Skip to main content

Orders

Unified order management

All endpoints require a bearer token (oh_... API key or user JWT) and are served under https://api.orderly-hub.com. Use the Try it consoles to run a request against the Preview (test) server.

The order object​

Every source platform is normalized to the same order shape. Nested objects use the following fields consistently across list, create, and detail responses.

customer​

FieldTypeDescription
idstringCustomer identifier from the source platform
emailstringCustomer email address
firstNamestringFirst name
lastNamestringLast name
phonestringPhone number

shippingAddress and billingAddress​

FieldTypeDescription
namestringFull recipient name
companystringCompany name
address1stringAddress line 1
address2stringAddress line 2
citystringCity
provincestringState or province
provinceCodestringState or province code
zipstringPostal code
countrystringCountry name
countryCodestringTwo-letter country code
phonestringRecipient phone
emailstringRecipient email

lineItems[]​

FieldTypeDescription
idstringOrderly line-item identifier
externalIdstringSource-platform line-item identifier
skustringStock keeping unit
namestringProduct or line title
quantitynumberUnits ordered
unitPricenumberPer-unit price in the order currency
totalPricenumberExtended line total
weightnumberUnit weight
weightUnitstringoz, lb, g, or kg
variantTitlestringVariant title
productIdstringSource product identifier
variantIdstringSource variant identifier
requiresShippingbooleanWhether the item ships physically
taxablebooleanWhether the item is taxable
propertiesobjectCustomer-defined SKU fields; keys are preserved exactly

totals​

FieldTypeDescription
subtotalnumberMerchandise subtotal
shippingnumberShipping amount
taxnumberTax amount
discountnumberDiscount amount
totalnumberFinal order total

All totals use the order's currency.

metadata​

FieldTypeDescription
customobjectCustom nested fields; keys are preserved exactly

Use metadata.custom for custom order data in Orders API requests and responses.

List orders​

GET/api/v1/orders

Parameters​

NameInRequiredTypeDescription
pagequerynointeger
limitquerynointegerNumber of orders per page, from 1 to 500
statusquerynostringOrder status. Comma-separated list. Allowed values: pending, confirmed, processing, shipped, delivered, cancelled, refunded, on_hold.
fulfillmentStatusquerynostringFulfillment status. partially_fulfilled is an alias of partial. Comma-separated list. Allowed values: unfulfilled, partial, partially_fulfilled, fulfilled.
paymentStatusquerynostringPayment status. Comma-separated list. Allowed values: pending, authorized, paid, partially_paid, refunded, voided.
lifecycleStatequerynostringLifecycle state. Comma-separated list. Allowed values: importing, validation_failed, awaiting_release, release_queued, released, ready_for_dispatch, service_assigned, label_purchasing, label_created, void_pending, ready_for_label, shipped, delivered, cancelled, exception.
priorityquerynostringFulfillment priority. Comma-separated list. Allowed values: low, normal, high, urgent.
tagsquerynostringComma-separated tags, up to 50 values of 100 characters. Matching follows tagsMode.
tagsModequerynoany | allany matches orders with at least one listed tag, all requires every listed tag.
fulfillmentLocationIdquerynostringA location UUID, or the literal unassigned for orders with no fulfillment location.
bridgeIdquerynostring
searchquerynostringCase-insensitive match on order number, external ID, or customer email. The * character is stripped.
customerquerynostringCase-insensitive contains match on customer name or email. The * character is stripped.
shipToCityquerynostringCase-insensitive contains match on the ship-to city. The * character is stripped.
shipToStatequerynostringCase-insensitive match on the ship-to state or province. The * character is stripped.
shipToCountryquerynostringCase-insensitive match on the ship-to country. The * character is stripped.
shipToPostalCodequerynostringCase-insensitive prefix match on the ship-to postal code. The * character is stripped.
skuquerynostringOrders with a line item carrying exactly this SKU.
minTotalquerynonumberMinimum order total, inclusive.
maxTotalquerynonumberMaximum order total, inclusive.
carrierquerynostringCase-insensitive match on the carrier of the assigned shipping service. Cannot be combined with hasService=false.
servicequerynostringCase-insensitive contains match on the assigned service code. Cannot be combined with hasService=false.
hasServicequerynotrue | falsetrue returns orders with an assigned shipping service, false returns orders without one. false cannot be combined with carrier or service.
labelStatusquerynostringLabel state of the order shipments. none returns orders with no shipment carrying a label state and cannot be combined with other values. Comma-separated list. Allowed values: none, pending, purchased, failed, void_requested, voided, refund_pending, refunded, replaced.
orderedFromquerynostringEarliest order time, inclusive. A YYYY-MM-DD date (start of day, UTC) or an ISO datetime with offset.
orderedToquerynostringLatest order time, inclusive. A YYYY-MM-DD date (end of day, UTC) or an ISO datetime with offset.
requestedShipFromquerynostringEarliest requested ship date, inclusive.
requestedShipToquerynostringLatest requested ship date, inclusive.
attentionquerynotrue | falsetrue returns unfulfilled, non-cancelled, non-refunded orders placed more than three days ago.
sortquerynoordered_at | created_at | requested_ship_date | total | order_numberSort key. Ties are broken by order id so pages are stable.
sortDirquerynoasc | descSort direction. Defaults to desc for ordered_at, created_at and total, and asc for requested_ship_date and order_number.
fieldsquerynoidsWhen ids, data is an array of order UUID strings instead of order objects. Pagination is unchanged.
includequerynostringComma-separated: bridge, dispatch_assignments

