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


curl -X GET "https://api.orderly.dev/api/orders?status=pending&limit=50" \
  -H "Authorization: Bearer ord_sk_..."

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",
      "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/orders/:id

Retrieve a single order by ID.

Requiredorders:read

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


curl -X GET "https://api.orderly.dev/api/orders/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer ord_sk_..."

Update Order

PATCH/api/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.dev/api/orders/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer ord_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"status": "processing", "notes": "Rush order"}'

Get Order Activities

GET/api/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.dev/api/orders/550e8400-e29b-41d4-a716-446655440000/activities" \
  -H "Authorization: Bearer ord_sk_..."

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"
    }
  ]
}