Identifiers

Every id Manifold makes says what it names: a prefix, an underscore and a UUID.

An order's id

ord_0192f3a4-5e6f-7a8b-9c0d-1e2f3a4b5c6d

The rule

An id is <prefix>_<uuid>. The prefix is fixed for each kind of record, and every field, path and body that takes an id checks it. An order id is always ord_…, a location id always loc_….

Records Manifold makes get their id from Manifold, in the answer to the call that made them. A few writes take an id you make instead; see Ids you make.

Why

An id in the wrong place is refused before anything is read or written. Send a refund's id where a payment's goes and the call answers 400, so a mixed-up id can never touch the wrong record. The prefix also tells you what an id is when you meet it in a log, a fact or a URL.

This call sends an rfd_ id as a paymentId. It answers 400 with an empty body, and nothing is recorded:

curl · refused

curl -X POST 'https://fulfillment.getmanifold.io/orders/ord_0192f3a4-5e6f-7a8b-9c0d-1e2f3a4b5c6d/payments' \
  -H "Authorization: Bearer $MANIFOLD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "paymentId": "rfd_0192f3a4-8c2d-7e3f-9a40-5b6c7d8e9f0a",
  "amountCents": 7200,
  "method": "bank-transfer",
  "reference": "BANK-TXN-55102"
}'

Prefixes you will meet

org_: An organization. A sandbox's id starts org_test_.
usr_: A person.
loc_: A location, such as a warehouse or a shop.
itm_, cat_: A SKU's record, and a catalog.
po_, rcpt_: A purchase order, and one receipt of goods against it.
ord_, lin_, shp_, inv_: A sales order or quote, one of its lines, a parcel, and an invoice.
pay_, rfd_, wo_: A payment, a refund, and a write-off.
psn_, cmp_: A customer or supplier contact, and a company.
stk_: A stocktake.
imp_: An import job: a CSV staged, checked and then committed.
chn_: A sales channel, such as a Shopify store or a marketplace account.
app_, conn_: An app, and an app's link to an account it connects, such as one Shopify store.
evt_, tx_, req_: A fact, the write that recorded it, and the request that began it. See Facts and the journal.

Each operation's page names the ids it takes. Its OpenAPI document gives each one's pattern.

Ids you make

Some writes take an id you make for the record they create. That id is also the write's key: send the call again with the same id and it is applied once. See Idempotency and retries.

paymentId (pay_): Recording money received against an order: POST /orders/{orderId}/payments.
refundId (rfd_): Refunding an order: POST /orders/{orderId}/refunds.
receiptId (rcpt_): Receiving goods against a purchase order: POST /pos/{poId}/receipts.
stocktakeId (stk_): Starting a stocktake: POST /stocktakes.
writeOffId (wo_): Writing stock off: POST /write-offs.

To make one, put the prefix before a UUID. Any UUID version is accepted; Manifold's own are time-ordered (version 7). Make it once, when you decide to do the work, and save it with your own record before you send the call. Then a retry after a crash sends the same id.

JavaScript

const paymentId = `pay_${crypto.randomUUID()}`;

A write-off made with one. Idempotency and retries shows a payment, and what its other fields mean.

curl

curl -X POST 'https://fulfillment.getmanifold.io/write-offs' \
  -H "Authorization: Bearer $MANIFOLD_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "writeOffId": "wo_0192f3a4-9d3e-7f40-8b51-6c7d8e9f0a1b",
  "sku": "WIDGET-BLUE",
  "quantity": 2,
  "reason": "damaged"
}'

Ids made from your key

Some ids are worked out from what you send rather than made fresh. A sales order's id comes from your organization and the order's reference, and each line's id from the order and the line's position. So sending the same order twice never makes two orders, or two ids for one.

What is not an id

SKUs: A SKU is your own key for a product, and paths take it as it is: /items/WIDGET-BLUE. Manifold trims it and makes it upper case, so abc-1 is stored and matched as ABC-1.
Document numbers: A number such as SO-00042 is for people: it goes on the paperwork and in the admin. Calls name the record by its id.
Other systems' ids: A Shopify order id, a carrier's tracking number or a bank's reference is kept exactly as sent, with no prefix added.

What to do

Store ids whole, as strings, and compare them exactly. Do not read meaning into the UUID part.
Use the id field each answer returns. Do not build ids yourself, except the ones a write asks you to make.
On a 400, check each id's prefix against the field it went in.