Zonal Product Discounts

Overview

Zonal discounts allow you to set a discount percentage individually for each checkout currency. You can also remove a discount for a currency by setting the discount percentage to zero.

Zonal discounts are supported by promotions having type Discounts ("promotion_type": "discount") with individual product discounts, i.e. array discounts.products containing a list of products and discounts for these products is transferred).

Individual Zonal Product Discount

How it works:

The request you transfer must include an array of products with individual discounts specified for each product: discounts.products.
This array must also include:
- Total discount value for product discounts.products.discount_percent – used if no zonal discount is found for checkout currency.
- Array of zonal discounts discounts.products.discount_percent_currencies – contain discount values based on checkout currency.
When adding a product to the checkout page, the corresponding zonal discount is applied to the product, if:
- there is an individual discount for this product (product ID is transferred in array discounts.products within parameter product_id),
- and the currency selected at checkout matches one of the currencies listed in array discount_percent_currencies.
  Otherwise, if no zonal discount is available for the product, the discount specified in parameter discount_percent is applied instead (this parameter should have already been present in the request and contained the individual discount for the product).

Please note, the request must meet the following conditions:

The promotion type must be discount ("promotion_type": "discount").
The request must not contain parameters that define the total discount discounts.discount_percent, discounts.product_id.

Example Request: Creating a Promotion with Zonal Discounts

CODE

{
 "promotion_type": "discount",
 "promotion_name": "Black Friday",
 "status": true,
 "date_from": "2023-01-01T00:00:00+03:00",
 "date_to": "2023-01-10T00:00:00+03:00",
 "discounts": {
 "products": [{
    "product_id": 11111,
    "discount_percent": "20",
    "discount_percent_currencies": [
         {
            "currency": "USD",
            "discount_percent": "5" 
         },
         {
            "currency": "EUR",
            "discount_percent": "0" 
         }
    ]
   }, {
    "product_id": 22222,
    "discount_percent": "30"
   }
  ]
 }
}

Explaining the example:

Product at checkout	Checkout currency	Discount applied
11111	USD	5% — individual zonal discount for USD.
11111	EUR	No discount because array of zonal product discounts and currency EUR contains discount value "0".
11111	AUD	20% total product discount because no AUD in array of zonal discounts.
22222	USD or EUR or AUD	30% total product discount because no array of zonal discounts is transferred.

Disable Discount for Specific Currency

With zonal discounts you can prohibit a discount for a particular checkout currency.

The logic works as follows:

If the array of zonal discounts (discounts.products.discount_percent_currencies) contains a discount with value > 0 for the current checkout currency selected at checkout, this discount will be applied to the product.
If the array of zonal discounts (discounts.products.discount_percent_currencies) contains a discount with value = 0 for the current checkout currency selected at checkout, the price of the product on the checkout page will be full, i.e. no discount.
If the array of zonal discounts (discounts.products.discount_percent_currencies) contains no discount for the current checkout currency selected at checkout, or the array of zonal discounts is not transferred, the discount specified in parameter discounts.products.discount_percent will be applied to the product.

See the example request above. For product 1111, if the selected currency at checkout is EUR, no discount will be applied.

Add Zonal Discount Values to Existing Promotion

Let us assume you have already created a promotion with individual product discounts:

Product 111111 is assigned discount 55.444444% for any checkout currency.

CODE

{
  "promotion_type": "discount",
  "discounts": {
    "products": [
      {
        "product_id": 111111,
        "discount_percent": "55.444444"
      }
    ]
  }
}

Now, you want the discount amount to depend on the checkout currency.

Send request [PATCH] Modify promotion to modify the promotion and transfer:

Array discounts.products – must include all the products eligible for the discount.
Array of zonal discounts discounts.products.discount_percent_currencies – for each of the products.

Example:

CODE

{
  "promotion_type": "discount",
  "discounts": {
    "products": [
      {
        "product_id": 111111,
        "discount_percent": "55.444444",
        "discount_percent_currencies": [
          {
            "currency": "USD",
            "discount_percent": "9.99"
          },
          {
            "currency": "EUR",
            "discount_percent": "20"
          },
          {
            "currency": "AUD",
            "discount_percent": "0"
          }
        ]
      }
    ]
  }
}

After the system has completed the request the following will apply for product 111111:

For all checkout currencies except USD, EUR, AUD: discount = 55.444444%.
For USD: discount = 9.99%.
For EUR: discount = 20%.
For AUD: no discount – not even 55.444444% (however, a discount may still be applied via a promotion code if another promotion is configured accordingly).

Replace Total Product Discount with Individual Zonal Discounts

Let us assume you have created a promotion with a 10% total discount for all your products:

CODE

{
  "promotion_type": "discount",
  "promotion_name": "Black Friday",
  "status": true,
  "date_from": "2023-01-01T00:00:00+03:00",
  "date_to": "2023-01-10T00:00:00+03:00",
  "discounts": {
    "discount_percent": "10"
  }
}

Now, you want the discount to apply only to specific products, and the amount to vary based on the checkout currency.

Send request [PATCH] Modify promotion to modify the promotion and transfer:

Array discounts.products – must include all the products eligible for the discount.
Array of zonal discounts discounts.products.discount_percent_currencies – for each of the products.

Example:

CODE

{
  "promotion_type": "discount",
  "discounts": {
    "products": [
      {
        "product_id": 222222,
        "discount_percent": "55.444444",
        "discount_percent_currencies": [
        {
            "currency": "USD",
            "discount_percent": "9.99"
          },
          {
            "currency": "EUR",
            "discount_percent": "20"
          },
          {
            "currency": "AUD",
            "discount_percent": "0"
          }
        ]
      }
    ]
  }
}

Explaining the example:

Total product discount 10% no longer applies.
Only product 222222 uses the discount:
- For all checkout currencies except USD, EUR, AUD: discount = 55.444444%.
- For USD: discount = 9.99%.
- For EUR: discount = 20%.
- For AUD: no discount - not even 55.444444% (however, a discount may still be applied via a promotion code if another promotion is configured accordingly).