Stripe: Promotion codes schemas
4 Stripe schemas with complete fields and constraints.
← Promotion codes operations · All schemas
Create a promotion code — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A Promotion Code represents a customer-redeemable code for an underlying promotion. You can create multiple codes for a single promotion. If you enable promotion codes in your [customer portal configuration](https://docs.stripe.com/customer-management/configure-portal), then customers can redeem a code themselves when updating a subscription in the portal. Customers can also view the currently active promotion codes and coupons on each of their subscriptions in the portal. |
active | boolean | Required within parent | Whether the promotion code is currently active. A promotion code is only active if the coupon is also valid. |
code | string | Required within parent | The customer-facing code. Regardless of case, this code must be unique across all active promotion codes for each customer. Valid characters are lower case letters (a-z), upper case letters (A-Z), digits (0-9), and dashes (-). Maximum length: 5000 |
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]+)?$ |
customer | JSON | Optional | |
customer (anyOf 1) | JSON | Alternative | The customer who can use this promotion code. |
customer (anyOf 1) (anyOf 1) | string | Alternative | Maximum length: 5000 |
customer (anyOf 1) (anyOf 2) | Model | Alternative | Expand Create a customer — response body |
customer (anyOf 1) (anyOf 3) | Model | Alternative | Expand Delete a customer — response body |
customer (anyOf 2) | null | Alternative | |
customer_account | JSON | Optional | |
customer_account (anyOf 1) | string | Alternative | The account representing the customer who can use this promotion code. Maximum length: 5000 |
customer_account (anyOf 2) | null | Alternative | |
expires_at | JSON | Optional | |
expires_at (anyOf 1) | JSON | Alternative | |
expires_at (anyOf 1) (anyOf 1) | integer | Alternative | Date at which the promotion code can no longer be redeemed. Format: unix-time |
expires_at (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
expires_at (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 promotion code can be redeemed. |
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 | |
object | string | Required within parent | String representing the object's type. Objects of the same type share the same value. Known values: promotion_code |
promotion | Model | Required within parent | Expand Create a promotion code — response body — promotion |
restrictions | Model | Required within parent | Expand Create a promotion code — response body — restrictions |
times_redeemed | JSON | Required within parent | |
times_redeemed (anyOf 1) | integer | Alternative | Number of times this promotion code has been used. |
times_redeemed (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
Referenced models: Create a customer — response body, Delete a customer — response body, Create a promotion code — response body — promotion, Create a promotion code — response body — restrictions
Create a promotion code — response body — promotion
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
coupon | JSON | Optional | |
coupon (anyOf 1) | JSON | Alternative | If promotion `type` is `coupon`, the coupon for this promotion. |
coupon (anyOf 1) (anyOf 1) | string | Alternative | Maximum length: 5000 |
coupon (anyOf 1) (anyOf 2) | Model | Alternative | Expand Create a coupon — response body |
coupon (anyOf 2) | null | Alternative | |
type | string | Required within parent | The type of promotion. Known values: coupon |
Referenced models: Create a coupon — response body
Create a promotion code — response body — restrictions
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
currency_options | object | Optional | Promotion code restrictions 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 promotion code — response body — restrictions currency options value |
first_time_transaction | boolean | Required within parent | A Boolean indicating if the Promotion Code should only be redeemed for Customers without any successful payments or invoices |
minimum_amount | JSON | Optional | |
minimum_amount (anyOf 1) | JSON | Alternative | |
minimum_amount (anyOf 1) (anyOf 1) | integer | Alternative | Minimum amount required to redeem this Promotion Code into a Coupon (e.g., a purchase must be $100 or more to work). |
minimum_amount (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
minimum_amount (anyOf 2) | null | Alternative | |
minimum_amount_currency | JSON | Optional | |
minimum_amount_currency (anyOf 1) | string | Alternative | Three-letter [ISO code](https://stripe.com/docs/currencies) for minimum_amount Maximum length: 5000 |
minimum_amount_currency (anyOf 2) | null | Alternative |
Referenced models: Create a promotion code — response body — restrictions currency options value
Create a promotion code — response body — restrictions currency options value
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
minimum_amount | JSON | Required within parent | |
minimum_amount (anyOf 1) | integer | Alternative | Minimum amount required to redeem this Promotion Code into a Coupon (e.g., a purchase must be $100 or more to work). |
minimum_amount (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |