A Promotion Code represents a customer-redeemable code for a coupon. You can create multiple codes for a single coupon.
If you enable promotion codes in your customer portal configuration, 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.
Attributes
- idstring
Unique identifier for the object.
- codestring
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), and digits (0-9).
- couponobject
Hash describing the coupon for this promotion code.
- metadatanullable object
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.
More attributes
- objectstring
- activeboolean
- createdtimestamp
- customernullable stringExpandable
- expires_
atnullable timestamp - livemodeboolean
- max_
redemptionsnullable integer - restrictionsobject
- times_
redeemedinteger
{ "id": "promo_1MiM6KLkdIwHu7ixrIaX4wgn", "object": "promotion_code", "active": true, "code": "A1H1Q1MG", "coupon": { "id": "nVJYDOag", "object": "coupon", "amount_off": null, "created": 1678040164, "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 }, "created": 1678040164, "customer": null, "expires_at": null, "livemode": false, "max_redemptions": null, "metadata": {}, "restrictions": { "first_time_transaction": false, "minimum_amount": null, "minimum_amount_currency": null }, "times_redeemed": 0}A promotion code points to a coupon. You can optionally restrict the code to a specific customer, redemption limit, and expiration date.
Parameters
- couponstringRequired
The coupon for this promotion code.
- codestring
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), and digits (0-9).
If left blank, we will generate one automatically.
- metadataobject
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.
More parameters
- activeboolean
- customerstring
- expires_
attimestamp - max_
redemptionsinteger - restrictionsobject
Returns
Returns the promotion code object.
{ "id": "promo_1MiM6KLkdIwHu7ixrIaX4wgn", "object": "promotion_code", "active": true, "code": "A1H1Q1MG", "coupon": { "id": "nVJYDOag", "object": "coupon", "amount_off": null, "created": 1678040164, "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 }, "created": 1678040164, "customer": null, "expires_at": null, "livemode": false, "max_redemptions": null, "metadata": {}, "restrictions": { "first_time_transaction": false, "minimum_amount": null, "minimum_amount_currency": null }, "times_redeemed": 0}Updates the specified promotion code by setting the values of the parameters passed. Most fields are, by design, not editable.
Parameters
- metadataobject
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.
More parameters
- activeboolean
- restrictionsobject
Returns
The updated promotion code object is returned upon success. Otherwise, this call raises an error.
{ "id": "promo_1MiM6KLkdIwHu7ixrIaX4wgn", "object": "promotion_code", "active": true, "code": "A1H1Q1MG", "coupon": { "id": "nVJYDOag", "object": "coupon", "amount_off": null, "created": 1678040164, "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 }, "created": 1678040164, "customer": null, "expires_at": null, "livemode": false, "max_redemptions": null, "metadata": { "order_id": "6735" }, "restrictions": { "first_time_transaction": false, "minimum_amount": null, "minimum_amount_currency": null }, "times_redeemed": 0}{ "id": "promo_1MiM6KLkdIwHu7ixrIaX4wgn", "object": "promotion_code", "active": true, "code": "A1H1Q1MG", "coupon": { "id": "nVJYDOag", "object": "coupon", "amount_off": null, "created": 1678040164, "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 }, "created": 1678040164, "customer": null, "expires_at": null, "livemode": false, "max_redemptions": null, "metadata": {}, "restrictions": { "first_time_transaction": false, "minimum_amount": null, "minimum_amount_currency": null }, "times_redeemed": 0}