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

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

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.

Body

application/json

channel_id

integer

required

ID of the channel this order belongs to

Example:

1

order_number

string

required

Unique order number identifier

Maximum string length: 255

Example:

"ORD-2024-001"

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

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

Configuration

Integrations

Create a new sales order

Key Features

Product Identification

Order Status Values

Total Calculation

Custom Fields and Tags

Authorizations

Body

Response