Promotion codes
The codes customers type to redeem a coupon, each with its own limits.
A promotion code redeems a coupon. It can be restricted to one customer, limited in redemptions and given an expiry, all within the coupon's own limits. Codes are upper-cased and unique among your codes. Redeem one on a subscription with promotion_code, on a checkout session that starts a subscription, or price it first with a quote.
The promotion code object
idstring
Prefixed
promo_.objectstring
promotion_codecodestring
What the customer types.
couponstring
customerstring | null
The only customer who may use it, when restricted.
max_redemptionsinteger | null
expires_attimestamp | null
times_redeemedinteger
activeboolean
metadataobject
created_attimestamp
updated_attimestamp
Create a promotion code
POST/v1/promotion_codesSecret key
Body
couponstringrequired
An active coupon.
codestring
3 to 40 letters, digits and dashes. Generated when omitted.
customerstring
Restrict the code to this customer.
max_redemptionsinteger
expires_attimestamp
metadataobject
Errors: resource_not_found for the coupon or customer, resource_in_wrong_state for a retired coupon, resource_already_exists for a code in use.
Retrieve a promotion code
GET/v1/promotion_codes/:idSecret key
Update a promotion code
POST/v1/promotion_codes/:idSecret key
Body
activeboolean
false retires the code; true brings it back while its coupon is active.customerstring | null
Restrict to one customer, or
null to lift the restriction.metadataobject
Errors: resource_not_found for the code or customer, resource_in_wrong_state for bringing back a code whose coupon is retired.
List promotion codes
GET/v1/promotion_codesSecret key
Query parameters
couponstring
codestring
An exact code.
limitintegerdefault: 25
starting_afterstring