curl --request POST \
  --url https://{companyName}.api.joinluminous.com/external/api/v1/sales-orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "channel_id": 1,
  "order_number": "ORD-2024-001",
  "order_date": "2024-01-15",
  "order_status": "pending",
  "bill_to": {
    "name": "John Doe"
  },
  "ship_to": {
    "name": "Jane Smith"
  },
  "items": [
    {
      "product_id": 123,
      "quantity": 2,
      "unit_price": 49.99
    }
  ]
}
'

{
  "data": {
    "id": 12345,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "status": "Active",
    "order_id": "12345",
    "order_number": "ORD-2024-001",
    "order_date": "2024-01-15",
    "order_status": "pending",
    "customer_email": "customer@example.com",
    "customer_username": "johndoe123",
    "customer_po_number": "PO-2024-5678",
    "company_id": 123,
    "company": {
      "id": 123,
      "name": "Acme Corporation",
      "status": "active",
      "address": "123 Main Street",
      "city": "Anytown",
      "state": "CA",
      "postal_code": "90210",
      "country": "US"
    },
    "bill_to": {
      "name": "John Doe",
      "company": "Acme Corporation",
      "street1": "123 Main Street",
      "street2": "Suite 100",
      "city": "Anytown",
      "state": "CA",
      "postal_code": "90210",
      "country": "US",
      "phone": "555-1234"
    },
    "ship_to": {
      "name": "Jane Smith",
      "company": "Delivery Corp",
      "street1": "456 Oak Avenue",
      "city": "Somewhere",
      "state": "NY",
      "postal_code": "10001",
      "country": "US",
      "phone": "555-5678"
    },
    "total": 128.23,
    "total_paid": 0,
    "total_tax": 15.75,
    "total_shipping": 12.5,
    "product_total": 99.98,
    "requested_shipping_service": "FedEx Ground",
    "customer_notes": "Please handle with care - fragile items",
    "internal_notes": "Rush order - expedite processing",
    "ship_date": "2024-01-20",
    "hold_until_date": "2024-01-18",
    "ship_by_date": "2024-01-25",
    "earliest_ship_date": "2024-01-18",
    "externally_fulfilled": false,
    "is_posted": false,
    "source": "external_api",
    "total_order_quantity": 3,
    "items": [
      {
        "id": 67890,
        "line_number": 1,
        "sku": "WIDGET-001",
        "name": "Premium Widget",
        "quantity": 2,
        "unit_price": 49.99,
        "upc": "123456789012",
        "product_id": 123,
        "tags": [],
        "custom_fields": {}
      },
      {
        "id": 67891,
        "line_number": 2,
        "sku": "WIDGET-002",
        "name": "Standard Widget",
        "quantity": 1,
        "unit_price": 25,
        "upc": "123456789013",
        "product_id": 124,
        "tags": [],
        "custom_fields": {}
      }
    ],
    "tags": [
      {
        "id": 1,
        "name": "urgent"
      },
      {
        "id": 2,
        "name": "vip-customer"
      },
      {
        "id": 3,
        "name": "rush-order"
      }
    ],
    "custom_fields": {
      "Customer PO": "PO-98765",
      "Priority Level": "High",
      "Package Count": 3
    }
  }
}

Sales Orders

Create a new sales order

Create a new sales order with items, addresses, 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
Flexible address handling (only name required)
Optional company association - when company_id is provided, addresses are auto-populated
Optional custom fields and tags at both order and order item level
Automatic total calculation from line items plus tax/shipping

Order Number

order_number is optional. Supply your own unique value to keep it, or omit it (or send null / "") and Luminous assigns LUM-{id} after the order is saved. Channels configured with an order-number prefix assign {prefix}{n} from that channel’s sequence instead. The assigned value is returned as order_number in the response.

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: pending, shipped, fulfilled, cancelled, awaiting_shipment, partially_shipped, on_hold, backorder, partially_refunded, committed, processing, completed

Total Calculation

The order total is automatically calculated as: (sum of item quantities × unit prices) + total_tax + total_shipping

