Create Unit - Plugixa Inventory for WordPress

Create Unit - Plugixa Inventory

POST /plugixa-inventory/v1/units

Create a unit of measurement, on its own or converting to a base unit.

The user needs the plugixa_inventory_create capability (administrators have every inventory capability). With Pro Roles and permissions enforcing, their role must also allow creating units. Needs Plugixa Inventory Pro with the Units of measurement app on in Plugixa Inventory -> App Manager; with it off, this route answers 404.

Request

POST https://your-site.example/wp-json/plugixa-inventory/v1/units

Request body

Content type: application/json

Field	Type	Required	Description
`code`	`string`	Yes	The short form shown on lines, such as `kg` or `pcs`. Letters, digits, `-`, `_`, `/` and `%` only. Must be unique among live units. At most 20 characters.
`name`	`string`	Yes	Must not be blank. At most 100 characters.
`base_unit_id`	`integer`	No	A live unit this one converts to. `0` or `null` for a base unit of its own.
`operator`	`string`	No	`*`, `/`, `+` or `-`. Required with `base_unit_id`.
`operation_value`	`number`	No	Applied with `operator` to turn a quantity in this unit into the base unit. Not `0` with `*` or `/`.
`status`	`string`	No	`published` (the default) or `unpublished`.

With base_unit_id, one of this unit is operation_value of the base unit through operator: "*" and 12 make a box of 12 pieces. Without a base unit, operator and operation_value are cleared. A chain may not loop back on itself.

{
  "code": "box12",
  "name": "Box of 12",
  "base_unit_id": 1,
  "operator": "*",
  "operation_value": 12
}

Responses

`201` Created. `data` is the new unit.

{
  "success": true,
  "data": {
    "id": 4,
    "code": "box12",
    "name": "Box of 12",
    "base_unit_id": 1,
    "operator": "*",
    "operation_value": 12.0,
    "status": "published",
    "created_by": 1,
    "modified_by": 1,
    "created_at": "2026-11-12 09:30:00",
    "modified_at": "2026-11-12 09:30:00",
    "deleted_at": null,
    "base_unit_code": "pcs"
  }
}

Field	Type	Meaning
`data.id`	`integer`	The new unit’s id
`data.base_unit_id`	`integer\|null`	The base unit, or `null`
`data.base_unit_code`	`string\|null`	The base unit’s code
`data.operation_value`	`number`	The conversion value

Errors

Status	Code	When
`422`	`plugixa_inventory_missing_name`	`name` is missing or blank.
`422`	`plugixa_inventory_missing_code`	`code` is missing or blank.
`422`	`plugixa_inventory_invalid_choice`	`status` or `operator` is not one of the allowed values. `data.allowed` lists them.
`422`	`plugixa_inventory_not_a_number`	`operation_value` is not a number.
`422`	`plugixa_inventory_too_long`	A text field is longer than its column. `data.field` names it and `data.max` gives the limit.
`422`	`plugixa_inventory_invalid_code`	`code` contains a character that is not allowed.
`409`	`plugixa_inventory_duplicate_code`	Another live unit already uses this `code`.
`422`	`plugixa_inventory_unknown_unit`	`base_unit_id` is not a live unit.
`422`	`plugixa_inventory_unit_self_reference`	`base_unit_id` is this unit.
`422`	`plugixa_inventory_missing_operator`	`base_unit_id` is set without a valid `operator`.
`422`	`plugixa_inventory_invalid_operation_value`	`operation_value` is `0` with `*` or `/`.
`422` / `409`	`plugixa_inventory_unit_cycle`	The base unit would make the chain circular (`422`), or is already part of a circular chain (`409`).
`500`	`plugixa_inventory_insert_failed`	The database refused to save the unit.

Plus the errors every endpoint can return.

Examples

curl -s -X POST "https://your-site.example/wp-json/plugixa-inventory/v1/units" \
  -u "admin:$WP_APP_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"code":"box12","name":"Box of 12","base_unit_id":1,"operator":"*","operation_value":12}'

<?php
$ch = curl_init('https://your-site.example/wp-json/plugixa-inventory/v1/units');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD        => 'admin:' . getenv('WP_APP_PASSWORD'),
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode([
        'code'            => 'box12',
        'name'            => 'Box of 12',
        'base_unit_id'    => 1,
        'operator'        => '*',
        'operation_value' => 12,
    ]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

const auth = 'Basic ' + btoa(`admin:${process.env.WP_APP_PASSWORD}`);
const response = await fetch('https://your-site.example/wp-json/plugixa-inventory/v1/units', {
  method: 'POST',
  headers: { 'Authorization': auth, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    code: 'box12',
    name: 'Box of 12',
    base_unit_id: 1,
    operator: '*',
    operation_value: 12,
  }),
});
const { data } = await response.json();