Responses​

200 Paginated order list. With fields=ids, data is an array of order UUID strings.

Order[] object:

FieldTypeDescription
idstring
organizationIdstring
bridgeIdstring
externalIdstring
orderNumberstring
statusstring
statusDetailstring
sourceSystemstring
sourceRecordIdstring
ingestMethodstring
trackingLifecycleIdstring
paymentStatusstring
fulfillmentStatusstring
customerCustomer
shippingAddressAddress
billingAddressAddress
lineItemsLineItem[]
totalsOrderTotals
currencystring
tagsarray
notestring
metadataOrderMetadataCustom order data stored under metadata.custom.
sourceDataobject
orderedAtstring
createdAtstring
updatedAtstring
{
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"organizationId": "550e8400-e29b-41d4-a716-446655440000",
"bridgeId": "550e8400-e29b-41d4-a716-446655440000",
"externalId": "550e8400-e29b-41d4-a716-446655440000",
"orderNumber": "string",
"status": "pending",
"statusDetail": "string",
"sourceSystem": "string",
"sourceRecordId": "550e8400-e29b-41d4-a716-446655440000",
"ingestMethod": "string",
"trackingLifecycleId": "550e8400-e29b-41d4-a716-446655440000",
"paymentStatus": "pending",
"fulfillmentStatus": "pending",
"customer": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"email": "jane@example.com",
"firstName": "string",
"lastName": "string",
"phone": "string"
},
"shippingAddress": {
"name": "Jane Doe",
"company": "string",
"address1": "string",
"address2": "string",
"city": "string",
"province": "string",
"provinceCode": "string",
"zip": "94107",
"country": "string",
"countryCode": "string",
"phone": "string",
"email": "jane@example.com"
},
"billingAddress": {
"name": "Jane Doe",
"company": "string",
"address1": "string",
"address2": "string",
"city": "string",
"province": "string",
"provinceCode": "string",
"zip": "94107",
"country": "string",
"countryCode": "string",
"phone": "string",
"email": "jane@example.com"
},
"lineItems": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"externalId": "550e8400-e29b-41d4-a716-446655440000",
"sku": "string",
"name": "Jane Doe",
"quantity": 0,
"unitPrice": 0,
"totalPrice": 0,
"weight": 0,
"weightUnit": "oz",
"variantTitle": "string",
"productId": "550e8400-e29b-41d4-a716-446655440000",
"variantId": "550e8400-e29b-41d4-a716-446655440000",
"requiresShipping": true,
"taxable": true,
"properties": {}
}
],
"totals": {
"subtotal": 49.99,
"shipping": 0,
"tax": 0,
"discount": 0,
"total": 49.99
},
"currency": "USD",
"tags": [
"string"
],
"note": "string",
"metadata": {
"custom": {}
},
"sourceData": {},
"orderedAt": "2026-07-23T12:00:00Z",
"createdAt": "2026-07-23T12:00:00Z",
"updatedAt": "2026-07-23T12:00:00Z"
}
],
"pagination": {
"page": 0,
"limit": 0,
"total": 0,
"totalPages": 0,
"hasMore": true
}
}

400 A filter value is invalid, or the combination is not allowed (labelStatus none with other values, hasService=false with carrier or service)

GET/api/v1/orders

List orders

https://api-test.orderly-hub.com/api/v1/orders

Create an order​

POST/api/v1/orders

Request body​

