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

# Orders API: Create and Track Orders

> Create and retrieve orders through the OMS API. Built-in idempotency, payment capture, and inventory reservation ensure every order is processed reliably.

The Orders API lets you create and track orders in Synq's Order Management System (OMS). When you submit a new order, the platform processes payment capture, inventory reservation, and status transitions in sequence. Because order processing is durable, a transient error never leaves an order in a broken state — failed steps are retried automatically until they succeed or exhaust the retry policy.

<Note>
  All requests require three headers: `Authorization: Bearer YOUR_TOKEN`, `X-Tenant-ID: YOUR_TENANT_ID`, and `X-Org-ID: YOUR_ORG_ID`.
</Note>

***

## List orders

Retrieve a paginated list of orders scoped to your tenant and organization.

**`GET /api/v1/oms/orders`**

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token from your authentication provider.
</ParamField>

<ParamField header="X-Tenant-ID" type="string" required>
  UUID of your tenant.
</ParamField>

<ParamField header="X-Org-ID" type="string" required>
  UUID of your organization.
</ParamField>

### Query parameters

<ParamField query="limit" type="integer">
  Number of orders to return. Max `100`, default `50`.
</ParamField>

<ParamField query="offset" type="integer">
  Number of orders to skip for pagination. Default `0`.
</ParamField>

### Response

<ResponseField name="orders" type="array">
  Array of order objects.

  <Expandable title="Order fields">
    <ResponseField name="id" type="string">UUID of the order.</ResponseField>
    <ResponseField name="status" type="string">Order status. Possible values: `pending_payment`, `payment_authorized`, `confirmed`, `processing`, `partially_fulfilled`, `fulfilled`, `delivered`, `completed`, `cancelled`, `return_requested`, `returned`, `refunded`, `failed`.</ResponseField>
    <ResponseField name="currency" type="string">ISO 4217 currency code.</ResponseField>
    <ResponseField name="subtotal" type="number">Sum of line item prices before adjustments.</ResponseField>
    <ResponseField name="discount_total" type="number">Total discount applied.</ResponseField>
    <ResponseField name="shipping_total" type="number">Shipping charges.</ResponseField>
    <ResponseField name="tax_total" type="number">Tax charges.</ResponseField>
    <ResponseField name="total" type="number">Final order total.</ResponseField>
    <ResponseField name="payment_status" type="string">Payment capture status, e.g. `authorized`.</ResponseField>
    <ResponseField name="payment_provider" type="string">Payment provider name, e.g. `stripe`.</ResponseField>
    <ResponseField name="payment_reference" type="string">Provider-side payment reference ID.</ResponseField>
    <ResponseField name="channel" type="string">Sales channel that originated this order.</ResponseField>
    <ResponseField name="source_platform" type="string">Source platform identifier, e.g. `shopify`.</ResponseField>
    <ResponseField name="idempotency_key" type="string">The unique key you provided when creating the order.</ResponseField>
    <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
    <ResponseField name="updated_at" type="string">ISO 8601 last-updated timestamp.</ResponseField>
    <ResponseField name="tags" type="array">Array of string tags on the order.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="limit" type="integer">
  The `limit` value used for this page.
</ResponseField>

<ResponseField name="offset" type="integer">
  The `offset` value used for this page.
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.synq.app/api/v1/oms/orders?limit=20&offset=0" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-Tenant-ID: YOUR_TENANT_ID" \
    -H "X-Org-ID: YOUR_ORG_ID"
  ```

  ```json Response theme={null}
  {
    "orders": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "status": "confirmed",
        "currency": "USD",
        "subtotal": 179.98,
        "discount_total": 0,
        "shipping_total": 9.99,
        "tax_total": 15.30,
        "total": 205.27,
        "payment_status": "authorized",
        "payment_provider": "stripe",
        "payment_reference": "pi_3Pqr4RLkdIwHu7ix0pQvA1bC",
        "channel": "web-storefront",
        "source_platform": null,
        "idempotency_key": "cart-9f2e1a4b-3c7d",
        "created_at": "2024-06-10T14:22:00Z",
        "updated_at": "2024-06-10T14:23:15Z",
        "tags": []
      }
    ],
    "limit": 20,
    "offset": 0
  }
  ```
</CodeGroup>

***

## Get an order

Retrieve a single order by its UUID.

**`GET /api/v1/oms/orders/{orderID}`**

### Path parameters

<ParamField path="orderID" type="string" required>
  UUID of the order to retrieve.
</ParamField>

### Headers

<ParamField header="Authorization" type="string" required>Bearer token.</ParamField>
<ParamField header="X-Tenant-ID" type="string" required>UUID of your tenant.</ParamField>
<ParamField header="X-Org-ID" type="string" required>UUID of your organization.</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.synq.app/api/v1/oms/orders/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-Tenant-ID: YOUR_TENANT_ID" \
    -H "X-Org-ID: YOUR_ORG_ID"
  ```

  ```json Response theme={null}
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "confirmed",
    "currency": "USD",
    "subtotal": 179.98,
    "discount_total": 0,
    "shipping_total": 9.99,
    "tax_total": 15.30,
    "total": 205.27,
    "payment_status": "authorized",
    "payment_provider": "stripe",
    "payment_reference": "pi_3Pqr4RLkdIwHu7ix0pQvA1bC",
    "channel": "web-storefront",
    "source_platform": null,
    "idempotency_key": "cart-9f2e1a4b-3c7d",
    "created_at": "2024-06-10T14:22:00Z",
    "updated_at": "2024-06-10T14:23:15Z",
    "tags": []
  }
  ```
