Docs menu

Inventory Manager API · items

Create a new inventory item with its master data

POST /items

Create a new inventory item with its master data, each field defaulted when omitted: a stock item is counted and sellable and posts to the chart's 1400 / 4000 / 5000 (accounts, GET /accounts); a service is never counted or tracked and opens at quantity 0.

Weight and box are sent to the sales channels that publish it. Appends an inventory.item-created event. 409 SkuConflict if the SKU exists, SkuNotAllowed if the organization's skuAlphabet refuses it, BarcodeConflict for another SKU's barcode, UnknownAccountCode for a code not in the chart. Idempotent on the SKU: a retried create meets 409 SkuConflict, never a second item.

Access

Requires stock:write or products:write.

Any one of these scopes is enough.

How scopes come from roles: Scopes and roles. Getting a token: Authentication and app tokens.

Retries

Idempotent on the SKU: a retried create meets 409 SkuConflict, never a second item.

A retry with the same key answers 201, with what the first call recorded.

Why every write carries a key: Idempotency and retries.

Facts appended

  • inventory.item-created

What a fact is: Facts and the journal.

AI agent tool

Agents call this as inventory_create_item (Inventory: Create item), in the stock toolset.

Connecting an agent: AI agents.

Example

From Procure to pay, step 1: Create the item.

curl 
curl -X POST 'https://inventory.getmanifold.io/items' \
  -H "Authorization: Bearer $MANIFOLD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "sku": "WIDGET-BLUE",
  "name": "Blue widget, 40mm",
  "quantity": 0
}'
JavaScript (fetch) 
const response = await fetch("https://inventory.getmanifold.io/items", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.MANIFOLD_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "sku": "WIDGET-BLUE",
    "name": "Blue widget, 40mm",
    "quantity": 0
  }),
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const answer = await response.json();
Request body · application/json 
{
  "sku": "WIDGET-BLUE",
  "name": "Blue widget, 40mm",
  "quantity": 0
}
Response · 201 · application/json 
{
  "id": "itm_01a15891-6c3f-7d19-9a3e-7c1b5d8e2f10",
  "sku": "WIDGET-BLUE",
  "name": "Blue widget, 40mm",
  "stock": [],
  "createdAt": "2026-08-17T09:00:00.000Z",
  "updatedAt": "2026-08-17T09:00:00.000Z"
}

The panel writes this call in other languages. It does not send it: Manifold's APIs do not take calls from a web page on another site, so run the call from your own code or terminal. The whole API as OpenAPI: inventory-manager.openapi.json. Base URL https://inventory.getmanifold.io.

Errors

Every refusal is a status and a JSON body whose _tag names it. A refused call changes nothing. Some can answer a retry of a call that already worked: they are marked.

401

RefusalWhat it meansWhat to do
Unauthorized reason The token is missing, expired or not one Manifold issued.Get a fresh token and send the call again.
TokenAlreadyUsed tokenId A single-use app token was already spent.Mint a new token for this call.

402

RefusalWhat it meansWhat to do
SubscriptionRequired status The organization's subscription has lapsed, so writes are refused.An owner settles billing. Reads still work meanwhile.

403

RefusalWhat it meansWhat to do
TenantRequired userId The token names no organization.Choose the organization, then get a new token.
ScopeRequired required The token's roles do not grant the scope this call needs.Ask an owner or admin for a role that grants it.

404

RefusalWhat it meansWhat to do
LocationNotFound locationId No such record in this organization.Check the id in the path or the body.

409

RefusalWhat it meansWhat to do
SkuConflict sku Can answer a retryAnother item already has this SKU.If this answers a retry, your first call probably landed. Use another SKU, or update the existing item.
SkuNotAllowed sku, alphabet, allowed The SKU has characters this organization's SKU alphabet does not allow. allowed lists them.Change the SKU, or an owner widens the alphabet in Settings › General.
BarcodeConflict barcode, sku Another SKU already has this barcode. sku names it.Use another barcode, or take it off the other SKU first.
LocationArchived locationId The location is archived, and an archived location takes no changes or stock.Use an active location.
UnknownAccountCode role, code An account code is not in the chart of accounts.Use a code the chart holds, or add the account first.
MirroredFromSource source This area is fed by your source system until the organization goes live.Make the change in the source system, or go live first.

503

RefusalWhat it meansWhat to do
RequestLogUnavailable tokenId, reason The service could not record the request, so it did nothing.Send the same request again, with the same key.

How refusals work everywhere: Errors.

Used in