---
title: Orders
sort: 2
---

# Orders

An order is a committed cart with a charged payment method. Orders are immutable in all fields
except `status`, `fulfilment`, and `metadata`.

## Object

| Field                  | Type      | Notes                                                  |
|------------------------|-----------|--------------------------------------------------------|
| `id`                   | string    | `order_…`, ULID                                        |
| `cart_id`              | string    | `cart_…`, frozen at order creation                     |
| `customer_id`          | string?   | `cust_…` if a known customer                           |
| `line_items[]`         | array     | Snapshot of cart at order creation                     |
| `currency`             | string    | ISO 4217                                               |
| `subtotal_cents`       | integer   | Before tax + shipping                                  |
| `tax_total_cents`      | integer   |                                                        |
| `shipping_total_cents` | integer   |                                                        |
| `total_cents`          | integer   | Charged to the customer                                |
| `tax_calculation_source` | enum    | `zephyr`, `stripe_tax`, `avalara`                      |
| `status`               | enum      | `created`, `paid`, `partially_refunded`, `refunded`, `cancelled` |
| `livemode`             | boolean   | `false` in test mode                                   |
| `placed_at`            | timestamp | When the customer confirmed the order                  |

## Endpoints

| Method | Path                          | Purpose                              |
|--------|-------------------------------|--------------------------------------|
| `GET`  | `/v1/orders`                  | List, paginated                      |
| `GET`  | `/v1/orders/{id}`             | Retrieve                             |
| `PATCH`| `/v1/orders/{id}`             | Update (status, fulfilment, metadata only) |
| `POST` | `/v1/orders/{id}/refunds`     | Refund full or partial                |
| `POST` | `/v1/orders/{id}/cancel`      | Cancel before fulfilment              |

## Refunds

```bash
curl -sS https://api.zephyrcart.io/v1/orders/order_01HXY8.../refunds \
  -H "Authorization: Bearer $ZEPHYR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount_cents": 1490,
    "reason": "requested_by_customer",
    "metadata": { "ticket": "ZD-31427" }
  }'
```

`reason` is one of `requested_by_customer`, `duplicate`, `fraudulent`. The deprecated free-text
`note` field still works but will be removed in v2 — see the
[Changelog 2026-05-30](../changelog.md#2026-05-30--refunds-api).

## Cancellation

An order can be cancelled before its first fulfilment is recorded. After that, you refund instead.
The transition is irreversible.

```bash
curl -X POST https://api.zephyrcart.io/v1/orders/order_…/cancel \
  -H "Authorization: Bearer $ZEPHYR_API_KEY"
```

## Webhook events

- `order.created` — fired once, on placement.
- `order.updated` — fired on any mutable-field change.
- `order.refunded` — fired on each refund, including partials.
- `order.cancelled` — fired once.

Full reference: [Webhooks](webhooks.md).