Promotion Code
A Promotion Code represents a customer-redeemable code for a coupon. It can be used to create multiple codes for a single coupon.
The Promotion Code object
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.
- 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
}
Create a promotion code
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. 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
}
Update a promotion code
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
}
Retrieve a promotion code
{
"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
}