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": "[email protected]",
    "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",
    "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": "[email protected]",
    "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",
    "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 obtain a token, contact [email protected]

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:

"[email protected]"

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"

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

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

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

Sales orders Single sales order

⌘I

Products

Purchase Orders

Inventory

Transfer Orders

Receiving Reports

Sales Orders

Invoices

Tags

Custom Fields

Locations

Companies

Contacts

Pricing

BOMs

Create a new sales order

Key Features

Product Identification

Order Status Values

Total Calculation

Custom Fields and Tags

Authorizations

Body

Response