Menu

API reference

Inventory

The append-only stock ledger: ingredients, waste, counts, transfers, receipts, batches and reorder levels.

get

/v1/inventory/ingredients

Ingredients (tenant-wide); q matches the name; outlet is checked against the caller's scope

operationId listIngredients

Auth

Member token+Tenant header

Parameters

  • outletin querystringoptional
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
  • qin querystringoptional
  • limitin queryintegeroptional
  • cursorin querystringoptional
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Response 200

V1InventoryIngredientscontract v1.inventory.ingredients
  • itemsarray of objectrequired
    • ingredient_idUuid7required
    • namestringrequired
    • base_unitstringrequired
      pattern ^[a-z][a-z_]{0,15}$
    • shelf_life_daysinteger | nullrequired
      ≥ 1≤ 9007199254740991
    • tracked_by_batchbooleanrequired
    • activebooleanrequired
  • next_cursorUuid7 | nullrequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

post

/v1/inventory/ingredients

inventory.ingredient.upsert.v1 — create or edit an ingredient / stock record

operationId upsertIngredient

Auth

Member token+Tenant header

Request body

object
  • command_idUuid7required
  • idempotency_keystringrequired
    pattern ^[A-Za-z0-9_.:-]{8,100}$
  • typeconst "inventory.ingredient.upsert.v1"required
  • payloadInventoryIngredientUpsertV1required

Response 200

CommandResultcontract command-result
  • command_idUuid7required
  • typestringrequired
    pattern ^[a-z][a-z_]*(\.[a-z][a-z_]*)+\.v[1-9][0-9]*$
  • entity_idUuid7required
  • committed_atIsoDatetimerequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

get

/v1/inventory/waste

An outlet's waste log; business_date = the outlet's local day less its business-day cutoff

operationId listWaste

Auth

Member token+Tenant header

Parameters

  • outletin querystringrequired
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
  • business_datein querystring (date)optional
  • limitin queryintegeroptional
  • cursorin querystringoptional
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Response 200

V1InventoryWastecontract v1.inventory.waste
  • itemsarray of objectrequired
    • waste_idUuid7required
    • outlet_idUuid7required
    • ingredient_idUuid7required
    • batch_idUuid7 | nullrequired
    • qty_milliintegerrequired
      ≥ -9007199254740991≤ 9007199254740991
    • unitstringrequired
      pattern ^[a-z][a-z_]{0,15}$
    • reasonenum (5)required
      temperatureoverprepexpireddamagedother
    • notestring | nullrequired
    • recorded_byUuid7required
    • atIsoDatetimerequired
    • business_datestring (date)required
      pattern ^(?:(?:[0-9][0-9][2468][048]|[0-9][0-9][13579][26]|[0-9][0-9]0[48]|[02468][048]00|[13579][26]00)-02-29|[0-9]{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12][0-9]|3[01])|(?:0[469]|11)-(?:0[1-9]|[12][0-9]|30)|(?:02)-(?:0[1-9]|1[0-9]|2[0-8])))$
  • next_cursorUuid7 | nullrequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

post

/v1/inventory/waste

inventory.waste.record.v1 — log waste; core derives the waste movement

operationId recordWaste

Auth

Member token+Tenant header

Request body

object
  • command_idUuid7required
  • idempotency_keystringrequired
    pattern ^[A-Za-z0-9_.:-]{8,100}$
  • typeconst "inventory.waste.record.v1"required
  • payloadInventoryWasteRecordV1required

Response 200

CommandResultcontract command-result
  • command_idUuid7required
  • typestringrequired
    pattern ^[a-z][a-z_]*(\.[a-z][a-z_]*)+\.v[1-9][0-9]*$
  • entity_idUuid7required
  • committed_atIsoDatetimerequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

get

/v1/inventory/counts

Stock counts with their lines (expected beside counted), newest first

operationId listStockCounts

Auth

Member token+Tenant header

Parameters

  • outletin querystringoptional
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
  • statusin queryenum (3)optional
    opensubmittedcancelled
  • limitin queryintegeroptional
  • cursorin querystringoptional
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Response 200

V1InventoryCountscontract v1.inventory.counts
  • itemsarray of objectrequired
    • stock_count_idUuid7required
    • outlet_idUuid7required
    • counted_byUuid7required
    • counted_atIsoDatetimerequired
    • statusenum (3)required
      opensubmittedcancelled
    • linesarray of objectrequired
      • count_line_idUuid7required
      • ingredient_idUuid7required
      • batch_idUuid7 | nullrequired
      • expected_qty_milliintegerrequired
        ≥ -9007199254740991≤ 9007199254740991
      • counted_qty_milliintegerrequired
        ≥ -9007199254740991≤ 9007199254740991
      • unitstringrequired
        pattern ^[a-z][a-z_]{0,15}$
  • next_cursorUuid7 | nullrequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

post

/v1/inventory/counts

inventory.count.submit.v1 — a blind count; core derives count_adjust movements

operationId submitStockCount

Auth

Member token+Tenant header

Request body

