Skip to main content
The Synq Order Management System (OMS) gives you a reliable pipeline for every order your business processes. When you create an order, Synq reserves inventory, validates your payment details, confirms the order, and emits downstream events — all without you having to coordinate those steps yourself. You interact with a clean REST API; Synq handles the processing and status updates asynchronously.

​
Order lifecycle

Every order moves through a well-defined set of statuses. Understanding these helps you build accurate UI states and support flows.
Status transitions are enforced by Synq’s order state machine. You cannot skip states or move backwards — for example, a confirmed order can only move to processing or cancelled.

​
Required headers

Every request to the Synq API requires three headers for tenant isolation and authentication.

​
Create an order

​
Request fields

​
string
required
A unique key scoped to this order attempt. Synq uses this to prevent duplicate order creation — submitting the same key twice returns the original result. Generate a new UUID v4 for each distinct order attempt.
​
string
required
The payment provider used for this order. For example: "stripe", "adyen", "braintree".
​
string
required
The transaction or payment intent ID from your payment provider. For Stripe this is typically a pi_... or ch_... value.
​
array
required
One or more line items in the order. At least one item is required.
​
string
required
Human-readable product name recorded on the order line.
​
integer
required
Number of units. Must be greater than zero.
​
number
required
Price per unit in the order currency. Cannot be negative.
​
string (UUID)
The Synq variant UUID. Required for inventory-backed items. When provided, location_id is also required.
​
string (UUID)
The fulfillment location UUID from which inventory will be reserved. Required when variant_id is set.
​
string
Optional SKU recorded on the line item for reference.
​
string
Optional human-readable variant label (e.g. "Size 10 / Black").
​
boolean
Whether this line item requires physical shipment. Defaults to true when omitted.
​
string
ISO 4217 currency code. Defaults to "USD" when omitted.
​
string (UUID)
The Synq customer UUID to associate with this order.
​
string
The sales channel identifier (e.g. "web-storefront", "mobile-app", "pos-terminal").
​
string
Optional label for the originating platform used for analytics and channel sync.

​
List orders

Use GET /api/v1/oms/orders to retrieve a paginated list of orders scoped to the authenticated organization.
Query parameters
​
integer
Number of orders to return per page. Defaults to 50; maximum is 100.
​
integer
Number of records to skip for pagination. Defaults to 0.
Response

​
Get a single order

Use GET /api/v1/oms/orders/{orderID} to retrieve the full detail of one order by its UUID.
Response

​
Response fields

​
string
The UUID of the order.
​
string
Current lifecycle status. See the order lifecycle table above.
​
string
ISO 4217 currency code for all monetary values on this order.
​
number
Sum of all line item totals before discounts, shipping, and tax.
​
number
Total value of discounts applied to the order.
​
number
Total shipping cost applied to the order.
​
number
Total tax applied to the order.
​
number
Final order total: subtotal - discount_total + shipping_total + tax_total.
​
string
Payment authorization state, e.g. "authorized".
​
string
The payment provider recorded at order creation.
​
string
The provider transaction ID recorded at order creation.
​
string
The sales channel identifier recorded at order creation.
​
string
The originating platform label, if provided at creation. Otherwise null.
​
string
The key you supplied at creation, useful for correlating your internal records.
​
string (ISO 8601)
UTC timestamp of order creation.
​
string (ISO 8601)
UTC timestamp of the most recent status change or update.
​
array
Arbitrary string tags attached to the order.