Orders + fulfillment
Operate the post-purchase work: fulfill orders, issue refunds, and handle returns or exchanges.
Merchant-side state machine — list, fulfill, refund, returns, exchanges. Bearer required.
Orders are the post-payment state machine: pending → fulfilled → (optionally) returned or refunded. Merchant endpoints require read:orders or write:orders.
List orders
bash
curl "https://aly.store/api/storefront/v1/merchant/orders?status=pending&limit=25" \ -H "Authorization: Bearer aly_..."Filters
| Param | Type |
|---|---|
status | pending | fulfilled | cancelled | refunded | returned |
customer_id | string |
site_slug | string |
created_after / created_before | ISO-8601 |
limit / cursor | pagination |
Get one
bash
curl https://aly.store/api/storefront/v1/merchant/orders/ord_72...4b \ -H "Authorization: Bearer aly_..."Fulfill
Record a shipment.
bash
curl -X POST https://aly.store/api/storefront/v1/merchant/orders/ord_72...4b/fulfill \ -H "Authorization: Bearer aly_..." \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "carrier": "USPS", "tracking_number": "9400111202555582846137", "items": [ { "line_item_id": "li_1", "quantity": 1 } ] }'Partial fulfillment is supported — fulfill some line items now, others later. Order status moves to fulfilled when every item is shipped.
Refund
bash
curl -X POST https://aly.store/api/storefront/v1/merchant/orders/ord_72...4b/refund \ -H "Authorization: Bearer aly_..." \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "amount": 5076, "reason": "Buyer request" }'Omit amount for a full refund. Stripe processes asynchronously; the order moves to refunded when the Stripe webhook lands.
Returns
Returns are a small state machine:
POST /merchant/orders/{id}/returns— create a return request with the items and reason.POST /merchant/orders/{id}/returns/{returnId}/approve— operator approval. Issues an RMA.POST /merchant/orders/{id}/returns/{returnId}/receive— mark items received in good condition.POST /merchant/orders/{id}/returns/{returnId}/reject— reject the return.
Exchanges
Same shape as returns but with a target variant for the replacement.
bash
curl -X POST https://aly.store/api/storefront/v1/merchant/orders/ord_72...4b/exchanges \ -H "Authorization: Bearer aly_..." \ -H "Content-Type: application/json" \ -d '{ "items": [ { "line_item_id": "li_1", "quantity": 1, "new_variant_id": "var_2" } ], "reason": "Wrong color" }'Order shape
json
{ "id": "ord_72...4b", "site_slug": "acme", "status": "pending", "fulfillment_status": "unfulfilled", "buyer": { "email": "buyer@example.com", "name": "A. Buyer" }, "shipping_address": { ... }, "billing_address": { ... }, "items": [ { "id": "li_1", "product_id": "prod_abc", "variant_id": "var_1", "name": "Linen Tote — natural", "quantity": 1, "unit_price": 4200, "subtotal": 4200 } ], "totals": { "subtotal": 4200, "shipping": 500, "tax": 376, "discount": 0, "total": 5076 }, "currency": "USD", "payment": { "provider": "stripe", "intent_id": "pi_..." }, "fulfillments": [], "returns": [], "exchanges": [], "created_at": "..."}Subscribe to webhooks
Polling
orders.list works but the event-driven path is cheaper. Subscribe to order.created, order.fulfilled,order.refunded via Webhooks.Was this page helpful?