Coupons

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.

Was this section helpful? Yes No

Create a coupon

POST / v1 / coupons

Update a coupon

POST / v1 / coupons /:id

Retrieve a coupon

GET / v1 / coupons /:id

List all coupons

GET / v1 / coupons

Delete a coupon

DELETE / v1 / coupons /:id

The Coupon object

Attributes

• id string Unique identifier for the object.
• amount _ off nullable integer Amount (in the currency specified) that will be taken off the subtotal of any invoices for this customer.
• currency nullable enum If amount_off has been set, the three-letter ISO code for the currency of the amount to take off.
• duration enum One of forever, once, or repeating. Describes how long a customer who applies this coupon will get the discount. Possible enum values forever 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_in_months months from a subscription with this coupon applied.
• metadata nullable map 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.
• name nullable string Name of the coupon displayed to customers on for instance invoices or receipts.
• percent _ off nullable number 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

• object string, value is "coupon"
• applies _ to nullable object Includable
• created timestamp
• currency _ options nullable map Includable
• duration _ in _ months nullable integer
• livemode boolean
• max _ redemptions nullable integer
• redeem _ by nullable timestamp
• times _ redeemed integer
• valid boolean

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}

Create a coupon

POST / v1 / coupons

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_off or an amount_off and currency. If you set an amount_off, that amount will be subtracted from any invoice’s subtotal. For example, an invoice with a subtotal of 100 USD will have a final total of 0 USD if a coupon with an amount_off of 20000 is applied to it and an invoice with a subtotal of 300 USD will have a final total of 100 USD if a coupon with an amount_off of 20000 is applied to it.

Parameters

• amount _ off integer A positive integer representing the amount to subtract from an invoice total (required if percent_off is not passed).
• currency enum Three-letter ISO code for the currency of the amount_off parameter (required if amount_off is passed).
• duration enum Specifies how long the discount will be in effect if used on a subscription. Defaults to once. Possible enum values forever 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_in_months months from a subscription with this coupon applied.
• metadata map 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.
• name string Name of the coupon displayed to customers on, for instance invoices, or receipts. By default the id is shown if name is not set. The maximum length is 40 characters.
• percent _ off number A positive float larger than 0, and smaller or equal to 100, that represents the discount the coupon will apply (required if amount_off is not passed).

More parameters

• applies _ to object
• currency _ options map
• duration _ in _ months integer
• id string
• max _ redemptions integer
• redeem _ by timestamp

Returns

Returns the coupon object.

Response

{ "id": "jMT0WJUD", "object": "coupon", "amount_off": null, "created": 1678037688, "currency": null, "duration": "forever", "livemode": false, "max_redemptions": null, "metadata": {}, "name": null, "percent_off": 25.5, "redeem_by": null, "times_redeemed": 0, "valid": true}