Skip to main content

Stock balances on a date

Your system can ask the WMS how much stock it held on a given date — for example to reconcile it with your own records. This is a query, not a data type: balances are never imported and do not appear in the change feed.

The query needs the Change feed read capability.

POST /api/v1/integrations/stock-balances/as-of
{
  "externalSystemCode": "ERP_MAIN",
  "warehouseIds": [],
  "asOf": {"timeBasis": "accounting_date", "date": "2026-10-27"},
  "limit": 500
}
  • warehouseIds — WMS identifiers of the warehouses to report; an empty list means every warehouse your external system may work with.
  • asOf.date — the date, YYYY-MM-DD; required.
  • asOf.timeBasis — which date of a stock movement counts:
    • accounting_date — the accounting date of the document;
    • registration_date — when the movement was recorded in the WMS.
  • limit — rows per page, from 1 to 500 (200 when left out).
  • cursor — leave it out for the first page; for the next pages, send the nextCursor of the previous answer together with the same other fields.

The answer:

{
  "items": [
    {
      "warehouseId": {"int": "01a16373-d6be-7746-8eab-fc8e447bfea8", "ext": null},
      "productId": {"int": "01a16373-d3a9-7069-90ff-dfa694a27c0a", "ext": "prod-0042"},
      "lotId": {"int": "01a16373-da34-757f-b252-d20c58040bf0", "ext": null},
      "status": "AVAILABLE",
      "baseQuantity": "176.0000"
    }
  ],
  "nextCursor": "eyJ2ZXJzaW9uIjoyLCJ3YXJlaG91c2VJZCI6…",
  "hasMore": true
}
  • One row is the quantity of one product — with its feature, lot and owner when they apply — in one warehouse and stock status.
  • baseQuantity is in the product's base unit, written as a decimal number in a string. Convert it to a decimal type, not to a floating-point number.
  • Identifiers are {int, ext} pairs, as everywhere in what you read: see Building the payload.
  • Read the pages until hasMore is false. A page may hold a few rows more than limit: the rows of one product are not split between pages.

Code​

The function reads all pages and returns every row. It uses the client from API basics.

// Yields the stock balances on a date, row by row, reading page after page.
// date: 'YYYY-MM-DD'; timeBasis: 'accounting_date' or 'registration_date';
// warehouseIds: WMS identifiers of warehouses, or [] for all your warehouses.
async function* fetchStockBalances({date, timeBasis = 'accounting_date', warehouseIds = [], pageSize = 500}) {
  let cursor;
  do {
    const {body: page} = await wmsRequest('POST', '/api/v1/integrations/stock-balances/as-of', {
      body: {
        externalSystemCode: config.externalSystem,
        warehouseIds,
        asOf: {timeBasis, date},
        limit: pageSize,
        cursor, // undefined on the first page — left out of the JSON
      },
    });
    yield* page.items; // {warehouseId, productId, productFeatureId?, lotId?, ownerId?, status, baseQuantity}
    cursor = page.nextCursor;
    if (!page.hasMore) break;
  } while (cursor);
}

// Usage:
// for await (const row of fetchStockBalances({date: '2026-10-27'})) {
//   console.log(row.productId.ext ?? row.productId.int, row.status, Number(row.baseQuantity));
// }