curl --request PUT \
  --url https://{companyName}.api.joinluminous.com/external/api/v1/purchase-orders/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "order_status": "completed"
}
'

{
  "data": {
    "id": 123,
    "order_numbers": [
      "<string>"
    ],
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "order_status": "active",
    "order_date": "2023-12-25",
    "invoice_date": "2023-12-25",
    "arrival_due_date": "2023-12-25",
    "requested_ship_date": "2023-12-25",
    "original_arrival_due_date": "2023-12-25",
    "shipment_type": "Air",
    "override_transit_days": 123,
    "order_type": 123,
    "incoterm": "<string>",
    "tracking_info": "<string>",
    "payment_terms": "<string>",
    "supplier_id": 123,
    "item_count": 123,
    "total_qty_ordered": 123,
    "total_qty_received": 123,
    "total_qty_remaining": 123,
    "receipt_status": "awaiting_shipment",
    "order_cost": 123,
    "total_tax": 123,
    "total_shipping_cost": 123,
    "total_cost": 123,
    "total_paid": 123,
    "total_due": 123,
    "total_volume_cbm": 123,
    "total_weight_kg": 123,
    "lines_missing_dimensions": 123,
    "volume_target_cbm": 123,
    "volume_remaining_cbm": 123,
    "volume_fill_percent": 123,
    "down_payment": 123,
    "public_note": "<string>",
    "private_note": "<string>",
    "starred": true,
    "items": [
      {
        "id": 123,
        "purchase_order_id": 123,
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z",
        "quantity": 123,
        "unit_price": 123,
        "unit": "<string>",
        "tax": 123,
        "discount_amount": 123,
        "line_total": 123,
        "expected_ship_date": "2023-12-25",
        "expected_arrival_date": "2023-12-25",
        "requested_ship_date": "2023-12-25",
        "arrival_due_date": "2023-12-25",
        "shipment_type": "Air",
        "original_arrival_due_date": "2023-12-25",
        "override_transit_days": 123,
        "quantity_received": 123,
        "received_quantity": 123,
        "quantity_ordered": 123,
        "quantity_shipped": 123,
        "quantity_billed": 123,
        "quantity_allocated": 123,
        "quantity_released": 123,
        "under_covered_quantity": 123,
        "remaining_to_ship": 123,
        "remaining_to_receive": 123,
        "open_quantity": 40,
        "closed_at": null,
        "close_reason": null,
        "available_to_allocate": 123,
        "volume_cbm": 123,
        "line_volume_cbm": 123,
        "weight_kg": 123,
        "line_weight_kg": 123,
        "allocations": [
          {
            "sales_order_id": 123,
            "sales_order_number": "<string>",
            "quantity_allocated": 123,
            "quantity_released": 123,
            "peg_ids": [
              123
            ]
          }
        ],
        "source_sku": "<string>",
        "product": {
          "id": 123,
          "name": "<string>",
          "description": "<string>",
          "retail_price": 123,
          "wholesale_price": 123,
          "unit_cost": 123,
          "product_weight": 123,
          "product_length": 123,
          "product_width": 123,
          "product_height": 123,
          "sellable": true,
          "discontinued": true,
          "image_url": "<string>",
          "variant_attributes": {},
          "sku": "<string>",
          "upc": "<string>",
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z"
        },
        "base_unit_of_measure": {
          "id": 123,
          "name": "<string>",
          "abbreviation": "<string>"
        },
        "ordered_unit_of_measure": {
          "id": 123,
          "name": "<string>",
          "abbreviation": "<string>"
        },
        "lot": {
          "id": 123,
          "lot_number": "<string>",
          "expiration_date": "2023-12-25"
        }
      }
    ],
    "supplier": {
      "id": 123,
      "status": 123,
      "name": "<string>",
      "description": "<string>",
      "street_address": "<string>",
      "city": "<string>",
      "state": "<string>",
      "zip": "<string>",
      "country": "<string>",
      "contact_name": "<string>",
      "contact_email": "<string>",
      "contact_phone": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "custom_fields": {
        "Region": "Southwest",
        "Preferred Carrier": "UPS"
      }
    },
    "payments": [
      {
        "id": 123,
        "payment_date": "2023-12-25",
        "payment_type": "cash",
        "paid_amount": 123,
        "remarks": "<string>",
        "external_id": "<string>",
        "created_by": {
          "id": 123,
          "name": "<string>"
        },
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z"
      }
    ],
    "ship_to": {
      "address_1": "<string>",
      "address_2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "zip": "<string>",
      "country": "<string>",
      "default_ship_to_address": "ship_to_address"
    },
    "warehouse_id": 123,
    "location_id": 123,
    "warehouse": {
      "id": 123,
      "name": "<string>"
    },
    "location": {
      "id": 123,
      "name": "<string>"
    },
    "tags": [
      {
        "id": 123,
        "name": "<string>",
        "description": "<string>",
        "icon": "<string>",
        "color": "<string>"
      }
    ],
    "fulfillment_orders": [
      {
        "id": 123,
        "order_number": "<string>",
        "order_status": "<string>"
      }
    ],
    "custom_fields": {}
  }
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

Purchase Orders

Update a purchase order

Update an existing purchase order. All fields are optional - only provided fields will be updated.

Key Features

Partial updates supported - only include fields you want to change
Items can be added, updated, or removed
If items array is provided, it replaces all existing items
If payments array is provided, it replaces all existing payments
Totals are automatically recalculated after updates
Stock count updates - incoming quantities are automatically updated when items change

Product Identification

For each line item, you must provide either:

product_id: The internal product ID
sku: The product SKU (supports both internal SKU and alternate SKUs)

Inventory-Tracked Products Only

Every line item must reference an inventory-tracked product (type PRODUCT or KIT). Non-inventory items (e.g. service or fee SKUs) are rejected with a 422 on items.{index}.product — record those charges as an extra cost on the purchase order instead. When items is provided, it is validated before anything is written, so a rejected request leaves the purchase order and its existing lines unchanged.

Updating Items

To update an existing item, include its id in the item object. To add a new item, omit the id field. To remove an item, omit it from the items array.

Order Status Values

Valid order statuses include: active, completed, deleted

Total Calculation

The order cost (order_cost) is automatically recalculated as: sum of (item quantities × unit prices) + additional fees

Additional fees are the PO’s persisted extra costs, including fees added automatically by matching cost rules (e.g. tariffs) when the order is saved. If a save adds or removes a cost-rule fee, order_cost, total_cost, and total_due move by that amount.

The order total (total_cost) is automatically recalculated as: order_cost + total_tax + total_shipping_cost

Note: order_cost, total_cost, total_paid, and total_due are calculated automatically on the backend and cannot be edited directly.

Payments

If payments array is provided, it replaces all existing payments for the order. Totals are automatically recalculated after payments are updated.

If any existing payment on the order records an active vendor prepayment, the replace is refused with a 422 (“This purchase order has payment(s) recording prepayment #N…”) and no payments are changed. Void the prepayment instead — replacing the payments would leave the prepayment balance in place.

PUT

purchase-orders

{id}

curl --request PUT \
  --url https://{companyName}.api.joinluminous.com/external/api/v1/purchase-orders/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "order_status": "completed"
}
'

{
  "data": {
    "id": 123,
    "order_numbers": [
      "<string>"
    ],
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "order_status": "active",
    "order_date": "2023-12-25",
    "invoice_date": "2023-12-25",
    "arrival_due_date": "2023-12-25",
    "requested_ship_date": "2023-12-25",
    "original_arrival_due_date": "2023-12-25",
    "shipment_type": "Air",
    "override_transit_days": 123,
    "order_type": 123,
    "incoterm": "<string>",
    "tracking_info": "<string>",
    "payment_terms": "<string>",
    "supplier_id": 123,
    "item_count": 123,
    "total_qty_ordered": 123,
    "total_qty_received": 123,
    "total_qty_remaining": 123,
    "receipt_status": "awaiting_shipment",
    "order_cost": 123,
    "total_tax": 123,
    "total_shipping_cost": 123,
    "total_cost": 123,
    "total_paid": 123,
    "total_due": 123,
    "total_volume_cbm": 123,
    "total_weight_kg": 123,
    "lines_missing_dimensions": 123,
    "volume_target_cbm": 123,
    "volume_remaining_cbm": 123,
    "volume_fill_percent": 123,
    "down_payment": 123,
    "public_note": "<string>",
    "private_note": "<string>",
    "starred": true,
    "items": [
      {
        "id": 123,
        "purchase_order_id": 123,
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z",
        "quantity": 123,
        "unit_price": 123,
        "unit": "<string>",
        "tax": 123,
        "discount_amount": 123,
        "line_total": 123,
        "expected_ship_date": "2023-12-25",
        "expected_arrival_date": "2023-12-25",
        "requested_ship_date": "2023-12-25",
        "arrival_due_date": "2023-12-25",
        "shipment_type": "Air",
        "original_arrival_due_date": "2023-12-25",
        "override_transit_days": 123,
        "quantity_received": 123,
        "received_quantity": 123,
        "quantity_ordered": 123,
        "quantity_shipped": 123,
        "quantity_billed": 123,
        "quantity_allocated": 123,
        "quantity_released": 123,
        "under_covered_quantity": 123,
        "remaining_to_ship": 123,
        "remaining_to_receive": 123,
        "open_quantity": 40,
        "closed_at": null,
        "close_reason": null,
        "available_to_allocate": 123,
        "volume_cbm": 123,
        "line_volume_cbm": 123,
        "weight_kg": 123,
        "line_weight_kg": 123,
        "allocations": [
          {
            "sales_order_id": 123,
            "sales_order_number": "<string>",
            "quantity_allocated": 123,
            "quantity_released": 123,
            "peg_ids": [
              123
            ]
          }
        ],
        "source_sku": "<string>",
        "product": {
          "id": 123,
          "name": "<string>",
          "description": "<string>",
          "retail_price": 123,
          "wholesale_price": 123,
          "unit_cost": 123,
          "product_weight": 123,
          "product_length": 123,
          "product_width": 123,
          "product_height": 123,
          "sellable": true,
          "discontinued": true,
          "image_url": "<string>",
          "variant_attributes": {},
          "sku": "<string>",
          "upc": "<string>",
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z"
        },
        "base_unit_of_measure": {
          "id": 123,
          "name": "<string>",
          "abbreviation": "<string>"
        },
        "ordered_unit_of_measure": {
          "id": 123,
          "name": "<string>",
          "abbreviation": "<string>"
        },
        "lot": {
          "id": 123,
          "lot_number": "<string>",
          "expiration_date": "2023-12-25"
        }
      }
    ],
    "supplier": {
      "id": 123,
      "status": 123,
      "name": "<string>",
      "description": "<string>",
      "street_address": "<string>",
      "city": "<string>",
      "state": "<string>",
      "zip": "<string>",
      "country": "<string>",
      "contact_name": "<string>",
      "contact_email": "<string>",
      "contact_phone": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "custom_fields": {
        "Region": "Southwest",
        "Preferred Carrier": "UPS"
      }
    },
    "payments": [
      {
        "id": 123,
        "payment_date": "2023-12-25",
        "payment_type": "cash",
        "paid_amount": 123,
        "remarks": "<string>",
        "external_id": "<string>",
        "created_by": {
          "id": 123,
          "name": "<string>"
        },
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z"
      }
    ],
    "ship_to": {
      "address_1": "<string>",
      "address_2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "zip": "<string>",
      "country": "<string>",
      "default_ship_to_address": "ship_to_address"
    },
    "warehouse_id": 123,
    "location_id": 123,
    "warehouse": {
      "id": 123,
      "name": "<string>"
    },
    "location": {
      "id": 123,
      "name": "<string>"
    },
    "tags": [
      {
        "id": 123,
        "name": "<string>",
        "description": "<string>",
        "icon": "<string>",
        "color": "<string>"
      }
    ],
    "fulfillment_orders": [
      {
        "id": 123,
        "order_number": "<string>",
        "order_status": "<string>"
      }
    ],
    "custom_fields": {}
  }
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

Authorizations

Authorization

string

header

required

Authenticate using a bearer token. To create a token, navigate to /settings/api-tokens and click Create API Token.

Path Parameters

integer

required

ID of the purchase order to update

Body

application/json

order_date

string<date>

required

Date when the purchase order was created (YYYY-MM-DD)

Example:

"2024-01-15"

supplier_id

integer

required

ID of the supplier

Example:

123

items

object[]

required

Array of line items for the purchase order

Minimum array length: 1

Show child attributes

warehouse_id

integer | null

ID of the warehouse

Example:

1

location_id

integer | null

ID of the location

Example:

1

order_status

default:active

Milestone status (token or numeric id). Also accepts 30 (production_active) and 88 (delivered) by id. Writes a milestone row and updates the PO header.

draft (101) and cancelled (100) are order states, not timeline milestones. They do not count as incoming stock and the purchase order cannot take a new receipt while in either state. Creating a purchase order with order_status: draft saves it as a draft from the start, so its lines never post incoming. Moving it to an open milestone later posts incoming at that point.

Available options:

active,

production_started,

production_completed,

in_transit,

completed,

draft,

cancelled,

deleted

Example:

"active"

order_numbers

string[] | null

Array of purchase order numbers used to identify the purchase order across various systems

Maximum string length: 255

Example:

["PO-2024-001", "SUPPLIER-PO-123"]

invoice_date

string<date> | null

Date when the purchase order was invoiced (YYYY-MM-DD)

Example:

"2024-01-16"

incoterm

string | null

Incoterm (delivery term) for the purchase order, given as a logistic code configured for the account (e.g. exw, fob, ddp). Matching is case-insensitive — both the lower-case code (exw) and its upper-case label (EXW) are accepted. Returned on the purchase order resource as incoterm. If omitted, the account default is applied.

Example:

"exw"

payment_terms

string | null

Payment terms for the purchase order. Must exactly match one of the payment terms configured for the account (Manage > Suppliers); matching is case-sensitive (Net 30 passes where net 30 fails). Returned on the purchase order resource as payment_terms. If omitted, the account default is applied.

Example:

"Net 30"

total_shipping_cost

number<float> | null

default:0

Total shipping cost

Required range: x >= 0

Example:

50

total_tax

number<float> | null

default:0

Total tax amount

Required range: x >= 0

Example:

80

volume_target_cbm

number<float> | null

Target container volume in cubic metres (the container-fill gauge's denominator). When set, the purchase-order response reports volume_remaining_cbm and volume_fill_percent against it.

Required range: x >= 0

Example:

67

public_note

string | null

Public notes visible to suppliers

Example:

"Please ship via express delivery"

private_note

string | null

Internal private notes

Example:

"Rush order - expedite processing"

requested_ship_date

string<date> | null

Requested shipping date (YYYY-MM-DD)

Example:

"2024-01-20"

arrival_due_date

string<date> | null

Expected arrival date (YYYY-MM-DD)

Example:

"2024-01-25"

shipment_type

enum<string> | null

Freight mode used by the Transit Time Matrix. Matching is case-insensitive — sea and SEA are stored as Sea — but any other value returns 422. On update, omit to keep the stored value or send null to clear it.

When a request sends shipment_type or override_transit_days and the PO has a warehouse, the Original ETA (original_arrival_due_date) and current ETA (arrival_due_date) are filled from the transit matrix if empty. Arrival dates sent in the same request are always kept as sent.

Available options:

Air,

Sea,

Road,

Rail,

Express,

null

Example:

"Sea"

original_arrival_due_date

string<date> | null

Frozen Original ETA (YYYY-MM-DD) — the arrival date as first planned, kept separate from the current arrival_due_date. On update, omit to keep the stored value or send null to clear it.

Example:

"2024-01-25"

override_transit_days

integer | null

Manual override of the transit-matrix calendar days used to derive the arrival date. 0 is allowed. On update, omit to keep the stored value or send null to clear it.

Required range: 0 <= x <= 3650

Example:

35

ship_to

object | null

Shipping address information

Show child attributes

payments

object[] | null

Array of payments for this purchase order. If provided, replaces all existing payments. Totals are automatically recalculated after payments are updated.

Show child attributes

custom_fields

object | null

Custom field values for the purchase order

Show child attributes

Example:

{
  "Customer PO": "PO-98765",
  "Priority Level": "High"
}

Response

Purchase order updated successfully

data

object

Show child attributes

Products & Catalog

Companies & Contacts

Inventory & Warehousing

Purchasing

Sales & Fulfillment

Manufacturing

Accounts Payable

Reports & Analytics

Drive

Configuration

Integrations

Update a purchase order

Key Features

Product Identification

Inventory-Tracked Products Only

Updating Items

Order Status Values

Total Calculation

Payments

Authorizations

Path Parameters

Body

Response