Create Purchase Order

POST

/purchase_orders

🚀 Paid plan only

Creates a purchase order. The PO number is auto-generated if omitted.

Parameters

Header Parameters

x-api-key

string

E.g. 123

Example

123

Request Body

object

purchase_order

required

object

supplier_id

required

Supplier ID. Required; must belong to the company.

integer

destination_warehouse_id

required

Warehouse ID stock is delivered to. Required; must belong to the company.

integer

state

Lifecycle state: draft -> active -> completed.

string

Allowed values: draft active completed

number

PO number. Auto-generated if blank.

string

reference_number

Must be unique per company.

string

expected_date

Expected delivery date (must fall between 2010-01-01 and 2035-01-01).

string format: date-time

currency_code

Default GBP. Cannot be changed once the PO is active.

string

currency_rate

number

estimated_delivery_days

Auto-calculated from expected_date if omitted.

integer

note

string

shipping_and_handling

number

send_to_supplier

boolean

send_supplier_report_email

Emails the supplier report on save when the PO is active.

boolean

supplier_report_format

Format for the supplier report. Default pdf.

string

shipping_address_line_1

string

shipping_address_line_2

string

shipping_address_town

string

shipping_address_state

string

shipping_address_postcode

string

shipping_address_country

string

billing_address_line_1

string

billing_address_line_2

string

billing_address_town

string

billing_address_state

string

billing_address_postcode

string

billing_address_country

string

purchase_order_product_variants_attributes

Line items.

Array<object>

object

id

Existing line item ID (update requests only).

integer

product_variant_id

Must exist in the company and not be deleted. Required for create requests.

integer

quantity

Must be greater than 0. Required for create requests.

integer

cost

Unit cost. Must be greater than 0. Required for create requests.

number

tax_rate

Required for create requests.

number

display_position

integer

shipped

boolean

supplier_reference_number

Updates the supplier product variant reference.

string

supplier_title

Updates the supplier product variant title.

string

received_quantity

Update requests only — increments the received count for the line item. Cannot be negative.

integer

Example

{
  "purchase_order": {
    "supplier_id": 1748,
    "destination_warehouse_id": 1784,
    "expected_date": "2026-02-01T00:00:00Z",
    "currency_code": "GBP",
    "note": "Restock order",
    "shipping_and_handling": 12.5,
    "purchase_order_product_variants_attributes": [
      {
        "product_variant_id": 1226617,
        "quantity": 10,
        "cost": 9.99,
        "tax_rate": 0.2
      }
    ]
  }
}

Responses

201

Created. Returns the new purchase order (same shape as the list items).

object

id

number

number

string

state

string

supplier_id

number

destination_warehouse_id

number

line_items

Array<object>

object

Example

{
  "id": 492,
  "number": "PO-0000002",
  "state": "draft",
  "supplier_id": 1748,
  "destination_warehouse_id": 1784,
  "line_items": []
}

400

Validation failed (missing supplier/warehouse, invalid line item cost/quantity/tax_rate, duplicate reference_number, or IDs not found in the company). Returns an array of error messages.