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}
Retrieve a promotion code
GET / v1 / promotion_codes /:id
Retrieves the promotion code with the given ID. In order to retrieve a promotion code by the customer-facing code use list with the desired code.
Parameters
No parameters.
Returns
Returns a promotion code if a valid promotion code ID was provided. Raises an error otherwise.
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}