Get Started

Lot movements

Follow recorded receipts, shipments, and production activity with quantities and running balances kept with each named lot.

Access

GET /lot-movements uses lots:read and the acting person's current Product and Lot viewing access. Related identities have separate access requirements:

  • Purchase-order IDs, numbers, and types require purchase-orders:read and current Purchase Order viewing access.
  • Sales-order IDs and numbers require orders:read and current access to that order.
  • Customer identity requires customers:read and current access to that customer.
  • Supplier identity requires suppliers:read and current Supplier viewing access.

Work-order movements report their kind and workOrderVersion; their document ID and number remain null.

Choose a lot or period

Send from and to together as inclusive YYYY-MM-DD organization-calendar days covering at most 366 days. Alternatively, select a lotId or exact lotNumber without a date window. Do not send both lot selectors. A selected lot can also be narrowed by a date window.

curl "$SHELFCYCLE_API_BASE_URL/lot-movements?from=2026-10-01&to=2026-10-23&warehouseId=warehouse-id&limit=100" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"

Optional productIds is a comma-separated list of up to 120 exact product UUIDs and selects which lots are read. Other filters are warehouseId, customerId, and salesOrderId. Customer and sales-order filters require the matching read access. Add includeDirectShip=true or includePlaceholders=true when those lots belong in the review. limit accepts 1 to 100.

Read movements and balances

Each row includes occurredOn, direction (in or out), movementType, workflow, quantity, runningBalance, and its lot, product, warehouse, and quantityBasis. Movements within a lot are oldest first.

movementType is purchase_receipt, sales_shipment, production_output, production_input, or unclassified. workflow distinguishes production, warehouse_transfer, and relabeling when recorded. Production inputs and outputs remain production movements even when their workflow is a transfer or relabeling.

Read decimal-string quantities in the lot's stated package-count or base-unit basis. Do not add quantities across unrelated lots or units. Customer and sales-order filtering selects visible events after the running balance is calculated, so that balance still describes the full lot, not just the displayed customer's movements.

Keep coverage with the answer

meta.summary describes the complete matching population and repeats on every page. It reports event, lot, warehouse, basis, and group counts, grouped movement quantities, and limitationLotCounts. Do not add the summary again for each page.

meta.lots covers lots on the current page, with openingBalance, closingBalance, and any recorded limitations. Keep below_zero_balance, history_disagrees_with_on_hand, and header_inconsistent evidence with the affected lot rather than treating a movement-derived balance as a guaranteed current on-hand quantity. Use Lots for the stored current quantities and COA readiness.

Continue and refresh

When meta.nextCursor is present, send it by itself:

curl "$SHELFCYCLE_API_BASE_URL/lot-movements?cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY"

These are current-state reads. Retain meta.observedAt with the review and restart the original filtered request when a fresh view is needed.