Next Inventory REST API

The REST API of Next Inventory, the inventory component for Joomla 4, 5 and 6.

Base URL: https://<your-site>/api/index.php/v1/nextinventory

Authentication: create a token in Next Inventory → Configuration → REST API → Tokens and send it as Authorization: Bearer <token>. If your web server strips the Authorization header (some Apache

• PHP-FPM setups do), send X-NextInventory-Token: <token> instead.

A token acts as the user who created it. It can do only what its scopes allow AND what that user's Next Inventory role allows; every request goes through the same permission checks, validation and stock rules as the Next Inventory screens.

Responses: success is { "data": ..., "meta": { "total": n } } (meta on lists only); a create answers 201, a delete 204 with no body. Every failure is { "errors": [ { "title": "...", "code": "MACHINE_CODE", "meta": { ... } } ] }.

Stock is changed only through stock movements, transfers and adjustments — never by writing stock_quantity on an item — so every change is in the ledger (/transactions) and the FIFO/LIFO cost layers stay correct.

Rate limits: per token and per minute, reads (GET) and changes counted apart: 300 reads and 120 changes by default, set on REST API → Settings (0 = no limit). Every answer carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds); over a limit the answer is 429 RATE_LIMITED with Retry-After: <seconds>. More than 20 unknown tokens from one address within 5 minutes are answered 429 TOO_MANY_FAILED_LOGINS (a valid token never is).

Concurrent edits: reading one record (GET /items/{id} and the like) returns an ETag header, as does a successful change to it. Send it back as If-Match on PATCH, DELETE or an action, and the change is refused with 412 if someone else changed the record meanwhile. To learn when records change, subscribe a webhook rather than polling.

Safe retries: send an Idempotency-Key header on a POST, PATCH or DELETE and a retry after a timeout cannot run the request twice (see the parameter).

The same token also works on the administrator task lane (administrator/index.php?option=com_nextinventory&format=json&task=<controller.task>), which is the RPC interface the Next Inventory screens themselves use.

Base URL

{site}/api/index.php/v1/nextinventory

Authentication

Authorization: Bearer <your-api-token>

X-NextInventory-Token is accepted as an alternative — The same token, for servers that strip the Authorization header.

A Next Inventory API token (nxi_…), created under Configuration → REST API → Tokens.

Endpoints

Webhook events

Outbound events. When stock or a record changes, Next Inventory sends an HTTP POST to each webhook subscribed to that event, so another system can react without polling.

A webhook says something happened; the REST API reads the full record. To keep another system's stock in step, subscribe to stock.changed: it covers every way stock can change.

Errors

See also

• Getting Started guide — enabling the API, screenshots and a worked end-to-end example