object
  • command_idUuid7required
  • idempotency_keystringrequired
    pattern ^[A-Za-z0-9_.:-]{8,100}$
  • typeconst "inventory.count.submit.v1"required
  • payloadInventoryCountSubmitV1required

Response 200

CommandResultcontract command-result
  • command_idUuid7required
  • typestringrequired
    pattern ^[a-z][a-z_]*(\.[a-z][a-z_]*)+\.v[1-9][0-9]*$
  • entity_idUuid7required
  • committed_atIsoDatetimerequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

get

/v1/inventory/counts/{id}

One stock count with its lines

operationId getStockCount

Auth

Member token+Tenant header

Parameters

  • idin pathstringrequired
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Response 200

V1InventoryCountcontract v1.inventory.count
  • stock_count_idUuid7required
  • outlet_idUuid7required
  • counted_byUuid7required
  • counted_atIsoDatetimerequired
  • statusenum (3)required
    opensubmittedcancelled
  • linesarray of objectrequired
    • count_line_idUuid7required
    • ingredient_idUuid7required
    • batch_idUuid7 | nullrequired
    • expected_qty_milliintegerrequired
      ≥ -9007199254740991≤ 9007199254740991
    • counted_qty_milliintegerrequired
      ≥ -9007199254740991≤ 9007199254740991
    • unitstringrequired
      pattern ^[a-z][a-z_]{0,15}$

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

get

/v1/inventory/transfers

Transfers visible from either end (outlet = from or to), with their lines

operationId listTransfers

Auth

Member token+Tenant header

Parameters

  • outletin querystringoptional
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
  • statusin queryenum (3)optional
    sentreceivedcancelled
  • limitin queryintegeroptional
  • cursorin querystringoptional
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

Response 200

V1InventoryTransferscontract v1.inventory.transfers
  • itemsarray of objectrequired
    • transfer_idUuid7required
    • from_outlet_idUuid7required
    • to_outlet_idUuid7required
    • statusenum (3)required
      sentreceivedcancelled
    • sent_byUuid7required
    • sent_atIsoDatetimerequired
    • received_byUuid7 | nullrequired
    • received_atIsoDatetime | nullrequired
    • linesarray of objectrequired
      • transfer_line_idUuid7required
      • ingredient_idUuid7required
      • batch_idUuid7 | nullrequired
      • qty_milliintegerrequired
        ≥ -9007199254740991≤ 9007199254740991
      • unitstringrequired
        pattern ^[a-z][a-z_]{0,15}$
  • next_cursorUuid7 | nullrequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

post

/v1/inventory/transfers

inventory.transfer.create.v1 — send stock to another outlet (draftable); both ends in scope

operationId createTransfer

Auth

Member token+Tenant header

Request body

object
  • command_idUuid7required
  • idempotency_keystringrequired
    pattern ^[A-Za-z0-9_.:-]{8,100}$
  • typeconst "inventory.transfer.create.v1"required
  • payloadInventoryTransferCreateV1required

Response 200

CommandResultcontract command-result
  • command_idUuid7required
  • typestringrequired
    pattern ^[a-z][a-z_]*(\.[a-z][a-z_]*)+\.v[1-9][0-9]*$
  • entity_idUuid7required
  • committed_atIsoDatetimerequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

post

/v1/inventory/stock:receive

inventory.stock.receive.v1 — opening stock, optionally into new dated batches

operationId receiveOpeningStock

Auth

Member token+Tenant header

Request body

object
  • command_idUuid7required
  • idempotency_keystringrequired
    pattern ^[A-Za-z0-9_.:-]{8,100}$
  • typeconst "inventory.stock.receive.v1"required
  • payloadInventoryStockReceiveV1required

Response 200

CommandResultcontract command-result
  • command_idUuid7required
  • typestringrequired
    pattern ^[a-z][a-z_]*(\.[a-z][a-z_]*)+\.v[1-9][0-9]*$
  • entity_idUuid7required
  • committed_atIsoDatetimerequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

get

/v1/inventory/reorder-levels

Min / par levels at an outlet

operationId listReorderLevels

Auth

Member token+Tenant header

Parameters

  • outletin querystringrequired
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
  • ingredientin querystringoptional
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Response 200

V1InventoryReorderLevelscontract v1.inventory.reorder-levels
  • reorder_levelsarray of objectrequired
    • reorder_level_idUuid7required
    • outlet_idUuid7required
    • ingredient_idUuid7required
    • min_qty_milliintegerrequired
      ≥ 0≤ 9007199254740991
    • par_qty_milliintegerrequired
      ≥ 0≤ 9007199254740991
    • updated_atIsoDatetimerequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

post

/v1/inventory/reorder-levels

inventory.reorder_level.set.v1 — min / par for one ingredient at one outlet (draftable)

operationId setReorderLevel

Auth

Member token+Tenant header

Request body

object
  • command_idUuid7required
  • idempotency_keystringrequired
    pattern ^[A-Za-z0-9_.:-]{8,100}$
  • typeconst "inventory.reorder_level.set.v1"required
  • payloadInventoryReorderLevelSetV1required

Response 200