FieldTypeDescription
bridgeIdstring
externalIdstring
orderNumberstring
statusstring
paymentStatusstring
fulfillmentStatusstring
customerCustomer
shippingAddressAddress
billingAddressAddress
lineItemsLineItem[]
totalsOrderTotals
currencystring
tagsarray
notestring
metadataOrderMetadataCustom order data stored under metadata.custom.
sourceDataobject
orderedAtstring
{
"bridgeId": "550e8400-e29b-41d4-a716-446655440000",
"externalId": "550e8400-e29b-41d4-a716-446655440000",
"orderNumber": "string",
"status": "pending",
"paymentStatus": "pending",
"fulfillmentStatus": "pending",
"customer": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"email": "jane@example.com",
"firstName": "string",
"lastName": "string",
"phone": "string"
},
"shippingAddress": {
"name": "Jane Doe",
"company": "string",
"address1": "string",
"address2": "string",
"city": "string",
"province": "string",
"provinceCode": "string",
"zip": "94107",
"country": "string",
"countryCode": "string",
"phone": "string",
"email": "jane@example.com"
},
"billingAddress": {
"name": "Jane Doe",
"company": "string",
"address1": "string",
"address2": "string",
"city": "string",
"province": "string",
"provinceCode": "string",
"zip": "94107",
"country": "string",
"countryCode": "string",
"phone": "string",
"email": "jane@example.com"
},
"lineItems": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"externalId": "550e8400-e29b-41d4-a716-446655440000",
"sku": "string",
"name": "Jane Doe",
"quantity": 0,
"unitPrice": 0,
"totalPrice": 0,
"weight": 0,
"weightUnit": "oz",
"variantTitle": "string",
"productId": "550e8400-e29b-41d4-a716-446655440000",
"variantId": "550e8400-e29b-41d4-a716-446655440000",
"requiresShipping": true,
"taxable": true,
"properties": {}
}
],
"totals": {
"subtotal": 49.99,
"shipping": 0,
"tax": 0,
"discount": 0,
"total": 49.99
},
"currency": "USD",
"tags": [
"string"
],
"note": "string",
"metadata": {
"custom": {}
},
"sourceData": {},
"orderedAt": "2026-07-23T12:00:00Z"
}

Responses​

201 Order created

Order object:

FieldTypeDescription
idstring
organizationIdstring
bridgeIdstring
externalIdstring
orderNumberstring
statusstring
statusDetailstring
sourceSystemstring
sourceRecordIdstring
ingestMethodstring
trackingLifecycleIdstring
paymentStatusstring
fulfillmentStatusstring
customerCustomer
shippingAddressAddress
billingAddressAddress
lineItemsLineItem[]
totalsOrderTotals
currencystring
tagsarray
notestring
metadataOrderMetadataCustom order data stored under metadata.custom.
sourceDataobject
orderedAtstring
createdAtstring
updatedAtstring
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"organizationId": "550e8400-e29b-41d4-a716-446655440000",
"bridgeId": "550e8400-e29b-41d4-a716-446655440000",
"externalId": "550e8400-e29b-41d4-a716-446655440000",
"orderNumber": "string",
"status": "pending",
"statusDetail": "string",
"sourceSystem": "string",
"sourceRecordId": "550e8400-e29b-41d4-a716-446655440000",
"ingestMethod": "string",
"trackingLifecycleId": "550e8400-e29b-41d4-a716-446655440000",
"paymentStatus": "pending",
"fulfillmentStatus": "pending",
"customer": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"email": "jane@example.com",
"firstName": "string",
"lastName": "string",
"phone": "string"
},
"shippingAddress": {
"name": "Jane Doe",
"company": "string",
"address1": "string",
"address2": "string",
"city": "string",
"province": "string",
"provinceCode": "string",
"zip": "94107",
"country": "string",
"countryCode": "string",
"phone": "string",
"email": "jane@example.com"
},
"billingAddress": {
"name": "Jane Doe",
"company": "string",
"address1": "string",
"address2": "string",
"city": "string",
"province": "string",
"provinceCode": "string",
"zip": "94107",
"country": "string",
"countryCode": "string",
"phone": "string",
"email": "jane@example.com"
},
"lineItems": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"externalId": "550e8400-e29b-41d4-a716-446655440000",
"sku": "string",
"name": "Jane Doe",
"quantity": 0,
"unitPrice": 0,
"totalPrice": 0,
"weight": 0,
"weightUnit": "oz",
"variantTitle": "string",
"productId": "550e8400-e29b-41d4-a716-446655440000",
"variantId": "550e8400-e29b-41d4-a716-446655440000",
"requiresShipping": true,
"taxable": true,
"properties": {}
}
],
"totals": {
"subtotal": 49.99,
"shipping": 0,
"tax": 0,
"discount": 0,
"total": 49.99
},
"currency": "USD",
"tags": [
"string"
],
"note": "string",
"metadata": {
"custom": {}
},
"sourceData": {},
"orderedAt": "2026-07-23T12:00:00Z",
"createdAt": "2026-07-23T12:00:00Z",
"updatedAt": "2026-07-23T12:00:00Z"
}
}

409 Duplicate external ID

POST/api/v1/orders

Create an order

https://api-test.orderly-hub.com/api/v1/orders

Get single order​

GET/api/v1/orders/{id}

Parameters​

NameInRequiredTypeDescription
idpathyesstring
includequerynostringComma-separated: bridge, dispatch_assignments

