Create Item - Plugixa Inventory for WordPress

POST /plugixa-inventory/v1/items

Create an item in the catalogue. It starts with nothing on hand.

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 items.

Request

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

Request body

Content type: application/json

Field	Type	Required	Description
`name`	`string`	Yes	Must not be blank. At most 255 characters.
`sku`	`string`	No	Letters, digits, `.`, `-`, `_` and `/` only. Must be unique among live items. At most 100 characters.
`barcode`	`string`	No	Same characters as `sku`. Must be unique among live items. At most 100 characters.
`serial_number`	`string`	No	Free text. At most 255 characters.
`item_type`	`string`	No	`asset`, `consumable` (the default) or `sellable`. It decides which stock movements can carry the item.
`category_id`	`integer`	No	A live category. `0` or `null` for none.
`default_warehouse_id`	`integer`	No	A live warehouse. `0` or `null` for none.
`unit_id`	`integer`	No	A live unit of measurement PRO. On a site without units, any value other than `0` or `null` is refused.
`image_id`	`integer`	No	The id of an image in the media library.
`reorder_level`	`number`	No	The item counts as low stock at or below this. `0` (the default) means no level. Not negative.
`unit_price`	`number`	No	Sale price. Not negative.
`cost_price`	`number`	No	Cost price. Not negative.
`weight`	`number`	No	Not negative.
`weight_unit`	`string`	No	`mg`, `g`, `kg`, `t`, `oz` or `lb`. Defaults to the default weight unit in the settings.
`track_weight`	`boolean`	No	Defaults to the “track weight by default” setting.
`status`	`string`	No	`published` (the default) or `unpublished`.
`description`	`string`	No	HTML. Tags not allowed in a WordPress post are removed.
`assigned_user_id`	`integer`	No	An existing WordPress user. `0` or `null` for none.

Only name is required. On hand cannot be set here: stock_quantity and weight_base are worked out for you, and values sent for them are ignored. To put stock on the shelf, finalize a stock movement.

{
  "name": "Printer paper A4",
  "sku": "PAP-A4",
  "barcode": "3045140105502",
  "item_type": "consumable",
  "category_id": 3,
  "default_warehouse_id": 1,
  "reorder_level": 20,
  "unit_price": 6.9,
  "cost_price": 4.2,
  "weight": 2.5,
  "weight_unit": "kg"
}

Responses

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

{
  "success": true,
  "data": {
    "id": 42,
    "name": "Printer paper A4",
    "sku": "PAP-A4",
    "barcode": "3045140105502",
    "serial_number": "",
    "item_type": "consumable",
    "category_id": 3,
    "default_warehouse_id": 1,
    "unit_id": null,
    "image_id": null,
    "stock_quantity": 0.0,
    "reorder_level": 20.0,
    "unit_price": 6.9,
    "cost_price": 4.2,
    "weight": 2.5,
    "weight_unit": "kg",
    "weight_base": 2.5,
    "track_weight": false,
    "status": "published",
    "description": "",
    "custom_fields": null,
    "assigned_user_id": null,
    "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,
    "image_url": null,
    "image_url_medium": null,
    "category_name": "Office supplies",
    "warehouse_name": "Main warehouse",
    "unit_name": null
  }
}

Field	Type	Meaning
`data.id`	`integer`	The new item’s id
`data.stock_quantity`	`number`	Always `0.0` on a new item
`data.weight_base`	`number`	The weight in kilograms
`data.category_name`	`string\|null`	The category’s name
`data.warehouse_name`	`string\|null`	The default warehouse’s name
`data.created_at`	`string`	UTC datetime

Errors

Status	Code	When
`422`	`plugixa_inventory_missing_name`	`name` is missing or blank.
`422`	`plugixa_inventory_invalid_choice`	`item_type`, `status` or `weight_unit` is not one of the allowed values. `data.allowed` lists them.
`422`	`plugixa_inventory_not_a_number`	`reorder_level`, `unit_price`, `cost_price` or `weight` is not a number. `data.field` names it.
`422`	`plugixa_inventory_negative_number`	One of those numbers is negative.
`422`	`plugixa_inventory_number_too_large`	One of those numbers is too large to store.
`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_identifier`	`sku` or `barcode` contains a character other than letters, digits, `.`, `-`, `_` and `/`.
`409`	`plugixa_inventory_duplicate_identifier`	Another live item already uses this `sku` or `barcode`. `data.conflict_id` is that item.
`422`	`plugixa_inventory_unknown_reference`	`category_id`, `default_warehouse_id` or `unit_id` is not a live record. `data.field` names it.
`422`	`plugixa_inventory_invalid_image`	`image_id` is not in the media library.
`422`	`plugixa_inventory_unknown_user`	`assigned_user_id` is not a WordPress user.
`500`	`plugixa_inventory_insert_failed`	The database refused to save the item.

Plus the errors every endpoint can return.

Examples

curl -s -X POST "https://your-site.example/wp-json/plugixa-inventory/v1/items" \
  -u "admin:$WP_APP_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name":"Printer paper A4","sku":"PAP-A4","barcode":"3045140105502","item_type":"consumable","category_id":3,"default_warehouse_id":1,"reorder_level":20,"unit_price":6.9,"cost_price":4.2,"weight":2.5,"weight_unit":"kg"}'

<?php
$ch = curl_init('https://your-site.example/wp-json/plugixa-inventory/v1/items');
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([
        'name'                 => 'Printer paper A4',
        'sku'                  => 'PAP-A4',
        'barcode'              => '3045140105502',
        'item_type'            => 'consumable',
        'category_id'          => 3,
        'default_warehouse_id' => 1,
        'reorder_level'        => 20,
        'unit_price'           => 6.9,
        'cost_price'           => 4.2,
        'weight'               => 2.5,
        'weight_unit'          => 'kg',
    ]),
]);
$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/items', {
  method: 'POST',
  headers: { 'Authorization': auth, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Printer paper A4',
    sku: 'PAP-A4',
    barcode: '3045140105502',
    item_type: 'consumable',
    category_id: 3,
    default_warehouse_id: 1,
    reorder_level: 20,
    unit_price: 6.9,
    cost_price: 4.2,
    weight: 2.5,
    weight_unit: 'kg',
  }),
});
const { data } = await response.json();