Raise a draft purchase order with a supplier

POST /pos

Raise a draft purchase order with a supplier, one line per SKU (quantity + expected unit cost in cents, in the order's currency — ISO 4217, default AUD).

The order is numbered from the organization's purchasing settings (number, e.g. PO-00042; the serial is consumed and never reused). supplierId optionally names the CRM company the order is placed with (supplier stays the name as shown on the document). expectedOn optionally records the day the supplier is expected to deliver; placedOn the day the order was really placed with the supplier when that was earlier (a phoned order, a migration) — lead time counts from it (400 DayInFuture for a day to come). A line naming a one-SKU kit (a case of 12) buys packs, priced per pack (409 KitNotBuyable for other kits, StockSkuOnTwoLines for two lines of one SKU). Appends purchasing.po-created. reference (the buyer's own PO number) is required and is the idempotency key: a retry with the same reference returns the order it already opened and appends nothing.

Access

Requires purchasing:write.

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

Retries

reference (the buyer's own PO number) is required and is the idempotency key: a retry with the same reference returns the order it already opened and appends nothing.

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

purchasing.po-created

What a fact is: Facts and the journal.

AI agent tool

Agents call this as purchasing_create_po (Purchasing: Create PO), in the purchasing toolset.

Connecting an agent: AI agents.

Example

From Procure to pay, step 4: Raise the purchase order.

curl

curl -X POST 'https://purchasing.getmanifold.io/pos' \
  -H "Authorization: Bearer $MANIFOLD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "reference": "PO-WIDGET-BLUE",
  "supplier": "Northwind Components",
  "supplierId": "cmp_01a15884-6399-7e5f-8a6b-1c2d3e4f5a6b",
  "lines": [
    {
      "sku": "WIDGET-BLUE",
      "quantity": 40
    }
  ]
}'

JavaScript (fetch)

const response = await fetch("https://purchasing.getmanifold.io/pos", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.MANIFOLD_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "reference": "PO-WIDGET-BLUE",
    "supplier": "Northwind Components",
    "supplierId": "cmp_01a15884-6399-7e5f-8a6b-1c2d3e4f5a6b",
    "lines": [
      {
        "sku": "WIDGET-BLUE",
        "quantity": 40
      }
    ]
  }),
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const answer = await response.json();

Request body · application/json

{
  "reference": "PO-WIDGET-BLUE",
  "supplier": "Northwind Components",
  "supplierId": "cmp_01a15884-6399-7e5f-8a6b-1c2d3e4f5a6b",
  "lines": [
    {
      "sku": "WIDGET-BLUE",
      "quantity": 40
    }
  ]
}

Response · 201 · application/json

{
  "id": "po_01a15876-6c9e-7b3a-8c4d-9e0f1a2b3c4d",
  "reference": "PO-WIDGET-BLUE",
  "supplier": "Northwind Components",
  "currency": "AUD",
  "number": "PO-00001",
  "serial": 1,
  "status": "draft",
  "lines": [
    {
      "sku": "WIDGET-BLUE",
      "ordered": 40,
      "received": 0,
      "unitCostCents": 1250
    }
  ],
  "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: purchasing-manager.openapi.json. Base URL https://purchasing.getmanifold.io.

Errors

Every refusal is a status and a JSON body whose _tag names it. A refused call changes nothing.

`400`

Refusal	What it means	What to do
`DayInFuture` day, today	The request was refused, and nothing changed.	Fix the request. Sending it again unchanged gets the same answer.

`401`

Refusal	What it means	What 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`

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

`403`

Refusal	What it means	What 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.

`409`

Refusal	What it means	What to do
`LineUncosted` skus	A line has no cost, and the purchase order needs one on every line. `skus` names them.	Set a cost on each line.
`KitNotBuyable` sku, reason	The request was refused. `reason` says why.	Nothing changed. Read the record, then decide.
`StockSkuOnTwoLines` sku, lines	The request was refused, and nothing changed.	Nothing changed. Read the record, then decide.
`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.

`502`

Refusal	What it means	What to do
`InventoryUnavailable` reason	The inventory service did not answer, so nothing changed.	Send the same request again, with the same key.

`503`

Refusal	What it means	What 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

Procure to pay, step 4: Raise the purchase order
Ordering stock in, and counting it when it lands, step 5: Raise a purchase order for more
Journal an additional cost on an order, step 12: Raise a purchase order