Orders

Manage orders synced from your e-commerce bridges. Orders are the primary data model in Orderly, representing customer purchases flowing through your fulfillment pipeline.

List Orders

GET/api/v1/orders

List all orders with filtering, sorting, and pagination.

Requiredorders:read

Returns a paginated list of orders for the current organization. Supports filtering by status, source bridge, date range, and search.

Query Parameters

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20, max: 100)
`status`	string	Filter by status: `pending`, `processing`, `shipped`, `delivered`, `cancelled`
`bridge_id`	string	Filter by source bridge ID
`search`	string	Search by order number, customer name, or email
`sort`	string	Sort field (default: `created_at`)
`order`	string	Sort direction: `asc` or `desc` (default: `desc`)
`since`	string	ISO 8601 date — only orders created after this time
`include`	string	Comma-separated related resources to include: `bridge`, `dispatch_assignments`


curl -X GET "https://api.orderly-hub.com/api/v1/orders?status=pending&limit=50&include=bridge,dispatch_assignments" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": [
    {
      "id": "uuid",
      "order_number": "1001",
      "status": "pending",
      "customer": { "name": "Jane Doe", "email": "jane@example.com" },
      "line_items": [...],
      "total": 49.99,
      "currency": "USD",
      "bridge_id": "uuid",
      "external_id": "ext_123",
      "sent_to_fulfillment": "2026-01-15T11:00:00Z",
      "sent_to_cart": null,
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 328,
    "totalPages": 7,
    "hasMore": true
  }
}

Get Order

GET/api/v1/orders/:id

Retrieve a single order by ID.

Requiredorders:read

Returns the full order object including line items, customer details, shipping address, and metadata.

Supports include query parameter to include related resources: bridge, dispatch_assignments.


curl -X GET "https://api.orderly-hub.com/api/v1/orders/550e8400-e29b-41d4-a716-446655440000?include=bridge,dispatch_assignments" \
  -H "Authorization: Bearer oh_..."

Create Order

POST/api/v1/orders

Create a new order.

Requiredorders:write

Creates a new order linked to a bridge. The bridge must exist and belong to the current organization. If an order with the same external ID already exists, a 409 Conflict is returned. After creation, split rules are automatically evaluated.

Request Body

Field	Type	Required	Description
`bridge_id`	string	Yes	Bridge UUID the order originates from
`external_id`	string	Yes	Unique external identifier from the source system
`order_number`	string	No	Human-readable order number
`status`	string	Yes	Order status: `pending`, `confirmed`, `processing`, `shipped`, `delivered`, `cancelled`, `refunded`, `on_hold`
`payment_status`	string	No	Payment status (default: `pending`): `pending`, `authorized`, `paid`, `partially_paid`, `refunded`, `voided`
`fulfillment_status`	string	No	Fulfillment status (default: `unfulfilled`): `unfulfilled`, `partial`, `fulfilled`
`customer`	object	Yes	Customer object with `email` (required), `firstName`, `lastName`, `phone`
`shipping_address`	object	No	Shipping address
`billing_address`	object	No	Billing address
`line_items`	object[]	Yes	Array of line items (at least one). Each requires `sku`, `name`, `quantity`, `unitPrice`, `totalPrice`, `requiresShipping`, `taxable`
`totals`	object	Yes	Order totals: `subtotal`, `shipping`, `tax`, `discount`, `total`
`currency`	string	No	ISO 4217 currency code (default: `USD`)
`tags`	string[]	No	Order tags
`note`	string	No	Internal note
`metadata`	object	No	Custom key-value metadata
`source_data`	object	No	Raw source data from the originating system
`ordered_at`	string	No	ISO 8601 date when the order was placed (default: now)


curl -X POST "https://api.orderly-hub.com/api/v1/orders" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "bridge_id": "550e8400-e29b-41d4-a716-446655440000",
    "external_id": "shopify_5001",
    "order_number": "1042",
    "status": "pending",
    "customer": {
      "email": "jane@example.com",
      "firstName": "Jane",
      "lastName": "Doe"
    },
    "line_items": [
      {
        "sku": "WIDGET-001",
        "name": "Blue Widget",
        "quantity": 2,
        "unitPrice": 19.99,
        "totalPrice": 39.98,
        "requiresShipping": true,
        "taxable": true
      }
    ],
    "totals": {
      "subtotal": 39.98,
      "shipping": 5.99,
      "tax": 3.20,
      "discount": 0,
      "total": 49.17
    },
    "currency": "USD"
  }'

