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

Authorization

string

required

Bearer token from your authentication provider.

X-Tenant-ID

string

required

UUID of your tenant.

X-Org-ID

string

required

UUID of your organization.

Query parameters

limit

integer

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

offset

integer

Number of orders to skip for pagination. Default 0.

Response

orders

array

Array of order objects.

Show Order fields

string

UUID of the order.

status

string

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

currency

string

ISO 4217 currency code.

subtotal

number

Sum of line item prices before adjustments.

discount_total

number

Total discount applied.

shipping_total

number

Shipping charges.

tax_total

number

Tax charges.

total

number

Final order total.

payment_status

string

Payment capture status, e.g. authorized.

payment_provider

string

Payment provider name, e.g. stripe.

payment_reference

string

Provider-side payment reference ID.

channel

string

Sales channel that originated this order.

source_platform

string

Source platform identifier, e.g. shopify.

idempotency_key

string

The unique key you provided when creating the order.

created_at

string

ISO 8601 creation timestamp.

updated_at

string

ISO 8601 last-updated timestamp.

Get an order

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

Path parameters

orderID

string

required

UUID of the order to retrieve.

Headers

Authorization

string

required

Bearer token.

X-Tenant-ID

string

required

UUID of your tenant.

X-Org-ID

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"

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

Authorization

string

required

Bearer token from your authentication provider.

X-Tenant-ID

string

required

UUID of your tenant.

X-Org-ID

string

required

UUID of your organization.

Body

idempotency_key

string

required

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

payment_provider

string

required

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

payment_reference

string

required

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

customer_id

string

UUID of the customer placing the order. Optional.

currency

string

ISO 4217 currency code. Defaults to USD if omitted.

channel

string

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

source_platform

string

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

items

array

Array of line items in the order.

Show Line item fields

product_title

string

required

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

quantity

integer

required

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

unit_price

number

required

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

variant_id

string

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

location_id

string

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

sku

string

SKU identifier for the variant. Optional.

variant_title

string

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

requires_shipping

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.

order_id

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

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.

​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