Read orders, returns and stock

Lists are sorted by last update, oldest first, and paginated with a cursor. To keep a copy in sync:

1. The first time, read every page of GET /orders, following next_cursor until it is null.
2. Store the updated_at of the last order you saved.
3. Every few minutes, call GET /orders?updated_since=<that time> and read the pages again. You get every order created or changed since then. A change to a return does not update its order: keep returns in sync the same way with GET /returns.

let since = await loadCheckpoint(); // null the first time
let cursor = null;
do {
  const params = new URLSearchParams({ limit: "200" });
  if (since) params.set("updated_since", since);
  if (cursor) params.set("cursor", cursor);
  const page = await nucleo(`/orders?${params}`);
  for (const order of page.data) await upsertOrder(order); // by order.id
  if (page.data.length) await saveCheckpoint(page.data.at(-1).updated_at);
  cursor = page.next_cursor;
} while (cursor);

• updated_since includes the time you pass, so the last order you stored comes back once more: upsert by id.
• Keep status and updated_since the same while you follow a cursor; a different status answers 400 invalid_cursor.
• status filters by the public status (received, on_hold, in_fulfillment, shipped, delivered, cancellation_requested, cancelled). The table of statuses is in the reference.

For one order — for example when a customer calls — read it by number: GET /orders/1042 (the # can be omitted). GET /orders/1042/timeline tells what happened, oldest first.

GET /inventory answers for up to 100 items per call, by SKU or barcode, with the total available and the split per location:

curl "https://api-commerce.nucleoplatform.com/api/commerce/v1/inventory?sku=TEE-BLK-M,TEE-BLK-L" \
  -H "Authorization: Bearer $NUCLEO_COMMERCE_KEY"

• available is stock on hand minus what is reserved for open orders and the safety stock, never below zero.
• With channel=shopify (or the id of a sales channel connection), the channel's allocation rules apply too: only the locations it sells from, minus the pieces held for other channels, within its caps. Pre-order quantities are not included.
• Only locations with stock or reservations for the item are listed, and an SKU or barcode Nucleo does not know is left out of the answer. GET /locations gives the names and kinds of every location code.