Change a storefront order status
POST /rest/v1/storefront/orders/{id}/status
paid → fulfilled or canceled; pending → canceled; fulfilled → canceled. Other moves are 409 transition_not_allowed; an unknown order is 404 order_not_found. Canceling doesn't refund.
Required scope: orders:write.
Authorization
apiKey Authorization: Bearer nbl_live_... (or nbl_test_... for test mode). Test-mode writes are validated and simulated but never persisted and never touch channels; simulated results are marked simulated.
In: header
Path Parameters
Header Parameters
Unique client-generated key (max 255 chars), stored 24h.
length <= 255Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/storefront/orders/order_7KQ2M9XW4PZB/status" \ -H "Content-Type: application/json" \ -d '{ "status": "fulfilled" }'{ "id": "order_7KQ2M9XW4PZB", "object": "storefront_order", "status": "pending", "currency": "EUR", "subtotal": "15.90", "shipping": "5.00", "discount": "0.00", "discount_code": "string", "tax": "0.00", "total": "20.90", "refunded": "0.00", "buyer": { "email": "string", "name": "string", "phone": "string", "tax_ids": [ "string" ], "marketing_consent": true }, "billing_address": { "name": "string", "line1": "string", "line2": "string", "city": "string", "state": "string", "postal_code": "string", "country": "string" }, "shipping_address": { "name": "string", "line1": "string", "line2": "string", "city": "string", "state": "string", "postal_code": "string", "country": "string" }, "delivery_method": "shipping", "shipping_notes": "string", "lines": [ { "product_id": "prod_6ad22d0ee891b034a5693aa0", "variant_id": "string", "name": "string", "variant_title": "string", "sku": "string", "photo": "string", "quantity": 0, "unit_price": "15.90", "line_total": "15.90", "stock_shortfall": true } ], "payment": { "provider": "stripe", "paid_at": "2019-08-24T14:15:22Z" }, "tracking": { "number": "string", "carrier": "string", "url": "string" }, "created_at": "2019-08-24T14:15:22Z", "fulfilled_at": "2019-08-24T14:15:22Z", "refunded_at": "2019-08-24T14:15:22Z", "simulated": true}Last updated on October 18, 2026
Need help?
Email us and a human replies, usually within one business day.