> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a new order in StateSet

> Order created successfully

### Path parameters

<ParamField path="tenant_id" type="string" required>
  Tenant identifier
</ParamField>

### Request body

`CreateOrderRequest`

<ParamField body="createdAt" type="string (date-time)" required>
  Order creation timestamp
</ParamField>

<ParamField body="externalOrderId" type="string">
  Source order ID on the external channel/platform.
</ParamField>

<ParamField body="externalPlatform" type="string">
  External channel/platform for non-Shopify orders.
</ParamField>

<ParamField body="lineItems" type="OrderLineItem[]" required>
  Order line items
</ParamField>

<ParamField body="locationId" type="string">
  Location ID for fulfillment
</ParamField>

<ParamField body="netsuiteId" type="string">
  NetSuite order ID if synced
</ParamField>

<ParamField body="orderNumber" type="string" required>
  Order number
</ParamField>

<ParamField body="shopifyOrderId" type="string" required>
  Legacy canonical order ID field used by existing StateSet/order storage. For non-Shopify channels, prefer also sending `externalPlatform` and `externalOrderId`; the orchestrator will store the canonical key as `&#123;platform&#125;:&#123;externalOrderId&#125;` while preserving backwards compatibility.
</ParamField>

<ParamField body="sourceOrderPayload" type="object">
  Raw upstream order payload snapshot, persisted for downstream sync jobs.
</ParamField>

<ParamField body="tags" type="string[]">
  Order tags for filtering/categorization
</ParamField>

<ParamField body="workflowId" type="string (uuid)">
  Workflow ID for tracking
</ParamField>

### Response

`CreateOrderResponse`

<ResponseField name="statesetOrderId" type="string (uuid)" required>
  Unique StateSet order ID
</ResponseField>

### Status codes

| Code  | Meaning                                   |
| ----- | ----------------------------------------- |
| `201` | Order created successfully                |
| `401` | Unauthorized - invalid or missing API key |
| `422` | Validation error                          |

<RequestExample>
  ```bash cURL theme={null}
  curl --request POST \
    --url 'https://api.sync.stateset.com/v1/tenants/{tenant_id}/orders' \
    --header 'x-stateset-api-key: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
    "createdAt": "2026-08-31T14:22:05Z",
    "externalOrderId": "string",
    "externalPlatform": "string",
    "lineItems": [],
    "locationId": "string",
    "netsuiteId": "string",
    "orderNumber": "M-1001",
    "shopifyOrderId": "1234567890",
    "sourceOrderPayload": null,
    "tags": [
      "priority"
    ],
    "workflowId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "statesetOrderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
  ```
</ResponseExample>