Coupon Service Tutorials

How to create a new coupon

To create a new coupon, you need to send a request to the Creating a new coupon endpoint.

Creating a free shipping coupon with minimum order value and 1 usage per customer

attention

When creating a free shipping coupon, ensure that the categoryRestricted parameter is set to false.

Creating a coupon with a fixed discount amount for a specific customer

To limit a coupon to a specific customer, you need to provide the customer ID in the restrictions.validFor array and issuedTo field.

Creating a category coupon with percentage discount

To limit a coupon to a specific category, you need to set the categoryRestricted parameter to true and provide the category ID in the restrictions.includedCategories array.

How to update an existing coupon

To update an existing coupon, you need to send a request to the Partially updating a coupon endpoint.

info

For more information on managing carts, check out the Carts guide.

How to apply coupons to a cart

You can apply one or more coupons to a cart. Coupons of different types can be applied all at once.

Specify the number of coupons per cart

If you want to specify how many coupons can be added to a cart, first you need to send a request to the Updating a configuration endpoint in the Configuration Service.

In the following example, we are changing the maximum number of coupons that can be applied to a single cart to 3.

Apply a coupon to a cart

To apply a coupon to a cart, you need to send a request to the Applying a discount to cart endpoint.

info

If you want to apply more than one coupon to a cart, you need to send a separate request for each discount coupon.

attention

Applying the coupon to cart does not mean that the coupon is automatically redeemed. For more information, check out How to redeem a coupon.

How to redeem a coupon

A coupon can be redeemed in the following ways:

When a coupon is added to a cart and the order is completed at checkout, the coupon is automatically redeemed by the Checkout Service.
When you send a request to the Redeeming the coupon by creating a redemption endpoint. This process is independent of the checkout, so a coupon can be used even after an order is created and processed at checkout. This can be done by a merchant on behalf of a customer.

In the following example, we are redeeming a coupon on behalf of a customer.

Redeem a coupon on behalf of a customer by sending a request to the Redeeming the coupon by creating a redemption endpoint. The following scope is required:

Copy

Copied

coupon.coupon_redeem_on_behalf

info

The redeemed coupon cannot be used used again during checkout.

How to enable referral coupons

Configure your main site's referral coupon settings

Referral coupon settings are stored in your main site's couponSettings mixin.First, check if your couponSettings mixin has already been configured by sending a request to the Retrieving a site mixin endpoint.

If your site's couponSettings have never been configured before or have been deleted, you will receive a 404 error in the response body.In this case, to configure referral coupons, you need to send a request to the Creating a site mixin endpoint.

If your site's couponSettings have already been configured, you will receive them in the response body.In this case, to configure referral coupons, you need to send a request to the Partially updating a site mixin endpoint.

Configure referral email templates

Referral email templates are referenced in the emailTemplates configuration in the Configuration Service.First, check if your emailTemplates have already been configured by sending a request to the Retrieving a configuration endpoint.

If your emailTemplates have never been configured before or have been deleted, you will receive a 404 error in the response body.In this case, to configure referral email templates, you need to send a request to the Creating configurations endpoint.

If your emailTemplates have already been configured, you will receive them in the response body.In this case, you need to copy the response body and add the following objects to the value array:

Copy

Copied

{
    "name": "referralCouponMailTemplate",
    "languages": {
        "de": 604558,
        "en": 604608,
        "pt": 1694106,
        "nb": 855168
    }
},
{
    "name": "referralCouponRedemptionMailTemplate",
    "languages": {
        "de": 605150,
        "en": 605211,
        "pt": 1694130,
        "nb": 858154
    }
}

To add referral email templates to an existing emailTemplates configuration, you need to send a request to the Updating a configuration endpoint.

How to generate a referral coupon for a specific customer

To manually generate a referral coupon for a specific customer, you need to send a request to the Creating a referral coupon code for a specific customer endpoint.

How to retrieve a specific customer's referral coupon

To retrieve referral coupon information for a specific customer, you need to send a request to the Retrieving customer's referral coupon code endpoint.