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
| Field | Type | Description |
|---|---|---|
id | string | Customer identifier from the source platform |
email | string | Customer email address |
firstName | string | First name |
lastName | string | Last name |
phone | string | Phone number |
shippingAddress and billingAddress
| Field | Type | Description |
|---|---|---|
name | string | Full recipient name |
company | string | Company name |
address1 | string | Address line 1 |
address2 | string | Address line 2 |
city | string | City |
province | string | State or province |
provinceCode | string | State or province code |
zip | string | Postal code |
country | string | Country name |
countryCode | string | Two-letter country code |
phone | string | Recipient phone |
email | string | Recipient email |
lineItems[]
| Field | Type | Description |
|---|---|---|
id | string | Orderly line-item identifier |
externalId | string | Source-platform line-item identifier |
sku | string | Stock keeping unit |
name | string | Product or line title |
quantity | number | Units ordered |
unitPrice | number | Per-unit price in the order currency |
totalPrice | number | Extended line total |
weight | number | Unit weight |
weightUnit | string | oz, lb, g, or kg |
variantTitle | string | Variant title |
productId | string | Source product identifier |
variantId | string | Source variant identifier |
requiresShipping | boolean | Whether the item ships physically |
taxable | boolean | Whether the item is taxable |
properties | object | Customer-defined SKU fields; keys are preserved exactly |
totals
| Field | Type | Description |
|---|---|---|
subtotal | number | Merchandise subtotal |
shipping | number | Shipping amount |
tax | number | Tax amount |
discount | number | Discount amount |
total | number | Final order total |
All totals use the order's currency.
metadata
| Field | Type | Description |
|---|---|---|
custom | object | Custom nested fields; keys are preserved exactly |
Use metadata.custom for custom order data in Orders API requests and responses.
List orders
/api/v1/ordersParameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
page | query | no | integer | |
limit | query | no | integer | Number of orders per page, from 1 to 500 |
status | query | no | string | Order status. Comma-separated list. Allowed values: pending, confirmed, processing, shipped, delivered, cancelled, refunded, on_hold. |
fulfillmentStatus | query | no | string | Fulfillment status. partially_fulfilled is an alias of partial. Comma-separated list. Allowed values: unfulfilled, partial, partially_fulfilled, fulfilled. |
paymentStatus | query | no | string | Payment status. Comma-separated list. Allowed values: pending, authorized, paid, partially_paid, refunded, voided. |
lifecycleState | query | no | string | Lifecycle 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. |
priority | query | no | string | Fulfillment priority. Comma-separated list. Allowed values: low, normal, high, urgent. |
tags | query | no | string | Comma-separated tags, up to 50 values of 100 characters. Matching follows tagsMode. |
tagsMode | query | no | any | all | any matches orders with at least one listed tag, all requires every listed tag. |
fulfillmentLocationId | query | no | string | A location UUID, or the literal unassigned for orders with no fulfillment location. |
bridgeId | query | no | string | |
search | query | no | string | Case-insensitive match on order number, external ID, or customer email. The * character is stripped. |
customer | query | no | string | Case-insensitive contains match on customer name or email. The * character is stripped. |
shipToCity | query | no | string | Case-insensitive contains match on the ship-to city. The * character is stripped. |
shipToState | query | no | string | Case-insensitive match on the ship-to state or province. The * character is stripped. |
shipToCountry | query | no | string | Case-insensitive match on the ship-to country. The * character is stripped. |
shipToPostalCode | query | no | string | Case-insensitive prefix match on the ship-to postal code. The * character is stripped. |
sku | query | no | string | Orders with a line item carrying exactly this SKU. |
minTotal | query | no | number | Minimum order total, inclusive. |
maxTotal | query | no | number | Maximum order total, inclusive. |
carrier | query | no | string | Case-insensitive match on the carrier of the assigned shipping service. Cannot be combined with hasService=false. |
service | query | no | string | Case-insensitive contains match on the assigned service code. Cannot be combined with hasService=false. |
hasService | query | no | true | false | true returns orders with an assigned shipping service, false returns orders without one. false cannot be combined with carrier or service. |
labelStatus | query | no | string | Label 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. |
orderedFrom | query | no | string | Earliest order time, inclusive. A YYYY-MM-DD date (start of day, UTC) or an ISO datetime with offset. |
orderedTo | query | no | string | Latest order time, inclusive. A YYYY-MM-DD date (end of day, UTC) or an ISO datetime with offset. |
requestedShipFrom | query | no | string | Earliest requested ship date, inclusive. |
requestedShipTo | query | no | string | Latest requested ship date, inclusive. |
attention | query | no | true | false | true returns unfulfilled, non-cancelled, non-refunded orders placed more than three days ago. |
sort | query | no | ordered_at | created_at | requested_ship_date | total | order_number | Sort key. Ties are broken by order id so pages are stable. |
sortDir | query | no | asc | desc | Sort direction. Defaults to desc for ordered_at, created_at and total, and asc for requested_ship_date and order_number. |
fields | query | no | ids | When ids, data is an array of order UUID strings instead of order objects. Pagination is unchanged. |
include | query | no | string | Comma-separated: bridge, dispatch_assignments |
Responses
200 Paginated order list. With fields=ids, data is an array of order UUID strings.
Order[] object:
| Field | Type | Description |
|---|---|---|
id | string | |
organizationId | string | |
bridgeId | string | |
externalId | string | |
orderNumber | string | |
status | string | |
statusDetail | string | |
sourceSystem | string | |
sourceRecordId | string | |
ingestMethod | string | |
trackingLifecycleId | string | |
paymentStatus | string | |
fulfillmentStatus | string | |
customer | Customer | |
shippingAddress | Address | |
billingAddress | Address | |
lineItems | LineItem[] | |
totals | OrderTotals | |
currency | string | |
tags | array | |
note | string | |
metadata | OrderMetadata | Custom order data stored under metadata.custom. |
sourceData | object | |
orderedAt | string | |
createdAt | string | |
updatedAt | string |
{
"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)
/api/v1/ordersList orders
https://api-test.orderly-hub.com/api/v1/ordersCreate an order
/api/v1/ordersRequest body
| Field | Type | Description |
|---|---|---|
bridgeId | string | |
externalId | string | |
orderNumber | string | |
status | string | |
paymentStatus | string | |
fulfillmentStatus | string | |
customer | Customer | |
shippingAddress | Address | |
billingAddress | Address | |
lineItems | LineItem[] | |
totals | OrderTotals | |
currency | string | |
tags | array | |
note | string | |
metadata | OrderMetadata | Custom order data stored under metadata.custom. |
sourceData | object | |
orderedAt | string |
{
"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:
| Field | Type | Description |
|---|---|---|
id | string | |
organizationId | string | |
bridgeId | string | |
externalId | string | |
orderNumber | string | |
status | string | |
statusDetail | string | |
sourceSystem | string | |
sourceRecordId | string | |
ingestMethod | string | |
trackingLifecycleId | string | |
paymentStatus | string | |
fulfillmentStatus | string | |
customer | Customer | |
shippingAddress | Address | |
billingAddress | Address | |
lineItems | LineItem[] | |
totals | OrderTotals | |
currency | string | |
tags | array | |
note | string | |
metadata | OrderMetadata | Custom order data stored under metadata.custom. |
sourceData | object | |
orderedAt | string | |
createdAt | string | |
updatedAt | string |
{
"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
/api/v1/ordersCreate an order
https://api-test.orderly-hub.com/api/v1/ordersGet single order
/api/v1/orders/{id}Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
id | path | yes | string | |
include | query | no | string | Comma-separated: bridge, dispatch_assignments |
Responses
200 Order details
Order object:
| Field | Type | Description |
|---|---|---|
id | string | |
organizationId | string | |
bridgeId | string | |
externalId | string | |
orderNumber | string | |
status | string | |
statusDetail | string | |
sourceSystem | string | |
sourceRecordId | string | |
ingestMethod | string | |
trackingLifecycleId | string | |
paymentStatus | string | |
fulfillmentStatus | string | |
customer | Customer | |
shippingAddress | Address | |
billingAddress | Address | |
lineItems | LineItem[] | |
totals | OrderTotals | |
currency | string | |
tags | array | |
note | string | |
metadata | OrderMetadata | Custom order data stored under metadata.custom. |
sourceData | object | |
orderedAt | string | |
createdAt | string | |
updatedAt | string |
{
"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
/api/v1/orders/{id}Get single order
https://api-test.orderly-hub.com/api/v1/orders/Update an order
/api/v1/orders/{id}Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
id | path | yes | string |
Request body
| Field | Type | Description |
|---|---|---|
status | string | |
paymentStatus | string | |
fulfillmentStatus | string | |
tags | array | |
note | string | |
metadata | OrderMetadata | Custom 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
/api/v1/orders/{id}Update an order
https://api-test.orderly-hub.com/api/v1/orders/Delete an order
/api/v1/orders/{id}Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
id | path | yes | string |
Responses
200 Order deleted
/api/v1/orders/{id}Delete an order
https://api-test.orderly-hub.com/api/v1/orders/Get order activity feed
/api/v1/orders/{id}/activitiesParameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
id | path | yes | string | |
limit | query | no | integer | |
offset | query | no | integer |
Responses
200 Activity list
404 Order not found
/api/v1/orders/{id}/activitiesGet order activity feed
https://api-test.orderly-hub.com/api/v1/orders//activitiesAdd a note to an order
/api/v1/orders/{id}/notesParameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
id | path | yes | string |
Request body
| Field | Type | Description |
|---|---|---|
note | string |
{
"note": "string"
}
Responses
201 Note added
/api/v1/orders/{id}/notesAdd a note to an order
https://api-test.orderly-hub.com/api/v1/orders//notes