Skip to main content

Generating coupons (legacy)


This legacy method to generate coupons and coupon definitions is now deprecated with sunsetting planned for June 15, 2023. If you are using legacy coupons, we recommend that you migrate to the new coupons framework soon. See Creating coupons .

Use the NewStore coupons resource to manage coupon definitions and coupons.

Coupons are a way for customers to get a discount on an order. A customer receives a coupon code (an alphanumeric string) and uses this code to get a discount on the price of an order. Coupons can be delivered via a marketing campaign or via customer support. Merchants use coupons to drive sales or to appease customers during conflict resolution handled by customer support.

The NewStore coupons resource is not used to create discounts themselves. Use the NewStore discount rule for this purpose.

Generic usage flow

  1. Create a discount rule
  2. Create a coupon definition .
  3. Generate one or more coupons using the created definition .
  4. Send the generated coupons to customers or store associates.

  5. Customers or store associates add coupon codes to the shopping cart.

  6. Coupons are taken into account when calculating shopping cart totals.

    If coupons are not applicable for any reason, a meaningful error is returned.

  7. Coupons are calculated and redeemed upon checkout.

    If coupons are not applicable for any reason, a meaningful error is returned.

Discount rules

Discount rules store the following information:

  • discount amount (fixed or percentage)
  • scope (item, order, shipping)
  • shopping bag conditions a customer must meet to a get a particular discount
  • for item discounts, information about the items they are applicable to

A typical example of a discount rule is shipping is free when the shopping bag value reaches a certain value.

Creating discount rules

To create a discount rule, use the Discount Rules API's Create discount rule method.

Discount rules are required to create coupon definitions .

The required properties are:

labelThe identifier of the rule, must be unique.

The scope of the discount, possible values are:order, item or shipping:

  • order: the discount is distributed over products proportionally to their prices before discount.
  • item: the discount is applied to each eligible product.
  • shipping: the discount is applied to each eligible shipping option. If shipping_price_limit is set for the discount rule, shipping options with prices over its value are not eligible for shipping discounts. If shipping_price_limit is0, all shipping options are eligible for shipping discounts.
typeThe type of discount, either fixed orpercentage.
amountThe amount of the discount.
currencyThe currency of the discount. Matches the currency of the order.

Discount rules with scope shipping are only supported for the type percentage. The support for fixed amount shipping discounts will be added in the future versions of the API.

The priority field determines in which order multiple discounts must be applied.

The response contains the discount rule identifier that is required for coupon definitions.


POST https://{{retailer}}.{{stage}}

"description": "50 Euro",
"amount": 50,
"currency": "EUR",
"scope": "order",
"type": "fixed",
"priority": 10,
"label": "50Euro",
"minimum_order_amount": 100

Coupon definitions

A coupon definition serves as a source of coupon properties and a container for coupons.

After a coupon definition is created, you can create coupons out of it without providing any additional parameters.


It is not possible to create a coupon without creating a coupon definition.

Some parameters can be optionally specified for coupons whether they are part of the coupon definition or not.

In the future releases of the API it will be possible to extract the information about which coupons were created from the given coupon definition and edit all coupons at once by editing the corresponding definition.

Creating coupon definitions

To create coupon definitions, use the Create coupon definitions method.

The required properties are:

labelThe identifier of the definition, must be unique.
discount_rule_idThe identifier of the discount rule .
patternA regular expression in RE2 syntax used to generate random coupon codes. You can use patterns like COUPON_[a-zA-Z0-9]{5} to generate codes like COUPON_aV1Mn. You can use a fixed pattern like COUPON_XtyLz to get the code that matches the pattern itself. Coupon codes are unique so it is only possible to generate one coupon out of a fixed pattern.

The optional properties are:

channel_typesThe list of channel types where the coupon can be redeemed.

Validation rules allow for controlling the coupon usage. A validation rule is an array of rules, each of them described by a label and its value.

For more information about validation rules, refer to the Create coupon definition.

max_redemptionsThe maximum number of times the coupon can be redeemed, if not provided there is no limit. Canceled or failed orders are not taken into account.


POST https://{{retailer}}.{{stage}}

"pattern": "COUPON_[a-zA-Z0-9]{5}",
"channel_types": ["web", "store"],
"validation_rules": [
"label": "valid_from",
"values": {
"valid_from": "2017-09-01T15:35:00Z"
"label": "valid_to",
"values": {
"valid_to": "2017-10-01T15:35:00Z"
"label": "restricted_to_consumer_id",
"values": {
"consumer_id": "6d03a0f0-d040-4de3-bc31-4fc2971df050"
"label": "definition1",
"discount_rule_id": "21d978d0-9314-434c-b810-bb17a0863852",
"max_redemptions": 100


A coupon is the individual token that is handed to a customer and can be redeemed on an order to get a discount. The coupon is represented by and used via its coupon code, typically an alphanumeric string.

Coupons can be tied to a specific customer ID using the restricted_to_consumer_id validation rule, so that they can be used only by the person whom it was given to, for example, by a customer in a customer support appeasement case. If a coupon is not tied to a specific customer, the code can be passed on from one customer to another.

Creating coupons

Use POST /coupons to create coupons. A coupon is created based on a coupon definition.


POST https://{{retailer}}.{{stage}}

"template_label": "definition1",
"validation_rules": []

You can optionally specify validation rules in the same format they are specified for coupon definitions. Depending on the properties you add on the coupon, the coupon's validation rules might override the definition's validation rules. To learn more about the overriding policy, refer to override.

The response contains the coupon code and the coupon identifier.

You can communicate the coupon code to a customer or to a store associate.

Modifying a coupon

Currently, enabling and disabling coupons is the only supported modification.

To modify a coupon, use the coupon identifier.

For example, if the coupon identifier is 08833d1c-c39e-495f-b8f1-be6661848556, you can update the coupon the following way:

POST https://{{retailer}}.{{stage}}
"is_enabled": false

Overriding coupon definitions

When you create a coupon, you can specify validation rules just like in a coupon definition. As a result, it is possible to override certain validation rules set in coupon definitions.

This table shows which properties can be overridden.

PropertyTypeIs uniqueIs required in definitionInherited by couponsCan be overwritten by coupons
labelStringY (across all definitions)YNN
codeStringY (across all coupons)Only a property of couponsGenerated out of the patternN
is_enabledBooleanNN, true when not specifiedYY (upon modification)
valid_fromObjectNNYY (upon creation)
valid_toObjectNNYY (upon creation)
restricted_to_consumer_idObjectNNYN (can be assigned to the coupon if not set in the definition)

Deprecated functionality

This section contains the list of deprecated fields and methods. Do not use them.

  • The POST coupon_templates method.
  • The discount_rule_id field in POST coupons. Set this field in the coupon definition instead.
  • The amount and currency fields in POST coupons. Set these fields on the discount rule instead.
  • The min_total_before_discount rule in POST coupons. Use the minimum_order_amount field in the discount rule instead.

Related topics