Ctrlk
CommunitySupport PortalYouTubeFree trialSign Up!

Coupon Tutorial

How to create a new coupon

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

To test the endpoint, open the API reference or check the examples of the curl requests below that refer to different confgis.

API Reference

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

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

curl -i -X POST 
  'https://api.emporix.io/coupon/{tenant}/coupons' 
  -H 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}' 
  -H 'Content-Type: application/json' 
  -d '{
  "code": "ENG2OC0",
  "name": "Winter Sale 2022",
  "description": "Free shipping coupon",
  "discountType": "FREE_SHIPPING",
  "discountAbsolute": {
    "amount": 24.99,
    "currency": "USD"
  },
  "allowAnonymous": false,
  "maxRedemptions": -1,
  "maxRedemptionsPerCustomer": 1,
  "categoryRestricted": false,
  "segmentRestricted": false,
  "restrictions": {
    "validFor": [],
    "validFrom": "2022-02-16T09:04:35.446Z",
    "validUntil": "2022-03-31T10:04:35.446Z",
    "minOrderValue": {
      "amount": 50,
      "currency": "EUR"
    }
  },
  "issuedTo": ""
}'

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.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

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.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

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.

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

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

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

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

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: coupon.coupon_redeem_on_behalf.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

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.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

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.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

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.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

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.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

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.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

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:

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

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

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.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference

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.

To test the endpoint, open the API reference or check the example of a curl request.

API Reference
PreviousCoupon ServiceNextAPI Reference

Last updated

Was this helpful?