A coupon contains information about a percent-off or amount-off discount you might want to apply to a customer. Coupons may be applied to subscriptions, invoices, checkout sessions, quotes, and more. Coupons do not work with conventional one-off charges or payment intents.
Attributes
- idstring
Unique identifier for the object.
- amount_
offnullable integer Amount (in the
currency
specified) that will be taken off the subtotal of any invoices for this customer. - currencynullable enum
If
amount_
has been set, the three-letter ISO code for the currency of the amount to take off.off - durationenum
One of
forever
,once
, andrepeating
. Describes how long a customer who applies this coupon will get the discount.Possible enum valuesforever
Applies to all charges from a subscription with this coupon applied.
once
Applies to the first charge from a subscription with this coupon applied.
repeating
Applies to charges in the first
duration_
months from a subscription with this coupon applied.in_ months - duration_
in_ monthsnullable integer If
duration
isrepeating
, the number of months the coupon applies. Null if couponduration
isforever
oronce
. - metadatanullable object
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
- namenullable string
Name of the coupon displayed to customers on for instance invoices or receipts.
- percent_
offnullable float 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 $100 invoice $50 instead.
More attributes
- objectstring
- applies_
tonullable objectExpandable - createdtimestamp
- currency_
optionsnullable objectExpandable - livemodeboolean
- max_
redemptionsnullable integer - redeem_
bynullable timestamp - times_
redeemedinteger - validboolean
{ "id": "jMT0WJUD", "object": "coupon", "amount_off": null, "created": 1678037688, "currency": null, "duration": "repeating", "duration_in_months": 3, "livemode": false, "max_redemptions": null, "metadata": {}, "name": null, "percent_off": 25.5, "redeem_by": null, "times_redeemed": 0, "valid": true}
You can create coupons easily via the coupon management page of the Stripe dashboard. Coupon creation is also accessible via the API if you need to create coupons on the fly.
A coupon has either a percent_
or an amount_
and currency
. If you set an amount_
, that amount will be subtracted from any invoice’s subtotal. For example, an invoice with a subtotal of 100 JPY will have a final total of 0 JPY if a coupon with an amount_
of 200 is applied to it and an invoice with a subtotal of 300 JPY will have a final total of 100 JPY if a coupon with an amount_
of 200 is applied to it.
Parameters
- amount_
offinteger A positive integer representing the amount to subtract from an invoice total (required if
percent_
is not passed).off - currencyenum
Three-letter ISO code for the currency of the
amount_
parameter (required ifoff amount_
is passed).off - durationenum
Specifies how long the discount will be in effect if used on a subscription. Defaults to
once
.Possible enum valuesforever
Applies to all charges from a subscription with this coupon applied.
once
Applies to the first charge from a subscription with this coupon applied.
repeating
Applies to charges in the first
duration_
months from a subscription with this coupon applied.in_ months - duration_
in_ monthsinteger Required only if
duration
isrepeating
, in which case it must be a positive integer that specifies the number of months the discount will be in effect. - metadataobject
Set of key-value pairs 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
. - namestring
Name of the coupon displayed to customers on, for instance invoices, or receipts. By default the
id
is shown ifname
is not set. - percent_
offfloat A positive float larger than 0, and smaller or equal to 100, that represents the discount the coupon will apply (required if
amount_
is not passed).off
More parameters
- applies_
toobject - currency_
optionsobject - idstring
- max_
redemptionsinteger - redeem_
bytimestamp
Returns
Returns the coupon object.
{ "id": "jMT0WJUD", "object": "coupon", "amount_off": null, "created": 1678037688, "currency": null, "duration": "repeating", "duration_in_months": 3, "livemode": false, "max_redemptions": null, "metadata": {}, "name": null, "percent_off": 25.5, "redeem_by": null, "times_redeemed": 0, "valid": true}
Updates the metadata of a coupon. Other coupon details (currency, duration, amount_off) are, by design, not editable.
Parameters
- metadataobject
Set of key-value pairs 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
. - namestring
Name of the coupon displayed to customers on, for instance invoices, or receipts. By default the
id
is shown ifname
is not set.
More parameters
- currency_
optionsobject
Returns
The newly updated coupon object if the call succeeded. Otherwise, this call raises an error, such as if the coupon has been deleted.
{ "id": "jMT0WJUD", "object": "coupon", "amount_off": null, "created": 1678037688, "currency": null, "duration": "repeating", "duration_in_months": 3, "livemode": false, "max_redemptions": null, "metadata": { "order_id": "6735" }, "name": null, "percent_off": 25.5, "redeem_by": null, "times_redeemed": 0, "valid": true}
Retrieves the coupon with the given ID.
Parameters
No parameters.
Returns
Returns a coupon if a valid coupon ID was provided. Raises an error otherwise.
{ "id": "jMT0WJUD", "object": "coupon", "amount_off": null, "created": 1678037688, "currency": null, "duration": "repeating", "duration_in_months": 3, "livemode": false, "max_redemptions": null, "metadata": {}, "name": null, "percent_off": 25.5, "redeem_by": null, "times_redeemed": 0, "valid": true}