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

GET/api/v1/orders

Parameters

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
bridgeId	query	no	string
search	query	no	string	Search by order number or external ID
include	query	no	string	Comma-separated: bridge, dispatch_assignments

Responses

200 Paginated order list

Order[] object:

Field	Type	Description
id	string
organizationId	string
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
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",
      "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": null,
          "externalId": null,
          "sku": null,
          "name": null,
          "quantity": null,
          "unitPrice": null,
          "totalPrice": null,
          "weight": null,
          "weightUnit": null,
          "variantTitle": null,
          "productId": null,
          "variantId": null,
          "requiresShipping": null,
          "taxable": null,
          "properties": null
        }
      ],
      "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": 49.99,
    "totalPages": 0,
    "hasMore": true
  }
}

GET/api/v1/orders

List orders

API key (Bearer token)

page (query)

limit (query)

status (query)

bridgeId (query)

search (query)

include (query)

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

Create an order

POST/api/v1/orders

Request 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
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",
    "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

API key (Bearer token)

Request body (JSON){ "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" }

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

Get single order

GET/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
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",
    "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

API key (Bearer token)

id * (path)

include (query)

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

Update an order

PATCH/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

PATCH/api/v1/orders/{id}

Update an order

API key (Bearer token)

id * (path)

Request body (JSON){ "status": "pending", "paymentStatus": "pending", "fulfillmentStatus": "pending", "tags": [ "string" ], "note": "string", "metadata": { "custom": {} } }

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

Delete an order

DELETE/api/v1/orders/{id}

Parameters

Name	In	Required	Type	Description
id	path	yes	string

Responses

200 Order deleted

DELETE/api/v1/orders/{id}

Delete an order

API key (Bearer token)

id * (path)

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

Get order activity feed

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

Parameters

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

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

Get order activity feed

API key (Bearer token)

id * (path)

limit (query)

offset (query)

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

Add a note to an order

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

Parameters

Name	In	Required	Type	Description
id	path	yes	string

Request body

Field	Type	Description
note	string

{
  "note": "string"
}

Responses

201 Note added

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

Add a note to an order

API key (Bearer token)

id * (path)

Request body (JSON){ "note": "string" }

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