Apply Coupon

Apply a discount coupon code to the shopping cart.

Endpoint

POST /api/shop/apply-coupon

Request Headers

Header	Required	Description
Content-Type	Yes	application/json
X-STOREFRONT-KEY	Yes	Your storefront API key
Authorization	Yes	The cart's own token as a Bearer token, or a logged-in customer's token.

Request Body

{
  "couponCode": "SAVE20"
}

Field	Type	Required	Description
couponCode	string	Yes	The coupon to apply. The field is couponCode — code is not read, and its absence fails with Coupon code is required.

Response

201 Created carrying the whole recalculated cart — the same object Get Cart returns, plus two fields describing the attempt.

Field	Type	Description
success	boolean	true when the coupon was applied.
message	string	Coupon applied successfully or Failed to apply coupon.
couponCode	string	The applied code. null when the attempt failed.
discountAmount / formattedDiscountAmount	number / string	The discount now on the cart.
grandTotal / formattedGrandTotal	number / string	The recalculated total.

A rejected coupon still answers 201 with the full cart untouched, so the status code alone never tells you whether the discount applied.

Validation

Rule	Result
couponCode present	Missing → 400 Coupon code is required.
The code exists on an active cart rule	Otherwise success: false, Failed to apply coupon.
The cart satisfies the rule's conditions	Same failure — the message does not distinguish "unknown code" from "conditions not met".

Applying a second coupon replaces the first; a cart holds one coupon at a time.

Use Cases

• Coupon field at checkout — post the typed code, then branch on success and re-render the totals straight from the response.
• Show the discount immediately — the response is the recalculated cart, so no follow-up Get Cart is needed.

Best Practices

• Branch on success, never on the status code — a wrong code and a valid one both answer 201.
• Use couponCode, not code — the wrong key is treated as a missing coupon.
• Show the store's own message with care — one generic failure string covers unknown, expired, and non-qualifying codes, so a UI that says "coupon does not exist" will sometimes be wrong.
• Re-read grandTotal after applying — the discount changes shipping and tax lines as well as the subtotal.

Related Resources

• Remove Coupon — clear the applied coupon and recalculate
• Get Cart — read the current items and recalculated totals