Create purchase order

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

POST

api

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

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

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 purchase order