Refund a storefront order
POST /rest/v1/storefront/orders/{id}/refund
Sends the money back through Stripe/PayPal. Irreversible: asks the two-step confirmation, only once the refund is possible. An unknown order is 404 order_not_found, a fully refunded one 409 already_refunded, an unpaid one 409 order_not_paid, an amount above what's left a 422, all before any confirmation. Without amount, refunds everything left.
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 <= 255The one-time token from a 409 confirmation_required answer, to confirm an irreversible action (repeat the same request with it, within 10 minutes).
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/storefront/orders/order_7KQ2M9XW4PZB/refund" \ -H "Content-Type: application/json" \ -d '{}'{ "object": "refund", "order_id": "order_7KQ2M9XW4PZB", "amount": "12.50", "currency": "string", "provider_refund_id": "string", "order": { "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 }, "simulated": true}Last updated on October 18, 2026
Need help?
Email us and a human replies, usually within one business day.