</CodeGroup>

***

## Create an order

Submit a new order. The API validates your request, reserves inventory, and processes payment in sequence. It immediately returns a confirmation with the new order ID once the initial order record is created. Poll `GET /api/v1/oms/orders/{orderID}` to track status transitions.

**`POST /api/v1/oms/orders`**

### Idempotency

<Note>
  You **must** provide a unique `idempotency_key` with every order creation attempt. If your request times out or you receive a network error, retry with the same key — the platform detects the duplicate and will not create a second order. Use a value that is unique to each distinct order attempt, such as a client-generated UUID or your cart/session ID.
</Note>

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token from your authentication provider.
</ParamField>

<ParamField header="X-Tenant-ID" type="string" required>
  UUID of your tenant.
</ParamField>

<ParamField header="X-Org-ID" type="string" required>
  UUID of your organization.
</ParamField>

### Body

<ParamField body="idempotency_key" type="string" required>
  A unique string that identifies this order attempt. Re-use the same key on retries to prevent duplicate orders.
</ParamField>

<ParamField body="payment_provider" type="string" required>
  Name of the payment provider, e.g. `stripe`, `adyen`, or `paypal`.
</ParamField>

<ParamField body="payment_reference" type="string" required>
  The provider-side payment intent or transaction reference, e.g. Stripe's `pi_...`.
</ParamField>

<ParamField body="customer_id" type="string">
  UUID of the customer placing the order. Optional.
</ParamField>

<ParamField body="currency" type="string">
  ISO 4217 currency code. Defaults to `USD` if omitted.
</ParamField>

<ParamField body="channel" type="string">
  Name or identifier of the sales channel this order originated from, e.g. `web-storefront`.
</ParamField>

<ParamField body="source_platform" type="string">
  Upstream platform identifier, e.g. `shopify`. Optional.
</ParamField>

<ParamField body="items" type="array">
  Array of line items in the order.

  <Expandable title="Line item fields">
    <ParamField body="product_title" type="string" required>
      Display name of the product at the time of order capture.
    </ParamField>

    <ParamField body="quantity" type="integer" required>
      Number of units to order. Must be greater than zero.
    </ParamField>

    <ParamField body="unit_price" type="number" required>
      Price per unit at the time of order capture. Cannot be negative.
    </ParamField>

    <ParamField body="variant_id" type="string">
      UUID of the product variant being ordered. Required when you want inventory to be reserved.
    </ParamField>

    <ParamField body="location_id" type="string">
      UUID of the fulfillment location. Required when `variant_id` is set.
    </ParamField>

    <ParamField body="sku" type="string">
      SKU identifier for the variant. Optional.
    </ParamField>

    <ParamField body="variant_title" type="string">
      Display name of the specific variant option, e.g. `Blue / Medium`. Optional.
    </ParamField>

    <ParamField body="requires_shipping" type="boolean">
      Whether this line item requires physical shipment. Optional.
    </ParamField>
  </Expandable>
</ParamField>

### Response

Returns the new order ID once the order record has been created. The order is then processed asynchronously through payment authorization and inventory reservation.

<ResponseField name="order_id" type="string">
  UUID of the newly created order.
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.synq.app/api/v1/oms/orders \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-Tenant-ID: YOUR_TENANT_ID" \
    -H "X-Org-ID: YOUR_ORG_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "idempotency_key": "cart-9f2e1a4b-3c7d",
      "payment_provider": "stripe",
      "payment_reference": "pi_3Pqr4RLkdIwHu7ix0pQvA1bC",
      "currency": "USD",
      "channel": "web-storefront",
      "items": [
        {
          "product_title": "Classic Wool Sweater",
          "variant_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
          "location_id": "f6a7b8c9-d0e1-2345-abcd-678901234567",
          "sku": "WOOL-SWTR-M-BLU",
          "variant_title": "Blue / Medium",
          "quantity": 2,
          "unit_price": 89.99,
          "requires_shipping": true
        }
      ]
    }'
  ```

  ```json Response theme={null}
  {
    "order_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
  ```
</CodeGroup>

<Warning>
  The `location_id` field is required for every line item that includes a `variant_id`. Omitting it returns `400 Bad Request` with the message `location_id is required for inventory-backed items`.
</Warning>