Create Unit

POST /units

Create a unit

Scope units:write; role permission configuration.manage_units; needs the Units app. Required: title, code.

Request

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

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
`code`	`string`	No
`base_unit_id`	`integer`	No
`operator`	`string`	No	One of `*`, `/`, `+`, `-`.
`operation_value`	`number`	No
`published`	`integer`	No	One of `0`, `1`.

{
    "title": "string",
    "code": "string",
    "base_unit_id": 1,
    "operator": "*",
    "operation_value": 1.5,
    "published": 0
}

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/units" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"string","code":"string","base_unit_id":1,"operator":"*","operation_value":1.5,"published":0}'

PHP

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

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('API_TOKEN'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => '{"title":"string","code":"string","base_unit_id":1,"operator":"*","operation_value":1.5,"published":0}',
]);

$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/units", {
  method: 'POST',
  headers: {
    "Authorization": `Bearer ${API_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "title": "string",
    "code": "string",
    "base_unit_id": 1,
    "operator": "*",
    "operation_value": 1.5,
    "published": 0
  }),
});
const data = await response.json();