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

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

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)

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.

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

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

Available options:

active,

production_started,

production_completed,

in_transit,

completed,

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"

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

Configuration

Integrations

Update a purchase order

Key Features

Product Identification

Updating Items

Order Status Values

Total Calculation

Payments

Authorizations

Path Parameters

Body

Response