Custom Fields and Tags

Custom fields must be predefined in the system before use
Both order-level and item-level custom fields/tags are supported

Retries and idempotency

This endpoint accepts an optional Idempotency-Key request header, so a client that retries after a network timeout does not create the same sales order twice. Without the header, the request behaves as normal.

Same key, same body: the first response is replayed as-is (status, body, and an Idempotent-Replay: true response header). Only one sales order is created, however many times the request is resent.
Same key, different body: 409 with code: idempotency_conflict. Nothing is created.
Same key, first request still in progress: 409 until the first request finishes.

Keys are kept for 24 hours and are scoped to your API token. The stored response is replayed whatever its status, including a 422. After you fix a rejected request, resend it with a new key; reusing the old key returns the stored failure. Use one key per logical create (for example, your source system’s order number) and keep it the same across retries.

POST

sales-orders

curl --request POST \
  --url https://{companyName}.api.joinluminous.com/external/api/v1/sales-orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "channel_id": 1,
  "order_number": "ORD-2024-001",
  "order_date": "2024-01-15",
  "order_status": "pending",
  "bill_to": {
    "name": "John Doe"
  },
  "ship_to": {
    "name": "Jane Smith"
  },
  "items": [
    {
      "product_id": 123,
      "quantity": 2,
      "unit_price": 49.99
    }
  ]
}
'

{
  "data": {
    "id": 12345,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "status": "Active",
    "order_id": "12345",
    "order_number": "ORD-2024-001",
    "order_date": "2024-01-15",
    "order_status": "pending",
    "customer_email": "customer@example.com",
    "customer_username": "johndoe123",
    "customer_po_number": "PO-2024-5678",
    "company_id": 123,
    "company": {
      "id": 123,
      "name": "Acme Corporation",
      "status": "active",
      "address": "123 Main Street",
      "city": "Anytown",
      "state": "CA",
      "postal_code": "90210",
      "country": "US"
    },
    "bill_to": {
      "name": "John Doe",
      "company": "Acme Corporation",
      "street1": "123 Main Street",
      "street2": "Suite 100",
      "city": "Anytown",
      "state": "CA",
      "postal_code": "90210",
      "country": "US",
      "phone": "555-1234"
    },
    "ship_to": {
      "name": "Jane Smith",
      "company": "Delivery Corp",
      "street1": "456 Oak Avenue",
      "city": "Somewhere",
      "state": "NY",
      "postal_code": "10001",
      "country": "US",
      "phone": "555-5678"
    },
    "total": 128.23,
    "total_paid": 0,
    "total_tax": 15.75,
    "total_shipping": 12.5,
    "product_total": 99.98,
    "requested_shipping_service": "FedEx Ground",
    "customer_notes": "Please handle with care - fragile items",
    "internal_notes": "Rush order - expedite processing",
    "ship_date": "2024-01-20",
    "hold_until_date": "2024-01-18",
    "ship_by_date": "2024-01-25",
    "earliest_ship_date": "2024-01-18",
    "externally_fulfilled": false,
    "is_posted": false,
    "source": "external_api",
    "total_order_quantity": 3,
    "items": [
      {
        "id": 67890,
        "line_number": 1,
        "sku": "WIDGET-001",
        "name": "Premium Widget",
        "quantity": 2,
        "unit_price": 49.99,
        "upc": "123456789012",
        "product_id": 123,
        "tags": [],
        "custom_fields": {}
      },
      {
        "id": 67891,
        "line_number": 2,
        "sku": "WIDGET-002",
        "name": "Standard Widget",
        "quantity": 1,
        "unit_price": 25,
        "upc": "123456789013",
        "product_id": 124,
        "tags": [],
        "custom_fields": {}
      }
    ],
    "tags": [
      {
        "id": 1,
        "name": "urgent"
      },
      {
        "id": 2,
        "name": "vip-customer"
      },
      {
        "id": 3,
        "name": "rush-order"
      }
    ],
    "custom_fields": {
      "Customer PO": "PO-98765",
      "Priority Level": "High",
      "Package Count": 3
    }
  }
}

