curl --request POST \
  --url https://{companyName}.api.joinluminous.com/external/api/v1/purchase-orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "order_date": "2024-01-15",
  "supplier_id": 123,
  "items": [
    {
      "product_id": 456,
      "quantity": 10,
      "unit_price": 49.99
    }
  ]
}
'

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

Purchase Orders

Create a new purchase order

Create a new purchase order with items, payments, and optional metadata.

Key Features

Create orders with multiple line items
Support for both product ID and SKU lookup for items
Automatic product name and details population
Optional payments - can include payments when creating the order
Optional shipping address (ship_to) information
Optional custom fields and tags at both order and order item level
Automatic total calculation from line items plus tax/shipping
Stock count updates - incoming quantities are automatically updated

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)

Order Status Values

Valid order statuses include: active, completed, deleted Defaults to active if not provided.

Total Calculation

The order cost (order_cost) is automatically calculated as: sum of (item quantities × unit prices)

The order total (total_cost) is automatically calculated 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.

POST

purchase-orders

curl --request POST \
  --url https://{companyName}.api.joinluminous.com/external/api/v1/purchase-orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "order_date": "2024-01-15",
  "supplier_id": 123,
  "items": [
    {
      "product_id": 456,
      "quantity": 10,
      "unit_price": 49.99
    }
  ]
}
'

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

Authorizations

Authorization

string

header

required

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

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 created successfully

data

object

Show child attributes

Products & Catalog

Companies & Contacts

Inventory & Warehousing

Purchasing

Sales & Fulfillment

Manufacturing

Accounts Payable

Reports & Analytics

Configuration

Integrations

Create a new purchase order

Key Features

Product Identification

Order Status Values

Total Calculation

Payments

Authorizations

Body

Response