Stripe: Coupons schemas
4 Stripe schemas with complete fields and constraints.
← Coupons operations · All schemas
Create a coupon — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | 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](https://docs.stripe.com/api#subscriptions), [invoices](https://docs.stripe.com/api#invoices), [checkout sessions](https://docs.stripe.com/api/checkout/sessions), [quotes](https://docs.stripe.com/api#quotes), and more. Coupons do not work with conventional one-off [charges](/api/charges/create) or [payment intents](https://docs.stripe.com/api/payment_intents). |
amount_off | JSON | Optional | |
amount_off (anyOf 1) | JSON | Alternative | |
amount_off (anyOf 1) (anyOf 1) | integer | Alternative | Amount (in the `currency` specified) that will be taken off the subtotal of any invoices for this customer. |
amount_off (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
amount_off (anyOf 2) | null | Alternative | |
applies_to | Model | Optional | Expand Create a coupon — response body — applies to |
created | JSON | Required within parent | |
created (anyOf 1) | integer | Alternative | Time at which the object was created. Measured in seconds since the Unix epoch. Format: unix-time |
created (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
currency | JSON | Optional | |
currency (anyOf 1) | string | Alternative | 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. Format: currency |
currency (anyOf 2) | null | Alternative | |
currency_options | object | Optional | 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). Additional keys: see wildcard field |
currency_options.* | Model | Additional keys | Expand Create a coupon — response body — currency options value |
duration | string | Required within parent | One of `forever`, `once`, or `repeating`. Describes how long a customer who applies this coupon will get the discount. Known values: forever, once, repeating |
duration_in_months | JSON | Optional | |
duration_in_months (anyOf 1) | JSON | Alternative | |
duration_in_months (anyOf 1) (anyOf 1) | integer | Alternative | If `duration` is `repeating`, the number of months the coupon applies. Null if coupon `duration` is `forever` or `once`. |
duration_in_months (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
duration_in_months (anyOf 2) | null | Alternative | |
id | string | Required within parent | Unique identifier for the object. Maximum length: 5000 |
livemode | boolean | Required within parent | If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`. |
max_redemptions | JSON | Optional | |
max_redemptions (anyOf 1) | JSON | Alternative | |
max_redemptions (anyOf 1) (anyOf 1) | integer | Alternative | Maximum number of times this coupon can be redeemed, in total, across all customers, before it is no longer valid. |
max_redemptions (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
max_redemptions (anyOf 2) | null | Alternative | |
metadata | JSON | Optional | |
metadata (anyOf 1) | object | Alternative | 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. Additional keys: see wildcard field |
metadata (anyOf 1).* | string | Additional keys | Maximum length: 500 |
metadata (anyOf 2) | null | Alternative | |
name | JSON | Optional | |
name (anyOf 1) | string | Alternative | Name of the coupon displayed to customers on for instance invoices or receipts. Maximum length: 5000 |
name (anyOf 2) | null | Alternative | |
object | string | Required within parent | String representing the object's type. Objects of the same type share the same value. Known values: coupon |
percent_off | JSON | Optional | |
percent_off (anyOf 1) | JSON | Alternative | |
percent_off (anyOf 1) (anyOf 1) | number | Alternative | 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. |
percent_off (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
percent_off (anyOf 2) | null | Alternative | |
redeem_by | JSON | Optional | |
redeem_by (anyOf 1) | JSON | Alternative | |
redeem_by (anyOf 1) (anyOf 1) | integer | Alternative | Date after which the coupon can no longer be redeemed. Format: unix-time |
redeem_by (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
redeem_by (anyOf 2) | null | Alternative | |
times_redeemed | JSON | Required within parent | |
times_redeemed (anyOf 1) | integer | Alternative | Number of times this coupon has been applied to a customer. |
times_redeemed (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
valid | boolean | Required within parent | Taking account of the above properties, whether this coupon can still be applied to a customer. |
Referenced models: Create a coupon — response body — applies to, Create a coupon — response body — currency options value
Create a coupon — response body — applies to
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
products | array | Required within parent | A list of product IDs this coupon applies to |
products[] | string | Each item | Maximum length: 5000 |
Create a coupon — response body — currency options value
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
amount_off | JSON | Required within parent | |
amount_off (anyOf 1) | integer | Alternative | Amount (in the `currency` specified) that will be taken off the subtotal of any invoices for this customer. |
amount_off (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
Delete a coupon — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
deleted | boolean | Required within parent | Always true for a deleted object Known values: True |
id | string | Required within parent | Unique identifier for the object. Maximum length: 5000 |
object | string | Required within parent | String representing the object's type. Objects of the same type share the same value. Known values: coupon |