Authorizations

Authorization

string

header

required

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

Headers

Idempotency-Key

string

Optional idempotency token. A retry with the same key and body replays the original stored response (with an Idempotent-Replay: true header) instead of creating a second sales order. Reusing the key with a different body returns 409. Omit it to disable the guard.

Body

application/json

channel_id

integer

required

ID of the channel this order belongs to

Example:

1

order_date

string<date>

required

Date when the order was placed (YYYY-MM-DD)

Example:

"2024-01-15"

order_status

enum<string>

required

Current status of the order

Available options:

pending,

shipped,

fulfilled,

cancelled,

awaiting_shipment,

partially_shipped,

on_hold,

backorder,

partially_refunded,

committed,

processing,

completed

Maximum string length: 255

Example:

"pending"

items

object[]

required

Array of line items for the order

Minimum array length: 1

Show child attributes

order_number

string | null

Order number shown on the sales order. Must be unique across all sales orders when supplied. Optional on create: when omitted, null, or an empty string, Luminous assigns LUM-{id} (the new order's Luminous ID) after the order is saved. If the channel is configured with an order-number prefix, the assigned number is {prefix}{n} from that channel's sequence instead. A supplied value is always kept as-is.

Maximum string length: 255

Example:

"ORD-2024-001"

customer_email

string<email> | null

Customer's email address

Maximum string length: 255

Example:

"customer@example.com"

customer_username

string | null

Customer's username

Maximum string length: 255

Example:

"customer123"

customer_po_number

string | null

Customer's purchase order number

Maximum string length: 255

Example:

"PO-2024-5678"

company_id

integer | null

ID of the company (business account) to associate with this sales order. When provided, the system will automatically populate the bill_to and ship_to addresses from the company's information. If company_id is provided, the bill_to and ship_to fields become optional.

Example:

123

bill_to

object

Billing address information. Required when company_id is not provided. When company_id is provided, this field is optional and will be populated from the company's billing address if not specified.

Show child attributes

ship_to

object

Shipping address information. Required when company_id is not provided. When company_id is provided, this field is optional and will be populated from the company's default shipping address if not specified.

Show child attributes

ship_date

string<date> | null

Date when the order was or will be shipped (YYYY-MM-DD)

Example:

"2024-01-20"

hold_until_date

string<date> | null

Date to hold the order until (YYYY-MM-DD)

Example:

"2024-01-18"

ship_by_date

string<date> | null

Required ship by date (YYYY-MM-DD)

Example:

"2024-01-25"

earliest_ship_date

string<date> | null

Earliest date the order can be shipped (YYYY-MM-DD)

Example:

"2024-01-18"

total_tax

number<float> | null

Total tax amount for the order

Required range: x >= 0

Example:

15.75

total_shipping

number<float> | null

Total shipping cost for the order

Required range: x >= 0

Example:

12.5

total_discount

number<float> | null

Total discount amount applied to the order. If omitted, any header trade discount configured on the linked company (see header_discount_enabled, header_discount_type, and header_discount_value on the company) is computed and applied automatically. Provide an explicit value to override.

Required range: x >= 0

Example:

10

requested_shipping_service

string | null

Requested shipping service or carrier

Maximum string length: 255

Example:

"FedEx Ground"

customer_notes

string | null

Notes from the customer

Example:

"Please handle with care - fragile items"

internal_notes

string | null

Internal notes for order processing

Example:

"Rush order - expedite processing"

custom_fields

object | null

Custom field values for the sales order

Show child attributes

Example:

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

Response

Sales order created successfully

data

object

Show child attributes

Products & Catalog

Companies & Contacts

Inventory & Warehousing

Purchasing

Sales & Fulfillment

Manufacturing

Accounts Payable

Reports & Analytics

Drive

Configuration

Integrations

Create a new sales order

Key Features

Order Number

Product Identification

Order Status Values

Total Calculation

Custom Fields and Tags

Retries and idempotency

Authorizations

Headers

Body

Response