Orders API

Create and track service orders (pickup + sharpening + delivery).

Required scope: orders:read for GET, orders:write for POST

List Orders

GET /v1/orders

Query Parameters

| Param | Type | Description | |-------|------|-------------| | status | string | Filter: pending, scheduled, in_service, completed, etc. | | from | ISO date | Created at or after this date | | to | ISO date | Created at or before this date | | limit | integer | Default 25, max 100 | | after | string | Cursor for next page |

Response

{
  "data": [
    {
      "id": "ord_abc123",
      "order_number": "BS-2026-0042",
      "status": "in_service",
      "part_count": 8,
      "total_cents": 19200,
      "pickup_date": "2026-03-10T09:00:00Z",
      "expected_return_date": "2026-03-12T17:00:00Z",
      "created_at": "2026-03-08T14:00:00Z"
    }
  ],
  "meta": { "total": 12, "next_cursor": null }
}

Get an Order

GET /v1/orders/:id

Returns the full order including part list and status timeline.

Create an Order

POST /v1/orders

Body

{
  "part_ids": ["part_abc123", "part_def456"],
  "pickup_window_start": "2026-03-15T08:00:00Z",
  "pickup_window_end": "2026-03-15T12:00:00Z",
  "instructions": "Leave with reception if no one available"
}

Response 201 Created

{
  "data": {
    "id": "ord_xyz789",
    "order_number": "BS-2026-0043",
    "status": "pending",
    ...
  }
}

Order Status Timeline

GET /v1/orders/:id/timeline

{
  "data": [
    { "status": "pending",   "occurred_at": "2026-03-08T14:00:00Z", "actor": "api" },
    { "status": "scheduled", "occurred_at": "2026-03-09T09:00:00Z", "actor": "ops" },
    { "status": "picked_up", "occurred_at": "2026-03-10T09:15:00Z", "actor": "driver" }
  ]
}