CommandResultcontract command-result
  • command_idUuid7required
  • typestringrequired
    pattern ^[a-z][a-z_]*(\.[a-z][a-z_]*)+\.v[1-9][0-9]*$
  • entity_idUuid7required
  • committed_atIsoDatetimerequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

post

/v1/inventory/batches:update

inventory.batch.update.v1 — correct a batch's expiry or MRP

operationId updateBatch

Auth

Member token+Tenant header

Request body

object
  • command_idUuid7required
  • idempotency_keystringrequired
    pattern ^[A-Za-z0-9_.:-]{8,100}$
  • typeconst "inventory.batch.update.v1"required
  • payloadInventoryBatchUpdateV1required

Response 200

CommandResultcontract command-result
  • command_idUuid7required
  • typestringrequired
    pattern ^[a-z][a-z_]*(\.[a-z][a-z_]*)+\.v[1-9][0-9]*$
  • entity_idUuid7required
  • committed_atIsoDatetimerequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

post

/v1/inventory/transfers/{id}:receive

inventory.transfer.receive.v1 — the receiving outlet books the stock in

operationId receiveTransfer

Auth

Member token+Tenant header

Parameters

  • idin pathstringrequired
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Request body

object
  • command_idUuid7required
  • idempotency_keystringrequired
    pattern ^[A-Za-z0-9_.:-]{8,100}$
  • typeconst "inventory.transfer.receive.v1"required
  • payloadInventoryTransferReceiveV1required

Response 200

CommandResultcontract command-result
  • command_idUuid7required
  • typestringrequired
    pattern ^[a-z][a-z_]*(\.[a-z][a-z_]*)+\.v[1-9][0-9]*$
  • entity_idUuid7required
  • committed_atIsoDatetimerequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

post

/v1/inventory/expired-sale-overrides

inventory.expired_sale.override.v1 — a manager or owner lets one cart line sell from one expired batch, where the country pack allows it

operationId issueExpiredSaleOverride

Auth

Member token+Tenant header

Request body

object
  • command_idUuid7required
  • idempotency_keystringrequired
    pattern ^[A-Za-z0-9_.:-]{8,100}$
  • typeconst "inventory.expired_sale.override.v1"required
  • payloadInventoryExpiredSaleOverrideV1required

Response 200

CommandResultcontract command-result
  • command_idUuid7required
  • typestringrequired
    pattern ^[a-z][a-z_]*(\.[a-z][a-z_]*)+\.v[1-9][0-9]*$
  • entity_idUuid7required
  • committed_atIsoDatetimerequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

get

/v1/inventory/movements

Stock movement rows for an outlet, newest first; kind and ref (the source row id) filter (T-092a)

operationId listStockMovements

Auth

Member token+Tenant header

Parameters

  • outletin querystringrequired
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
  • ingredientin querystringoptional
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
  • kindin queryenum (12)optional
    receiptsale_consumptionwastetransfer_outtransfer_incount_adjustsupplier_returnsale_returndonationsurplus_outsurplus_incares_reversal
  • refin querystringoptional
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
  • limitin queryintegeroptional
  • cursorin querystringoptional
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Response 200

V1InventoryMovementscontract v1.inventory.movements
  • movementsarray of objectrequired
    • movement_idUuid7required
    • outlet_idUuid7required
    • ingredient_idUuid7required
    • batch_idUuid7 | nullrequired
    • qty_milliintegerrequired
      ≥ -9007199254740991≤ 9007199254740991
    • unitstringrequired
      pattern ^[a-z][a-z_]{0,15}$
    • kindenum (12)required
      receiptsale_consumptionwastetransfer_outtransfer_incount_adjustsupplier_returnsale_returndonationsurplus_outsurplus_incares_reversal
    • ref_typestring | nullrequired
      pattern ^core\.[a-z_]+$
    • ref_idUuid7 | nullrequired
    • unit_costMoney | nullrequired
    • unit_cost_per_1000Money | nullrequired
    • expired_sale_override_idUuid7 | nullrequired
    • atIsoDatetimerequired
  • next_cursorUuid7 | nullrequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.

get

/v1/inventory/batches

Batches at an outlet with expiry and MRP, earliest expiry first

operationId listBatches

Auth

Member token+Tenant header

Parameters

  • outletin querystringrequired
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
  • ingredientin querystringoptional
    pattern ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$

Response 200

V1InventoryBatchescontract v1.inventory.batches
  • batchesarray of objectrequired
    • batch_idUuid7required
    • outlet_idUuid7required
    • ingredient_idUuid7required
    • batch_codestringrequired
      min length 1
    • expires_onstring (date) | nullrequired
      pattern ^(?:(?:[0-9][0-9][2468][048]|[0-9][0-9][13579][26]|[0-9][0-9]0[48]|[02468][048]00|[13579][26]00)-02-29|[0-9]{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12][0-9]|3[01])|(?:0[469]|11)-(?:0[1-9]|[12][0-9]|30)|(?:02)-(?:0[1-9]|1[0-9]|2[0-8])))$
    • received_atIsoDatetimerequired
    • mrpMoney | nullrequired

Errors

Every error body carries a code, a message and, where it applies, a reason_code. All error and reason codes.