Sample - Stripe API
POST/v1/coupons/{coupon}

Update a coupon

Updates the metadata and display name of an existing coupon. Supply only editable fields such as name, metadata, or amount-based currency_options; coupon currency, duration, and discount amount details cannot be changed.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.
  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 4 body fields
couponstringrequired
The unique identifier of the coupon to update.

Optional coupon update fields for editable metadata, display name, currency options, and expanded response fields.

currency_optionsobjectoptional
Coupons defined in each available currency option (only supported if the coupon is amount-based). Each key must be a three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) and a [supported currency](https://stripe.com/docs/currencies).
expandarray<string>optional
Specifies which fields in the response should be expanded.
metadataobjectoptional
Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`.
namestringoptional
Name of the coupon displayed to customers on, for instance invoices, or receipts. By default the `id` is shown if `name` is not set.

2 status codes
200Returns the updated coupon object with its editable name, metadata, and currency options.
amount_offintegeroptional
Amount (in the `currency` specified) that will be taken off the subtotal of any invoices for this customer.
applies_toobjectoptional
createdintegerrequired
Time at which the object was created. Measured in seconds since the Unix epoch.
currencystringoptional
If `amount_off` has been set, the three-letter [ISO code for the currency](https://stripe.com/docs/currencies) of the amount to take off.
currency_optionsobjectoptional
Coupons defined in each available currency option. Each key must be a three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) and a [supported currency](https://stripe.com/docs/currencies).
durationstringrequired
One of `forever`, `once`, or `repeating`. Describes how long a customer who applies this coupon will get the discount.
Allowed:foreveroncerepeating
duration_in_monthsintegeroptional
If `duration` is `repeating`, the number of months the coupon applies. Null if coupon `duration` is `forever` or `once`.
idstringrequired
Unique identifier for the object.
livemodebooleanrequired
If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
max_redemptionsintegeroptional
Maximum number of times this coupon can be redeemed, in total, across all customers, before it is no longer valid.
metadataobjectoptional
Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
namestringoptional
Name of the coupon displayed to customers on for instance invoices or receipts.
objectstringrequired
String representing the object's type. Objects of the same type share the same value.
Allowed:coupon
percent_offnumberoptional
Percent that will be taken off the subtotal of any invoices for this customer for the duration of the coupon. For example, a coupon with percent_off of 50 will make a $ (or local equivalent)100 invoice $ (or local equivalent)50 instead.
redeem_byintegeroptional
Date after which the coupon can no longer be redeemed.
times_redeemedintegerrequired
Number of times this coupon has been applied to a customer.
validbooleanrequired
Taking account of the above properties, whether this coupon can still be applied to a customer.
defaultReturned when the API reports an error and includes an `error` object describing the failure.
errorobjectrequired

Error handling

coupon must be a string of no more than 5000 characters and identify an existing coupon. name must not exceed 40 characters, and each currency_options entry must provide amount_off; only amount-based coupons support currency options.