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

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.

Cancellation

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

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.