Create Item

POST /items

Create an item

Scope items:write; role permission inventory.create. Required: title, item_type, category_id, stock_quantity, low_stock_threshold (send 0 for none). Custom fields are sent as cf_<field name> keys. Opening stock is better recorded with an add_stock movement so it reaches the ledger.

Request

POST https://example.com/api/index.php/v1/nextinventory/items

Parameters

Name	Type	In	Required	Description
`Idempotency-Key`	`string`	`header`	No	Optional. Any unique string (1 to 191 printable ASCII characters, no spaces; a UUID is ideal). The request runs once: a retry with the same key gets the first response back, with the header `Idempotent-Replayed: true`, instead of running again. Keys are kept for 24 hours per token. `409 IDEMPOTENCY_IN_PROGRESS` while the first request is still running; `422 IDEMPOTENCY_KEY_REUSED` if the key comes with a different request. A 5xx answer is not kept, so it can be retried with the same key. (min length 1, max length 191, pattern `^[\x21-\x7E]+$`)

Request body

Content type: application/json

Field	Type	Required	Description
`title`	`string`	No
`item_type`	`string`	No	One of `asset`, `consumable`, `sellable`.
`category_id`	`integer`	No
`warehouse_id`	`integer`	No
`unit_id`	`integer`	No
`stock_quantity`	`number`	No	Opening stock on create. Later changes go through stock movements.
`sku`	`string`	No
`barcode`	`string`	No
`serial_number`	`string`	No
`unit_price`	`number`	No
`low_stock_threshold`	`number`	No
`weight`	`number`	No
`weight_unit`	`string`	No
`track_weight`	`integer`	No	One of `0`, `1`.
`description`	`string`	No
`state`	`integer`	No	One of `0`, `1`.

{
    "title": "Cordless drill",
    "item_type": "asset",
    "category_id": 3,
    "warehouse_id": 1,
    "sku": "TL-0042",
    "stock_quantity": 0,
    "unit_price": 129.9,
    "low_stock_threshold": 2,
    "state": 1
}

Responses

`201` — Created.

{
    "data": {
        "id": 1
    }
}

Field	Type	Meaning
`data.id`	`integer`

Errors

Status	Code	When
`4`		A refusal. Common codes: `MISSING_TOKEN` / `INVALID_TOKEN` (401); `API_DISABLED`, `ACCOUNT_UNUSABLE`, `ACCESS_DENIED`, `TASK_NOT_ALLOWED`, `MISSING_SCOPE`, `APP_DISABLED`, `DEMO_LOCKED`, `FORBIDDEN` (403); `NOT_FOUND` (404); `BAD_REQUEST` / `INVALID_JSON` / `INVALID_IDEMPOTENCY_KEY` (400, validation and stock rules, with the reason in `title`); `IDEMPOTENCY_IN_PROGRESS` (409); `PRECONDITION_FAILED` (412, the record changed since the `If-Match` ETag was read); `IDEMPOTENCY_KEY_REUSED` (422); `RATE_LIMITED` / `TOO_MANY_FAILED_LOGINS` (429, with a `Retry-After` header in seconds); `SERVER_ERROR` (500).

Examples

curl

curl -s -X POST "https://example.com/api/index.php/v1/nextinventory/items" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Cordless drill","item_type":"asset","category_id":3,"warehouse_id":1,"sku":"TL-0042","stock_quantity":0,"unit_price":129.9,"low_stock_threshold":2,"state":1}'

PHP

<?php
$ch = curl_init('https://example.com/api/index.php/v1/nextinventory/items');

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('API_TOKEN'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => '{"title":"Cordless drill","item_type":"asset","category_id":3,"warehouse_id":1,"sku":"TL-0042","stock_quantity":0,"unit_price":129.9,"low_stock_threshold":2,"state":1}',
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

JavaScript

const API_TOKEN = process.env.API_TOKEN;

const response = await fetch("https://example.com/api/index.php/v1/nextinventory/items", {
  method: 'POST',
  headers: {
    "Authorization": `Bearer ${API_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "title": "Cordless drill",
    "item_type": "asset",
    "category_id": 3,
    "warehouse_id": 1,
    "sku": "TL-0042",
    "stock_quantity": 0,
    "unit_price": 129.9,
    "low_stock_threshold": 2,
    "state": 1
  }),
});
const data = await response.json();