Changes
Comparing empty → 160dc49.
| @@ -1,0 +1,73 @@ | ||
| 1 | +--- | |
| 2 | +title: Orders | |
| 3 | +sort: 2 | |
| 4 | +--- | |
| 5 | + | |
| 6 | +# Orders | |
| 7 | + | |
| 8 | +An order is a committed cart with a charged payment method. Orders are immutable in all fields | |
| 9 | +except `status`, `fulfilment`, and `metadata`. | |
| 10 | + | |
| 11 | +## Object | |
| 12 | + | |
| 13 | +| Field | Type | Notes | | |
| 14 | +|------------------------|-----------|--------------------------------------------------------| | |
| 15 | +| `id` | string | `order_…`, ULID | | |
| 16 | +| `cart_id` | string | `cart_…`, frozen at order creation | | |
| 17 | +| `customer_id` | string? | `cust_…` if a known customer | | |
| 18 | +| `line_items[]` | array | Snapshot of cart at order creation | | |
| 19 | +| `currency` | string | ISO 4217 | | |
| 20 | +| `subtotal_cents` | integer | Before tax + shipping | | |
| 21 | +| `tax_total_cents` | integer | | | |
| 22 | +| `shipping_total_cents` | integer | | | |
| 23 | +| `total_cents` | integer | Charged to the customer | | |
| 24 | +| `tax_calculation_source` | enum | `zephyr`, `stripe_tax`, `avalara` | | |
| 25 | +| `status` | enum | `created`, `paid`, `partially_refunded`, `refunded`, `cancelled` | | |
| 26 | +| `livemode` | boolean | `false` in test mode | | |
| 27 | +| `placed_at` | timestamp | When the customer confirmed the order | | |
| 28 | + | |
| 29 | +## Endpoints | |
| 30 | + | |
| 31 | +| Method | Path | Purpose | | |
| 32 | +|--------|-------------------------------|--------------------------------------| | |
| 33 | +| `GET` | `/v1/orders` | List, paginated | | |
| 34 | +| `GET` | `/v1/orders/{id}` | Retrieve | | |
| 35 | +| `PATCH`| `/v1/orders/{id}` | Update (status, fulfilment, metadata only) | | |
| 36 | +| `POST` | `/v1/orders/{id}/refunds` | Refund full or partial | | |
| 37 | +| `POST` | `/v1/orders/{id}/cancel` | Cancel before fulfilment | | |
| 38 | + | |
| 39 | +## Refunds | |
| 40 | + | |
| 41 | +```bash | |
| 42 | +curl -sS https://api.zephyrcart.io/v1/orders/order_01HXY8.../refunds \ | |
| 43 | + -H "Authorization: Bearer $ZEPHYR_API_KEY" \ | |
| 44 | + -H "Idempotency-Key: $(uuidgen)" \ | |
| 45 | + -d '{ | |
| 46 | + "amount_cents": 1490, | |
| 47 | + "reason": "requested_by_customer", | |
| 48 | + "metadata": { "ticket": "ZD-31427" } | |
| 49 | + }' | |
| 50 | +``` | |
| 51 | + | |
| 52 | +`reason` is one of `requested_by_customer`, `duplicate`, `fraudulent`. The deprecated free-text | |
| 53 | +`note` field still works but will be removed in v2 — see the | |
| 54 | +[Changelog 2026-05-30](../changelog.md#2026-05-30--refunds-api). | |
| 55 | + | |
| 56 | +## Cancellation | |
| 57 | + | |
| 58 | +An order can be cancelled before its first fulfilment is recorded. After that, you refund instead. | |
| 59 | +The transition is irreversible. | |
| 60 | + | |
| 61 | +```bash | |
| 62 | +curl -X POST https://api.zephyrcart.io/v1/orders/order_…/cancel \ | |
| 63 | + -H "Authorization: Bearer $ZEPHYR_API_KEY" | |
| 64 | +``` | |
| 65 | + | |
| 66 | +## Webhook events | |
| 67 | + | |
| 68 | +- `order.created` — fired once, on placement. | |
| 69 | +- `order.updated` — fired on any mutable-field change. | |
| 70 | +- `order.refunded` — fired on each refund, including partials. | |
| 71 | +- `order.cancelled` — fired once. | |
| 72 | + | |
| 73 | +Full reference: [Webhooks](webhooks.md). | |