The Promotion Code object

Attributes

id string Unique identifier for the object.
code string 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 (-).
metadata nullable map 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.
promotion object The promotion referenced by this promotion code.

More attributes

object string, value is "promotion_code"
active boolean
created timestamp
customer nullable string Expandable
customer _ account nullable string
expires _ at nullable timestamp
livemode boolean
max _ redemptions nullable integer
restrictions object
times _ redeemed integer

{ "id": "promo_1MiM6KLkdIwHu7ixrIaX4wgn", "object": "promotion_code", "active": true, "code": "A1H1Q1MG", "promotion": { "type": "coupon", "coupon": "nVJYDOag" }, "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

POST / v1 / promotion_codes

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

Parameters

promotion object Required The promotion referenced by this promotion code.
code string 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. The maximum length is 500 characters.
metadata map 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

active boolean
customer string
customer _ account string
expires _ at timestamp
max _ redemptions integer
restrictions object

Returns

Returns the promotion code object.

Response

{ "id": "promo_1MiM6KLkdIwHu7ixrIaX4wgn", "object": "promotion_code", "active": true, "code": "A1H1Q1MG", "promotion": { "type": "coupon", "coupon": "nVJYDOag" }, "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

POST / v1 / promotion_codes /:id

Updates the specified promotion code by setting the values of the parameters passed. Most fields are, by design, not editable.

Parameters

metadata map 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

active boolean
restrictions object

Returns

The updated promotion code object is returned upon success. Otherwise, this call raises an error.

Response

{ "id": "promo_1MiM6KLkdIwHu7ixrIaX4wgn", "object": "promotion_code", "active": true, "code": "A1H1Q1MG", "promotion": { "type": "coupon", "coupon": "nVJYDOag" }, "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}