Skip to main content

Apply a coupon to an order

POST 
/v1/orders/:id/coupon

Redeems a coupon code on an order and returns it with the totals recalculated.

Only the coupon code is accepted here — the currency and timezone always come from your company.

Only orders created through the API can be changed here. An order taken on the storefront, the POS or a food app belongs to that channel and answers 422 order_not_modifiable.

How the coupon behaves on the order

  • The discount is applied immediately: total_discounts and total are recalculated and saved when this call returns, not when the order is paid. Charge the returned total.
  • The order status is not checked: a coupon can be redeemed at any point of the order lifecycle, so apply it before taking the payment.
  • One coupon per order. A second coupon answers 422 validation_failed. A manual discount added through POST /v1/orders/{id}/discounts can coexist with a coupon.
  • The coupon minimum amount is compared against the order total, after any discount already on the order.
  • The order must have a customer attached (client); otherwise the request fails with 422.
  • If the items change later, a percentage coupon is recalculated on the new items total; a fixed-amount coupon keeps its value.
  • The coupon eligibility rules are the ones configured on the promotion: service type, validity dates and weekly schedule (evaluated in your company timezone), usage limit, once per customer, new customers only, and — for product-restricted promotions — at least one matching item in the order.

A coupon that exists but is not eligible for this order — usage limit reached, once per customer, or restricted to a service type or to new customers — answers 422 coupon_not_applicable with the reason in detail. An unknown coupon code or an unknown order both answer a generic 404 not_found.

To remove a coupon, use DELETE /v1/orders/{id}/discounts/{discountId} with the discount id the coupon created. Removing it does not give the redemption back to the coupon usage count.

Required scope: orders:write

Request​

Responses​

The order with the coupon applied.