Responses​

200 Order details

Order object:

FieldTypeDescription
idstring
organizationIdstring
bridgeIdstring
externalIdstring
orderNumberstring
statusstring
statusDetailstring
sourceSystemstring
sourceRecordIdstring
ingestMethodstring
trackingLifecycleIdstring
paymentStatusstring
fulfillmentStatusstring
customerCustomer
shippingAddressAddress
billingAddressAddress
lineItemsLineItem[]
totalsOrderTotals
currencystring
tagsarray
notestring
metadataOrderMetadataCustom order data stored under metadata.custom.
sourceDataobject
orderedAtstring
createdAtstring
updatedAtstring
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"organizationId": "550e8400-e29b-41d4-a716-446655440000",
"bridgeId": "550e8400-e29b-41d4-a716-446655440000",
"externalId": "550e8400-e29b-41d4-a716-446655440000",
"orderNumber": "string",
"status": "pending",
"statusDetail": "string",
"sourceSystem": "string",
"sourceRecordId": "550e8400-e29b-41d4-a716-446655440000",
"ingestMethod": "string",
"trackingLifecycleId": "550e8400-e29b-41d4-a716-446655440000",
"paymentStatus": "pending",
"fulfillmentStatus": "pending",
"customer": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"email": "jane@example.com",
"firstName": "string",
"lastName": "string",
"phone": "string"
},
"shippingAddress": {
"name": "Jane Doe",
"company": "string",
"address1": "string",
"address2": "string",
"city": "string",
"province": "string",
"provinceCode": "string",
"zip": "94107",
"country": "string",
"countryCode": "string",
"phone": "string",
"email": "jane@example.com"
},
"billingAddress": {
"name": "Jane Doe",
"company": "string",
"address1": "string",
"address2": "string",
"city": "string",
"province": "string",
"provinceCode": "string",
"zip": "94107",
"country": "string",
"countryCode": "string",
"phone": "string",
"email": "jane@example.com"
},
"lineItems": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"externalId": "550e8400-e29b-41d4-a716-446655440000",
"sku": "string",
"name": "Jane Doe",
"quantity": 0,
"unitPrice": 0,
"totalPrice": 0,
"weight": 0,
"weightUnit": "oz",
"variantTitle": "string",
"productId": "550e8400-e29b-41d4-a716-446655440000",
"variantId": "550e8400-e29b-41d4-a716-446655440000",
"requiresShipping": true,
"taxable": true,
"properties": {}
}
],
"totals": {
"subtotal": 49.99,
"shipping": 0,
"tax": 0,
"discount": 0,
"total": 49.99
},
"currency": "USD",
"tags": [
"string"
],
"note": "string",
"metadata": {
"custom": {}
},
"sourceData": {},
"orderedAt": "2026-07-23T12:00:00Z",
"createdAt": "2026-07-23T12:00:00Z",
"updatedAt": "2026-07-23T12:00:00Z"
}
}

404 Order not found

GET/api/v1/orders/{id}

Get single order

https://api-test.orderly-hub.com/api/v1/orders/

Update an order​

PATCH/api/v1/orders/{id}

Parameters​

NameInRequiredTypeDescription
idpathyesstring

Request body​

FieldTypeDescription
statusstring
paymentStatusstring
fulfillmentStatusstring
tagsarray
notestring
metadataOrderMetadataCustom order data stored under metadata.custom.
{
"status": "pending",
"paymentStatus": "pending",
"fulfillmentStatus": "pending",
"tags": [
"string"
],
"note": "string",
"metadata": {
"custom": {}
}
}

Responses​

200 Order updated

404 Order not found

PATCH/api/v1/orders/{id}

Update an order

https://api-test.orderly-hub.com/api/v1/orders/

Delete an order​

DELETE/api/v1/orders/{id}

Parameters​

NameInRequiredTypeDescription
idpathyesstring

Responses​

200 Order deleted

DELETE/api/v1/orders/{id}

Delete an order

https://api-test.orderly-hub.com/api/v1/orders/

Get order activity feed​

GET/api/v1/orders/{id}/activities

Parameters​

NameInRequiredTypeDescription
idpathyesstring
limitquerynointeger
offsetquerynointeger

Responses​

200 Activity list

404 Order not found

GET/api/v1/orders/{id}/activities

Get order activity feed

https://api-test.orderly-hub.com/api/v1/orders//activities

Add a note to an order​

POST/api/v1/orders/{id}/notes

Parameters​

NameInRequiredTypeDescription
idpathyesstring

Request body​

FieldTypeDescription
notestring
{
"note": "string"
}

Responses​

201 Note added

POST/api/v1/orders/{id}/notes

Add a note to an order

https://api-test.orderly-hub.com/api/v1/orders//notes