Orders API

Scopes: orders.read / orders.write / fulfillments.write

List orders

GET /v1/orders?status=paid&updated_since=2026-08-01T00:00:00Z&limit=100&cursor=...

Get order

GET /v1/orders/{id}

Includes line items, totals, payment summary, fulfillment state. PII fields may be masked by plan/policy.

Update merchant note / ops fields

PATCH /v1/orders/{id}

{ "merchant_note": "Call before delivery" }

Cancel

POST /v1/orders/{id}/cancel
Idempotency-Key: ...

Create fulfillment

POST /v1/orders/{id}/fulfillments
Idempotency-Key: ...

{
  "tracking_number": "1Z…",
  "carrier": "ups",
  "items": [{ "line_item_id": "li_…", "quantity": 1 }]
}

Refund

POST /v1/orders/{id}/refunds
Idempotency-Key: ...

Requires payment scopes / PSP linkage; never send card data.

Webhooks: order.created | order.paid | order.fulfilled | order.cancelled | …