Sample - Stripe API
POST/v1/promotion_codes

Create a promotion code

A promotion code points to an underlying promotion. You can optionally restrict the code to a specific customer, redemption limit, and expiration date.

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

10 body fields
activebooleanoptional
Whether the promotion code is currently active.
codestringoptional
The customer-facing code. Regardless of case, this code must be unique across all active promotion codes for a specific customer. Valid characters are lower case letters (a-z), upper case letters (A-Z), digits (0-9), and dashes (-). If left blank, we will generate one automatically.
customerstringoptional
The customer who can use this promotion code. If not set, all customers can use the promotion code.
customer_accountstringoptional
The account representing the customer who can use this promotion code. If not set, all customers can use the promotion code.
expandarray<string>optional
Specifies which fields in the response should be expanded.
expires_atintegeroptional
The timestamp at which this promotion code will expire. If the coupon has specified a `redeems_by`, then this value cannot be after the coupon's `redeems_by`.
max_redemptionsintegeroptional
A positive integer specifying the number of times the promotion code can be redeemed. If the coupon has specified a `max_redemptions`, then this value cannot be greater than the coupon's `max_redemptions`.
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`.
promotionobjectrequired
The promotion referenced by this promotion code.
restrictionsobjectoptional
Settings that restrict the redemption of the promotion code.

2 status codes
200Successful response.
activebooleanrequired
Whether the promotion code is currently active. A promotion code is only active if the coupon is also valid.
codestringrequired
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 (-).
createdintegerrequired
Time at which the object was created. Measured in seconds since the Unix epoch.
customerstringoptional
The customer who can use this promotion code.
customer_accountstringoptional
The account representing the customer who can use this promotion code.
expires_atintegeroptional
Date at which the promotion code can no longer be redeemed.
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 promotion code can be redeemed.
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.
objectstringrequired
String representing the object's type. Objects of the same type share the same value.
Allowed:promotion_code
promotionobjectrequired
restrictionsobjectrequired
times_redeemedintegerrequired
Number of times this promotion code has been used.
defaultError response.
errorobjectrequired

Error handling

Any other status is an error: Error response.