Orders API: Create and Track Orders

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.

All requests require three headers: Authorization: Bearer YOUR_TOKEN, X-Tenant-ID: YOUR_TENANT_ID, and X-Org-ID: YOUR_ORG_ID.

List orders

Retrieve a paginated list of orders scoped to your tenant and organization. GET /api/v1/oms/orders

Headers

string

required

Bearer token from your authentication provider.

string

required

UUID of your tenant.

string

required

UUID of your organization.

Query parameters

integer

Number of orders to return. Max 100, default 50.

integer

Number of orders to skip for pagination. Default 0.

Response

array

Array of order objects.

Show Order fields

string

UUID of the order.

string

Order status. Possible values: pending_payment, payment_authorized, confirmed, processing, partially_fulfilled, fulfilled, delivered, completed, cancelled, return_requested, returned, refunded, failed.

string

ISO 4217 currency code.

number

Sum of line item prices before adjustments.

number

Total discount applied.

number

Shipping charges.

number

Tax charges.

number

Final order total.

string

Payment capture status, e.g. authorized.

string

Payment provider name, e.g. stripe.

string

Provider-side payment reference ID.

string

Sales channel that originated this order.

string

Source platform identifier, e.g. shopify.

string

The unique key you provided when creating the order.

string

ISO 8601 creation timestamp.

string

ISO 8601 last-updated timestamp.

array

Array of string tags on the order.

integer

The limit value used for this page.

integer

The offset value used for this page.

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"

{
  "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
}

Get an order

Retrieve a single order by its UUID. GET /api/v1/oms/orders/{orderID}

Path parameters

string

required

UUID of the order to retrieve.

Headers

string

required

Bearer token.

string

required

UUID of your tenant.

string

required

UUID of your organization.

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"

{
  "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": []
}

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

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.

Headers

string

required

Bearer token from your authentication provider.

string

required

UUID of your tenant.

string

required

UUID of your organization.

Body

string

required

A unique string that identifies this order attempt. Re-use the same key on retries to prevent duplicate orders.

string

required

Name of the payment provider, e.g. stripe, adyen, or paypal.

string

required

The provider-side payment intent or transaction reference, e.g. Stripe’s pi_....

string

UUID of the customer placing the order. Optional.

string

ISO 4217 currency code. Defaults to USD if omitted.

string

Name or identifier of the sales channel this order originated from, e.g. web-storefront.

string

Upstream platform identifier, e.g. shopify. Optional.

array

Array of line items in the order.

Show Line item fields

string

required

Display name of the product at the time of order capture.

integer

required

Number of units to order. Must be greater than zero.

number

required

Price per unit at the time of order capture. Cannot be negative.

string

UUID of the product variant being ordered. Required when you want inventory to be reserved.

string

UUID of the fulfillment location. Required when variant_id is set.

string

SKU identifier for the variant. Optional.

string

Display name of the specific variant option, e.g. Blue / Medium. Optional.

boolean

Whether this line item requires physical shipment. Optional.

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.

string

UUID of the newly created order.

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
      }
    ]
  }'

{
  "order_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

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.

Overview

Endpoints

Orders API: Create and Track Orders

List orders

Headers

Query parameters

Response

Get an order

Path parameters

Headers

Create an order

Idempotency

Headers

Body

Response

​List orders

​Headers

​Query parameters

​Response

​Get an order

​Path parameters

​Headers

​Create an order

​Idempotency

​Headers

​Body

​Response

List orders

Headers

Query parameters

Response

Get an order

Path parameters

Headers

Create an order

Idempotency

Headers

Body

Response