Identifiers & matching
You do not need our ids to send data. Your ERP, warehouse system or till sends the codes, barcodes and references it already has, and we find the matching record. This page says what each call matches on, in which order, and what happens when nothing matches.
The identifiers#
| Identifier | What it is |
|---|---|
| idinteger | Our id. Every response carries it. You can store it, but you never have to send it to write. |
| codestring | Your code: a product number, an SKU, a warehouse code. Products, variants, warehouses, store locations, catalogs and attribute definitions have one. Reconcile calls a variant code sku; stock rows call a warehouse code warehouse_code. |
| barcodestring | An EAN or other scannable code. Products, variants and loyalty cards have one. |
| external_refstring | Your system's own id for the record, when it is not the code: the row id in your ERP, for example. Variants, attribute definitions, store locations, customers, cards and orders have one. |
Rules that apply everywhere#
- Unique within your app. A code, barcode or external reference names one record of its kind in your app. Another app can use the same values.
- Exact match. Matching is case-sensitive and spaces count:
sku-1001does not findSKU-1001. We trim spaces from variant codes, barcodes and references when we store them, not when we look them up. The exceptions are the read helpersGET /products?code=andPOST /product/verify, which ignore case and surrounding spaces. - First hit wins. Where a call tries several identifiers, it tries them in the order listed below and uses the first one that finds a record. It does not check that the others agree, so send the identifier you are surest of.
- Keep identifiers stable. Changing a code in your system looks to us like a new record. Change it here too, in the same sync, or you will end up with two.
What each call matches on#
| Call and record | Tried in this order | When nothing matches |
|---|---|---|
| POST /int/products product | id, code, external_ref | The product is created. |
| POST /int/products variant | code, barcode, external_ref | The variant is created on the product. A variant of another product fails the product. |
| PUT /int/stocks variant | code, barcode, external_ref | The row fails; the other rows are written. |
| PUT /int/stocks warehouse | warehouse_code | The row fails. |
| POST /stock/reconcile | Variant code as sku; warehouse by warehouse_code | An unknown SKU fails its entry. An unknown warehouse fails the call with 404. |
| PUT /int/product_attributes product | One of its variants by code, barcode, external_ref | The whole call fails and nothing is written. |
| PUT /int/product_attributes definition | external_ref, together with product_attribute_def_id when you send it | The definition is created. |
| PUT /warehouse | code and id: both must match when you send both | The warehouse is created. |
| POST /product/verify | Variant by code or barcode, then product | The row comes back without ids. Nothing is ever written. |
Orders, customers, cards, catalogs and store locations match in their own ways; their pages say how: Orders, Customers, Cards, Catalogs, Locations.
Match products by code, not by external_ref. POST /int/products does not store a product's external_ref, so it only finds products that got one elsewhere. Variants store theirs. See Products.
Orders and customers: three-part ids#
Orders, customers and cards are stored in partitions. Each record is named by our id together with two partition numbers, data_part and time_part. They are not dates and they do not change for a record.
- Responses that return an order, a customer or a card include
data_partandtime_partnext toid. - Store all three. Calls that take an order or a customer by id ask for the other two as
dataPartandtimePart. - An order placed by a customer has the customer's
data_partandtime_part.
In practice#
- Give everything you create a code of your own, and send that code on every call.
- Pick one identifier per kind of record and use it everywhere. Mixing codes in one call and barcodes in the next works, but it is harder to reason about when something goes wrong.
- Before a first sync, send your codes to
POST /product/verifyto see which products we already have. - Never reuse a code for a different item, not even after deleting the old one.
Related#
- Products: products and variants, and how they are matched.
- Stock: rows that name a variant and a warehouse.
- Errors: what a failed row or a failed call looks like.
Last updated 1 October 2026 · API v2
Something wrong on this page?