Generating coupons (legacy)

Important

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

Create a discount rule
Create a coupon definition .
Generate one or more coupons using the created definition .
Send the generated coupons to customers or store associates.
Customers or store associates add coupon codes to the shopping cart.
Coupons are taken into account when calculating shopping cart totals.
If coupons are not applicable for any reason, a meaningful error is returned.
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:

Property	Description
`label`	The identifier of the rule, must be unique.
`scope`	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` is`0`, all shipping options are eligible for shipping discounts.
`type`	The type of discount, either `fixed` or`percentage`.
`amount`	The amount of the discount.
`currency`	The currency of the discount. Matches the currency of the order.

note

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.

Example

POST https://{{retailer}}.{{stage}}.newstore.net/v0/d/discount_rules

{
    "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.

Important

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:

Property	Description
`label`	The identifier of the definition, must be unique.
`discount_rule_id`	The identifier of the discount rule .
`pattern`	A 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:

Property Description

channel_types The list of channel types where the coupon can be redeemed.

Property	Description
`channel_types`	The list of channel types where the coupon can be redeemed.
`validation_rules`	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_redemptions`	The 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.

validation_rules

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_redemptions The 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.

Example

POST https://{{retailer}}.{{stage}}.newstore.net/v0/d/coupon_definitions

{
    "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
}

Coupons

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.

Example

POST https://{{retailer}}.{{stage}}.newstore.net/v0/d/coupons

{
    "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}}.newstore.net/v0/d/coupons/08833d1c-c39e-495f-b8f1-be6661848556
{
    "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.

Property	Type	Is unique	Is required in definition	Inherited by coupons	Can be overwritten by coupons
`label`	String	Y (across all definitions)	Y	N	N
`pattern`	String	N	Y	N	N
`code`	String	Y (across all coupons)	Only a property of coupons	Generated out of the pattern	N
`discount_rule_id`	String	N	Y	Y	N
`is_enabled`	Boolean	N	N, `true` when not specified	Y	Y (upon modification)
`valid_from`	Object	N	N	Y	Y (upon creation)
`valid_to`	Object	N	N	Y	Y (upon creation)
`restricted_to_consumer_id`	Object	N	N	Y	N (can be assigned to the coupon if not set in the definition)
`channel_types`	Array	N	N	Y	N

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

Getting started with NewStore APIs

Generating coupons (legacy)

Generic usage flow​

Discount rules​

Creating discount rules​

Coupon definitions​

Creating coupon definitions​

Coupons​

Creating coupons​

Modifying a coupon​

Overriding coupon definitions​

Deprecated functionality​

Generic usage flow

Discount rules

Creating discount rules

Coupon definitions

Creating coupon definitions

Coupons

Creating coupons

Modifying a coupon

Overriding coupon definitions

Deprecated functionality