Apply Coupon
kit.checkout.applyCoupon()
elements flow, recalculating and updating the underlying PaymentIntent's amount.Signature
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
checkoutId | string | Yes | The session to apply the coupon to. |
couponCode | string|null | Yes | The code to apply, or null to remove any currently applied coupon and reset to originalAmount. |
originalAmount | number | Yes | The pre-discount amount in minor currency units, used as the baseline for the discount calculation and as the fallback if couponCode is null. |
paymentIntentId | string|null | No | Unused directly; the session's own stored PaymentIntent ID is used instead. |
Example request
Example response
Errors
| Exception | When |
|---|---|
NotFoundError | The checkout session was not found. |
ConfigurationError | The coupons module isn't attached, which should never happen in normal use. |
ValidationError | couponCode is invalid or expired; or the session has no active PaymentIntent to discount (for example, an api flow session, or a subscription checkout with no elements-flow PaymentIntent). |
StripeOperationError | Stripe rejects the amount update. |
Notes
elements flow. api-flow (hosted Checkout Session) discounts are applied at creation time via couponCode on create() instead, since Stripe Checkout Sessions can't have their line items changed after creation.0, clientSecret is null and no PaymentIntent update is attempted, since a PaymentIntent cannot have an amount of 0. Your frontend should treat isFree: true as "nothing left to confirm, mark the order complete directly."percent coupons multiply originalAmount by (1 - discountValue / 100); amount coupons subtract discountValue (in major units) converted to minor units. Both are rounded and floored at 0.