Response (201 Created)


{
  "data": {
    "id": "uuid",
    "organizationId": "uuid",
    "bridgeId": "uuid",
    "externalId": "shopify_5001",
    "orderNumber": "1042",
    "status": "pending",
    "paymentStatus": "pending",
    "fulfillmentStatus": "unfulfilled",
    "customer": {
      "email": "jane@example.com",
      "firstName": "Jane",
      "lastName": "Doe"
    },
    "lineItems": [...],
    "totals": {
      "subtotal": 39.98,
      "shipping": 5.99,
      "tax": 3.20,
      "discount": 0,
      "total": 49.17
    },
    "currency": "USD",
    "tags": [],
    "metadata": {},
    "orderedAt": "2026-01-15T10:30:00Z",
    "createdAt": "2026-01-15T10:30:00Z",
    "updatedAt": "2026-01-15T10:30:00Z"
  }
}

Update Order

PATCH/api/v1/orders/:id

Update an order's editable fields.

Requiredorders:write

Updates an order. Only certain fields can be modified depending on the order’s current status. Orders that have been shipped or delivered cannot have their line items changed.

Request Body

Field	Type	Description
`status`	string	New status
`shipping_address`	object	Updated shipping address
`notes`	string	Internal notes
`metadata`	object	Custom key-value metadata
`tags`	string[]	Order tags


curl -X PATCH "https://api.orderly-hub.com/api/v1/orders/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{"status": "processing", "notes": "Rush order"}'

Delete Order

DELETE/api/v1/orders/:id

Permanently delete an order.

Requiredorders:write

Permanently deletes an order from the organization. This action cannot be undone.


curl -X DELETE "https://api.orderly-hub.com/api/v1/orders/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer oh_..."

Response


{
  "success": true
}

Get Order Activities

GET/api/v1/orders/:id/activities

List the activity log for an order.

Requiredorders:read

Returns a chronological list of activities for an order, including status changes, sync events, edits, and fulfillment updates.


curl -X GET "https://api.orderly-hub.com/api/v1/orders/550e8400-e29b-41d4-a716-446655440000/activities" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": [
    {
      "id": "uuid",
      "type": "status_change",
      "description": "Status changed from pending to processing",
      "actor": { "type": "user", "id": "uuid", "name": "Jane Doe" },
      "metadata": { "from": "pending", "to": "processing" },
      "created_at": "2026-01-15T11:00:00Z"
    }
  ]
}

Add Note to Order

POST/api/v1/orders/:id/notes

Add a note to an order's activity log.

Requiredorders:write

Adds a note entry to the order’s activity timeline. Notes are attributed to the authenticated user and appear alongside other order activities.

Request Body

Field	Type	Required	Description
`note`	string	Yes	The note text to add


curl -X POST "https://api.orderly-hub.com/api/v1/orders/550e8400-e29b-41d4-a716-446655440000/notes" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{"note": "Customer called to confirm delivery window."}'

Response (201 Created)


{
  "data": {
    "id": "uuid",
    "type": "note",
    "description": "Customer called to confirm delivery window.",
    "actor": { "type": "user", "id": "uuid", "name": "jane@example.com" },
    "created_at": "2026-01-15T11:30:00Z"
  }
}

Resync Order

POST/api/v1/orders/:id/resync

Resync an order from its source bridge.

Requiredorders:write

Triggers a fresh sync of the order from its originating bridge. This re-fetches the order data from the external system and updates the local record with the latest information. Useful when manual changes were made in the source system.


curl -X POST "https://api.orderly-hub.com/api/v1/orders/550e8400-e29b-41d4-a716-446655440000/resync" \
  -H "Authorization: Bearer oh_..."

Response


{
  "data": {
    "id": "uuid",
    "status": "queued",
    "message": "Order resync has been queued"
  }
}