{
"idempotency_key": "rcpt-2026-08-07-001",
"external_user_id": "user_receiving",
"store_id": "str_main_01...",
"supplier_id": "sup_best_foods_01...",
"reference": "INV-2026-1234",
"lines": [
{
"item_id": "itm_chicken_01...",
"qty": 10,
"qty_base": 10000,
"base_unit_id": "unit_g_01...",
"unit_id": "unit_kg_01...",
"unit_label": "kg",
"unit_to_base_factor": 1000,
"unit_cost": 4.5
}
]
}
{
"tracking_id": "trk_01j5k...",
"inventory_transaction_id": "txn_01j5k...",
"goods_receipt_id": "rcpt_01j5k...",
"idempotent": false
}
{
"error": {
"kind": "item_not_found",
"message": "Item not found",
"details": { "item_id": "itm_unknown..." }
}
}
Goods Receipts
Create goods receipt
Records inventory arriving from a supplier. Each line adds stock and optionally decrements a purchase order. Returns HTTP 202 — use the tracking_id to poll for final status.
POST
/
api
/
v1
/
public
/
vendors
/
{vendorId}
/
operations
/
goods-receipts
{
"idempotency_key": "rcpt-2026-08-07-001",
"external_user_id": "user_receiving",
"store_id": "str_main_01...",
"supplier_id": "sup_best_foods_01...",
"reference": "INV-2026-1234",
"lines": [
{
"item_id": "itm_chicken_01...",
"qty": 10,
"qty_base": 10000,
"base_unit_id": "unit_g_01...",
"unit_id": "unit_kg_01...",
"unit_label": "kg",
"unit_to_base_factor": 1000,
"unit_cost": 4.5
}
]
}
{
"tracking_id": "trk_01j5k...",
"inventory_transaction_id": "txn_01j5k...",
"goods_receipt_id": "rcpt_01j5k...",
"idempotent": false
}
{
"error": {
"kind": "item_not_found",
"message": "Item not found",
"details": { "item_id": "itm_unknown..." }
}
}
string
required
API key with
inventory:write scope.string
required
Vendor UUID.
string
required
Client-supplied key (1–128 chars). Duplicate submissions return the original response with
"idempotent": true.string
required
Actor identifier for audit trail.
string
UUID of the receiving store. Exactly one of
store_id or external_store_id must be provided.string
Your system’s store identifier. Used when you haven’t stored BOH UUIDs.
string
BOH UUID of the supplier.
string
Your system’s supplier identifier.
string
Invoice or delivery note number (max 200 chars).
string
UUID of the purchase order this receipt fulfills (optional).
object[]
required
Line items (1–500 lines):
Show line fields
Show line fields
string
BOH UUID of the item. Exactly one of
item_id or external_item_id required.string
Your system’s item identifier.
string
UUID of the PO line being fulfilled.
number
required
Received quantity in the given unit.
number
required
Received quantity converted to the item’s base unit.
string
required
UUID of the base unit.
string
UUID of the unit used for
qty.string
Human label for the unit (for display).
number
required
Conversion factor from
unit_id to base_unit_id.number
required
Cost per unit (in account currency, ≥ 0).
number
Precomputed total cost. Defaults to
qty × unit_cost.object
Free-form extra data.
string
Use this to poll for the final processing status.
string
UUID of the inventory transaction created.
string
UUID of the created goods receipt.
boolean
true if a previous identical submission was found.{
"idempotency_key": "rcpt-2026-08-07-001",
"external_user_id": "user_receiving",
"store_id": "str_main_01...",
"supplier_id": "sup_best_foods_01...",
"reference": "INV-2026-1234",
"lines": [
{
"item_id": "itm_chicken_01...",
"qty": 10,
"qty_base": 10000,
"base_unit_id": "unit_g_01...",
"unit_id": "unit_kg_01...",
"unit_label": "kg",
"unit_to_base_factor": 1000,
"unit_cost": 4.5
}
]
}
{
"tracking_id": "trk_01j5k...",
"inventory_transaction_id": "txn_01j5k...",
"goods_receipt_id": "rcpt_01j5k...",
"idempotent": false
}
{
"error": {
"kind": "item_not_found",
"message": "Item not found",
"details": { "item_id": "itm_unknown..." }
}
}