Create goods receipt

{
  "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..." }
  }
}

POST

api

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

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..." }
  }
}

Overview

Identity

Stores

Suppliers

Catalog Items

Catalog Sync

Recipes

Goods Receipts

Stock Counts

Waste Events

Transfers

Production Batches

Tracking

Par Levels

Suggested Order

Purchase Orders

PO Lines

Webhooks

Create goods receipt