{
"supplier_id": "sup_best_foods_01...",
"store_id": "str_main_01...",
"expected_delivery_at": "2026-08-14T10:00:00-05:00",
"notes": "Weekly protein order",
"idempotency_key": "0d4f1c9a-7c33-4d6e-9f2a-1b8e5a6c0d21",
"lines": [
{
"item_id": "itm_chicken_01...",
"qty": 10,
"qty_base": 10000,
"base_unit_id": "unit_g_01...",
"unit_to_base_factor": 1000,
"unit_label": "kg",
"unit_cost": 4.5
}
]
}
{
"external_supplier_id": "RUC-001234567",
"store_id": "str_main_01...",
"external_reference": "MOV-2026-00342",
"idempotency_key": "0d4f1c9a-7c33-4d6e-9f2a-1b8e5a6c0d21",
"lines": [
{
"external_item_id": "SAL-GRUESA-001",
"qty": 5,
"unit_code": "COSTAL-SAL",
"tax_amount": 2.5,
"total_amount": 27.5
}
]
}
{
"external_supplier_id": "RUC-001234567",
"store_id": "str_main_01...",
"external_reference": "MOV-2026-00342",
"lines": [
{
"supplier_sku": "SKU-CHICKEN-001",
"qty": 10,
"unit_code": "kg",
"total_amount": 55.0
}
]
}
{
"external_supplier_id": "RUC-001234567",
"store_tax_id": "0991234560001",
"external_reference": "MOV-2026-00342",
"external_user_id": "erp-user-42",
"lines": [
{
"supplier_sku": "SKU-CHICKEN-001",
"qty": 10,
"unit_code": "kg",
"total_amount": 55.0
}
]
}
{
"purchase_order": {
"id": "po_01j5k...",
"account_id": "acc_01...",
"vendor_id": "vnd_01...",
"supplier_id": "sup_best_foods_01...",
"store_id": "str_main_01...",
"status": "DRAFT",
"expected_delivery_at": "2026-08-14T15:00:00.000Z",
"submitted_at": null,
"confirmed_at": null,
"cancelled_at": null,
"closed_at": null,
"external_reference": null,
"notes": "Weekly protein order",
"metadata": {},
"created_at": "2026-08-11T12:00:00.000Z",
"updated_at": "2026-08-11T12:00:00.000Z",
"lines": [
{
"id": "pol_01...",
"item_id": "itm_chicken_01...",
"qty": 10,
"qty_base": 10000,
"base_unit_id": "unit_g_01...",
"unit_to_base_factor": 1000,
"unit_label": "kg",
"unit_cost": 4.5
}
]
}
}
{
"error": {
"kind": "purchase_order_supplier_external_id_not_found",
"message": "No supplier matches the provided external_supplier_id"
}
}
{
"error": {
"kind": "purchase_order_item_external_id_not_found",
"message": "One or more external_item_id values could not be resolved",
"details": { "external_item_ids": ["SAL-UNKNOWN-001"] }
}
}
{
"error": {
"kind": "purchase_order_store_external_id_not_found",
"message": "No active store matches the provided external_store_id"
}
}
{
"error": {
"kind": "purchase_order_store_tax_id_not_found",
"message": "No active store matches the provided store_tax_id"
}
}
{
"error": {
"kind": "purchase_order_store_tax_id_ambiguous",
"message": "Multiple active stores share the same tax_id — use store_id or external_store_id to disambiguate",
"details": { "tax_id": "0991234560001", "count": 3 }
}
}
{
"error": {
"kind": "purchase_order_qty_base_mismatch",
"message": "Client-provided qty_base does not match the server-derived value"
}
}
{
"error": {
"kind": "item_unit_not_found",
"message": "item_unit_id does not resolve to an active unit and qty_base was omitted"
}
}
Purchase Orders
Create purchase order
Creates a new purchase order in DRAFT status, optionally with initial lines. Returns 201 on creation, 200 when idempotency_key matched an existing PO.
POST
/
api
/
v1
/
public
/
vendors
/
{vendorId}
/
procurement
/
orders
{
"supplier_id": "sup_best_foods_01...",
"store_id": "str_main_01...",
"expected_delivery_at": "2026-08-14T10:00:00-05:00",
"notes": "Weekly protein order",
"idempotency_key": "0d4f1c9a-7c33-4d6e-9f2a-1b8e5a6c0d21",
"lines": [
{
"item_id": "itm_chicken_01...",
"qty": 10,
"qty_base": 10000,
"base_unit_id": "unit_g_01...",
"unit_to_base_factor": 1000,
"unit_label": "kg",
"unit_cost": 4.5
}
]
}
{
"external_supplier_id": "RUC-001234567",
"store_id": "str_main_01...",
"external_reference": "MOV-2026-00342",
"idempotency_key": "0d4f1c9a-7c33-4d6e-9f2a-1b8e5a6c0d21",
"lines": [
{
"external_item_id": "SAL-GRUESA-001",
"qty": 5,
"unit_code": "COSTAL-SAL",
"tax_amount": 2.5,
"total_amount": 27.5
}
]
}
{
"external_supplier_id": "RUC-001234567",
"store_id": "str_main_01...",
"external_reference": "MOV-2026-00342",
"lines": [
{
"supplier_sku": "SKU-CHICKEN-001",
"qty": 10,
"unit_code": "kg",
"total_amount": 55.0
}
]
}
{
"external_supplier_id": "RUC-001234567",
"store_tax_id": "0991234560001",
"external_reference": "MOV-2026-00342",
"external_user_id": "erp-user-42",
"lines": [
{
"supplier_sku": "SKU-CHICKEN-001",
"qty": 10,
"unit_code": "kg",
"total_amount": 55.0
}
]
}
{
"purchase_order": {
"id": "po_01j5k...",
"account_id": "acc_01...",
"vendor_id": "vnd_01...",
"supplier_id": "sup_best_foods_01...",
"store_id": "str_main_01...",
"status": "DRAFT",
"expected_delivery_at": "2026-08-14T15:00:00.000Z",
"submitted_at": null,
"confirmed_at": null,
"cancelled_at": null,
"closed_at": null,
"external_reference": null,
"notes": "Weekly protein order",
"metadata": {},
"created_at": "2026-08-11T12:00:00.000Z",
"updated_at": "2026-08-11T12:00:00.000Z",
"lines": [
{
"id": "pol_01...",
"item_id": "itm_chicken_01...",
"qty": 10,
"qty_base": 10000,
"base_unit_id": "unit_g_01...",
"unit_to_base_factor": 1000,
"unit_label": "kg",
"unit_cost": 4.5
}
]
}
}
{
"error": {
"kind": "purchase_order_supplier_external_id_not_found",
"message": "No supplier matches the provided external_supplier_id"
}
}
{
"error": {
"kind": "purchase_order_item_external_id_not_found",
"message": "One or more external_item_id values could not be resolved",
"details": { "external_item_ids": ["SAL-UNKNOWN-001"] }
}
}
{
"error": {
"kind": "purchase_order_store_external_id_not_found",
"message": "No active store matches the provided external_store_id"
}
}
{
"error": {
"kind": "purchase_order_store_tax_id_not_found",
"message": "No active store matches the provided store_tax_id"
}
}
{
"error": {
"kind": "purchase_order_store_tax_id_ambiguous",
"message": "Multiple active stores share the same tax_id — use store_id or external_store_id to disambiguate",
"details": { "tax_id": "0991234560001", "count": 3 }
}
}
{
"error": {
"kind": "purchase_order_qty_base_mismatch",
"message": "Client-provided qty_base does not match the server-derived value"
}
}
{
"error": {
"kind": "item_unit_not_found",
"message": "item_unit_id does not resolve to an active unit and qty_base was omitted"
}
}
string
required
API key with
inventory:write scope.string
required
Vendor UUID.
string
UUID of the receiving store. Exactly one of
store_id, external_store_id, or store_tax_id must be provided.string
Resolve the store by the cross-system external identifier. Mutually exclusive with
store_id and store_tax_id.string
Resolve the store by its fiscal identifier (RUC, CNPJ, CUIT, NIT, RUT, RFC…). Returns
422 if multiple active stores share the same value — use store_id or external_store_id to disambiguate. Mutually exclusive with store_id and external_store_id.string
UUID of the supplier. Exactly one of
supplier_id or external_supplier_id must be provided.string
External supplier identifier (e.g. RUC / tax id), resolved server-side. Mutually exclusive with
supplier_id.string
UUID of the receiving schedule this PO belongs to (optional).
string
Free-form order classification (max 64 chars).
string
ISO 8601 timestamp of the order cutoff.
string
ISO 8601 timestamp of the expected delivery.
string
Free-text notes (max 1024 chars).
object
Free-form extra data.
string
Client-supplied key (max 255 chars). Repeating the same key returns the existing PO with HTTP 200 instead of creating a duplicate. Recommended: one UUID v4 per business operation.
string
Client-supplied document reference (e.g. an ERP movement code, max 256 chars). Stored for lookup and display, filterable on the list endpoint. Not a deduplication key — use
idempotency_key for that.string
Caller’s user identifier for the audit trail. Optional on creation; required on
close.boolean
When
true, every line item must exist in the supplier’s catalog.object[]
Initial order lines (optional — you can add them later with
action=add-lines):Show line fields
Show line fields
string
UUID of the item. Exactly one of
item_id, external_item_id, or supplier_sku must be provided.string
External item id, resolved server-side. When used,
base_unit_id becomes optional.string
Supplier SKU (case-insensitive, max 128 chars). Resolved to the matching item in the order’s supplier catalog.
base_unit_id is also derived automatically.number
required
Ordered quantity in the entry unit.
number
Ordered quantity in the item’s base unit. Required unless
unit_code or item_unit_id is provided — in both cases the server derives it as qty × factor_to_base. If you send it anyway, it must match the derived value (tolerance 0.001) or the request fails with purchase_order_qty_base_mismatch (422).string
UUID of the base unit. Required unless
external_item_id or supplier_sku is used.number
Conversion factor from the entry unit to base.
string
UUID of an existing item unit. The server derives
qty_base from the unit’s factor_to_base — you don’t need to know the conversion factor. Returns item_unit_not_found (404) if the unit doesn’t resolve and qty_base was omitted. Mutually exclusive with unit_code and unit_label.string
Resolve the purchase unit by its integration code (case-insensitive). Mutually exclusive with
item_unit_id and unit_label.string
Free-form unit label (e.g.
"costal"), stored when item_unit_id is absent.boolean
When
true and unit_label is set, saves a new PURCHASE unit on the item for future reuse.number
Cost per unit (≥ 0).
number
Informational: tax amount for the line.
number
Informational: delivery / freight amount.
number
Informational: declared total amount.
number
Informational: commission / markup amount.
string
Line notes (max 512 chars).
object
Extra data per line.
object
The full purchase order detail: identifiers,
status, lifecycle timestamps (submitted_at, confirmed_at, cancelled_at, closed_at), actor fields, and lines[].{
"supplier_id": "sup_best_foods_01...",
"store_id": "str_main_01...",
"expected_delivery_at": "2026-08-14T10:00:00-05:00",
"notes": "Weekly protein order",
"idempotency_key": "0d4f1c9a-7c33-4d6e-9f2a-1b8e5a6c0d21",
"lines": [
{
"item_id": "itm_chicken_01...",
"qty": 10,
"qty_base": 10000,
"base_unit_id": "unit_g_01...",
"unit_to_base_factor": 1000,
"unit_label": "kg",
"unit_cost": 4.5
}
]
}
{
"external_supplier_id": "RUC-001234567",
"store_id": "str_main_01...",
"external_reference": "MOV-2026-00342",
"idempotency_key": "0d4f1c9a-7c33-4d6e-9f2a-1b8e5a6c0d21",
"lines": [
{
"external_item_id": "SAL-GRUESA-001",
"qty": 5,
"unit_code": "COSTAL-SAL",
"tax_amount": 2.5,
"total_amount": 27.5
}
]
}
{
"external_supplier_id": "RUC-001234567",
"store_id": "str_main_01...",
"external_reference": "MOV-2026-00342",
"lines": [
{
"supplier_sku": "SKU-CHICKEN-001",
"qty": 10,
"unit_code": "kg",
"total_amount": 55.0
}
]
}
{
"external_supplier_id": "RUC-001234567",
"store_tax_id": "0991234560001",
"external_reference": "MOV-2026-00342",
"external_user_id": "erp-user-42",
"lines": [
{
"supplier_sku": "SKU-CHICKEN-001",
"qty": 10,
"unit_code": "kg",
"total_amount": 55.0
}
]
}
{
"purchase_order": {
"id": "po_01j5k...",
"account_id": "acc_01...",
"vendor_id": "vnd_01...",
"supplier_id": "sup_best_foods_01...",
"store_id": "str_main_01...",
"status": "DRAFT",
"expected_delivery_at": "2026-08-14T15:00:00.000Z",
"submitted_at": null,
"confirmed_at": null,
"cancelled_at": null,
"closed_at": null,
"external_reference": null,
"notes": "Weekly protein order",
"metadata": {},
"created_at": "2026-08-11T12:00:00.000Z",
"updated_at": "2026-08-11T12:00:00.000Z",
"lines": [
{
"id": "pol_01...",
"item_id": "itm_chicken_01...",
"qty": 10,
"qty_base": 10000,
"base_unit_id": "unit_g_01...",
"unit_to_base_factor": 1000,
"unit_label": "kg",
"unit_cost": 4.5
}
]
}
}
{
"error": {
"kind": "purchase_order_supplier_external_id_not_found",
"message": "No supplier matches the provided external_supplier_id"
}
}
{
"error": {
"kind": "purchase_order_item_external_id_not_found",
"message": "One or more external_item_id values could not be resolved",
"details": { "external_item_ids": ["SAL-UNKNOWN-001"] }
}
}
{
"error": {
"kind": "purchase_order_store_external_id_not_found",
"message": "No active store matches the provided external_store_id"
}
}
{
"error": {
"kind": "purchase_order_store_tax_id_not_found",
"message": "No active store matches the provided store_tax_id"
}
}
{
"error": {
"kind": "purchase_order_store_tax_id_ambiguous",
"message": "Multiple active stores share the same tax_id — use store_id or external_store_id to disambiguate",
"details": { "tax_id": "0991234560001", "count": 3 }
}
}
{
"error": {
"kind": "purchase_order_qty_base_mismatch",
"message": "Client-provided qty_base does not match the server-derived value"
}
}
{
"error": {
"kind": "item_unit_not_found",
"message": "item_unit_id does not resolve to an active unit and qty_base was omitted"
}
}