Implementing promotions

This article provides information regarding implementing the Promotions feature:

  • Promotion statuses to show you the possible promotion statuses and explain the circumstances in which a promotion is assigned with a specific status.
  • Implementation variants to show you the possibilities of implementing the promotion calculation logic, features, requirements, and implementation guide for each implementation variant
  • Displaying promotion to show you the methods of displaying and distributing promotions in the channels of your choice

Promotion scopes

When creating a promotion, you can select the group of customers (audience) who are eligible.

The promotion’s scope can be:

  • for selected items - You can create a promotion for selected items or group of selected items.
  • for entire basket - You can create a promotion applied to total value of transaction.

Promotion statuses


When you create and publish a promotion, it can get the following statuses in a Synerise database:

Promotion statuses in Synerise database
Promotion statuses in Synerise database

Assigned

A promotion with this status can be displayed in the distribution channels of your choice.

When a promotion receives this status in the database, it means that one of the scenarios occurred:

  • the system found the recipients for the promotion who meet the requirements defined in the Audience section of a promotion right after publishing the promotion. This occurs automatically and in real time as a customer meets the conditions of the promotion. Such a promotion is ready to be activated.
  • an active promotion has been deactivated and it returned to the assigned status. If the promotion involved redeeming loyalty points, deactivation gives back the number of spent loyalty points to the customer. The following methods deactivate a promotion:
    Method API consumer Description Events generated
    Deactivate a promotion
    /v4/promotions/promotion/deactivate
    Profile (formerly client), Anonymous profile (formerly client) This method lets you deactivate only one promotion at a time. client.deactivatePromotion
    Batch deactivate promotions
    /v4/promotions/promotion/batch-deactivate
    Profile (formerly client), Anonymous profile (formerly client) This method lets you deactivate a number of promotions at a time. client.deactivatePromotion
    Deactivate a promotion as a Workspace
    /v4/promotions/promotion/deactivate-for-client/{identifierType}/{identifierValue}
    Workspace (formerly business profile), Synerise User This method lets you deactivate only one promotion at a time. client.deactivatePromotion
    Batch deactivate promotion
    /v4/promotions/promotion/batch-deactivate-for-client/{identifierType}/{identifierValue}
    Workspace (formerly business profile), Synerise User This method lets you deactivate a number of promotions at a time. client.deactivatePromotion

Active

When a promotion receives this status it means the promotion is ready to be applied (for example, for deducting the discount amount from the transaction value, purchasing an item with loyalty points, receiving one item for free, and so on). The promotion can receive this status as a result of the following methods:

Method API consumer Description Events generated
Activate a promotion
/v4/promotions/promotion/activate
Profile (formerly client), Anonymous profile (formerly client) This method lets you activate only one promotion at a time. client.activatePromotion
Batch activate promotions
/v4/promotions/promotion/batch-activate
Profile (formerly client), Anonymous profile (formerly client) This method lets you activate a number of promotions at a time. client.activatePromotion
Activate a promotion as a Workspace
/v4/promotions/promotion/activate-for-client/{identifierType}/{identifierValue}
Workspace (formerly business profile), Synerise User This method lets you activate only one promotion at a time. client.activatePromotion
Batch activate promotion as Workspace
/v4/promotions/promotion/batch-activate-for-client/{identifierType}/{identifierValue}
Workspace (formerly business profile), Synerise User This method lets you activate a number of promotions at a time. client.activatePromotion

Redeemed

When a promotion receives this status it means that the promotion has been used as many times as the limit allowed and cannot be used again by a customer. A promotion can be redeemed only when it’s in active status.

Redemption of the promotion is optional and it can be done by the methods presented in the table below. Usually, the redemption request is sent from an e-commerce/point of sales. To prevent fraud, execution of the methods is recommended right after the transaction has been made.

Optionally, when decide to send a transaction to the Synerise database, you can include an object with the value of the code parameter of the promotion in a request body and then Synerise will redeem a promotion automatically (details available in point 4 of the Full variant process outline).

Method API consumer Description Events generated
Redeem a promotion
/v4/promotions/promotion/redeem
Workspace (formerly business profile), Synerise User This method lets you redeem only one promotion at a time. client.removePoints
Batch redeem promotions
/v4/promotions/promotion/batch-redeem
Workspace (formerly business profile), Synerise User This method lets you redeem a number of promotions at once. client.removePoints

Promotion implementation variants


Before implementing promotions, you must decide on the promotion implementation variant. The distinction between these variants is the location of the promotion calculation logic, either in your backend (point of sale, e-commerce or m-commerce) - partial or within the Synerise platform - full. The specified component is then responsible for recalculating the final transaction value after applying any discounts.

Features

When creating a promotion, you can use the following functionalities for both promotion scopes (selected items and entire basket):

Full variant Partial variant
supported discount types:
- for entire basket promotions: percentage and amount discounts (for example, -20%, - $20 discounts);
- for selected products promotions: setting an exact price, percentage and amount discounts (for example, -20%, - $20 discounts)
supported discount types:
- for entire basket promotions: percentage and amount discounts (for example, -20%, - $20 discounts);
- for selected products promotions: setting an exact price, percentage and amount discounts (for example, -20%, - $20 discounts)
limits per users and activations; the following variants are supported:
- promotion available only for a specific number of customers - first come, first served
- promotion available for all customers; which can be used a specific number of times per transaction
- promotion with limits on activations per transaction (for example, a customer can use loyalty points to purchase an item for free, and you can limit the number of items purchased at once)
limits per users and activations; the limits are defined in the promotions in Synerise, but your systems must handle applying the limits
fixed discounts (the same discount amount for each purchase) or step discounts (each purchase triggers higher discount) fixed discounts (the same discount amount for each purchase) or step discounts (each purchase triggers higher discount)
selecting products to be included/excluded from the promotion selecting products to be included/excluded from the promotion
selecting points of sales where the promotion is applicable selecting points of sales where the promotion is applicable
assigning priority to each promotion (if you use a default logic of not combining promotions) assigning priority to each promotion (if you use a default logic of not combining promotions)
specific basket value as a promotion trigger (for example, a promotion is applicable for a customer whose transaction value ranges between $20 to $75) specific basket value as a promotion trigger (for example, a promotion is applicable for a customer whose transaction value ranges between $20 to $75)
Only “For selected items” promotion scope: buy one, get one (BOGO) logic (promotion which enables acquiring specific number of items for free or with a specific discount if a condition is met, for example, a customer purchased X specific items) Only “For selected items” promotion scope: buy one, get one (BOGO) logic (promotion which enables acquiring specific number of items for free or with a specific discount if a condition is met, for example, a customer purchased X specific items)
Tip: Both variants are presented as a baseline and process outlines can be customized to your business needs.

Full variant

Synerise acts as promotion engine where your backend sends the basket items to Synerise, Synerise calculates the final value of the basket (applying the promotions according to the logic, which is unavailable for your backend) and sends back recalculated values.

Prerequisites

  • Have customers in your database.
  • Implement a tracking code in the website. This will let you track the activity of your customers except for offline points of sales and mobile applications.
  • Implement collecting transaction events in real-time - recommended if the redemption of promotions relies on data sent within the transaction event, real-time processing is essential to prevent fraud.
  • To display promotions through documents and screen views with promotions in a mobile application, implement mobile SDK.
  • Import a product feed into Synerise, so you can select items included in a promotion.
  • Optionally, import a list of stores to the Catalogs module, so you can select the stores where the promotion is active.

Process outline

Full variant implementation
Full variant implementation
  1. In Synerise, create or import promotions.

  2. Display a promotion in the communication channel of your choice and if you want to limit the number of redemptions (which is obligatory when a promotion involves spending loyalty points), you need to implement in your communication channel (such as a mobile app, a website and so on) a solution that lets your customers activate a promotion before they use it. Use one of the following methods for implementing this solution:

    Method API consumer Description Events generated
    Batch activate promotions
    /v4/promotions/promotion/batch-activate
    Profile (formerly client), Anonymous profile (formerly client) This method lets you activate a number of promotions at a time. client.activatePromotion
    Batch activate promotions as Workspace
    /v4/promotions/promotion/batch-activate-for-client/{identifierType}/{identifierValue}
    Workspace (formerly business profile), Synerise User This method lets you activate a number of promotions at a time. client.activatePromotion
  3. During the checkout process:

    1. Send a request to Synerise to apply promotions using one of the following methods:

      Method API consumer Description Events generated
      Process basket
      /v4/promotions/v2/sale/process-sale/{identifierType}/{identifierValue}
      Workspace (formerly Business Profile), Synerise User This method lets you apply promotions to which a recognized customer is entitled and send back the final transaction value to the shop after discounts. n/a
      Process anonymous Profile’s basket
      /v4/promotions/v2/sale/process-anonymous-sale
      Workspace (formerly Business Profile), Synerise User This method lets you apply promotions to which an anonymous customer is entitled and send back the final transaction value to the shop after discounts. n/a
    2. Synerise responds with the final transaction value and transaction details after applying the promotions.

  4. After a customer makes a purchase:

    1. Record the transaction(s) to Synerise database using one of the methods in the table below. If you skip including the promotion in the transaction, proceed to the next step. If you will send promotion data in the transaction, contact the Synerise support to enable it for your workspace and include an object with the value of the code parameter of the promotion in the request body, so Synerise can redeem it automatically. For example:

              {
                "client": {
                  "customId": "string",
                  ...
                },
                "metadata": {},
                "orderId": "be466362-71e9-4bdd-ad11-bfacead5276b",
                "paymentInfo": {
                  "method": "CASH"
                },
                "products": [
                  {
                    "cancel": false,
                    "finalUnitPrice": {
                      "amount": 3.25,
                      "currency": "USD"
                    },
                    ...
                  }
                ],
              "promotionDetails": [
                    {
                      "promotionCode": "b1e794ff-f3b7-4530-aa80-44931eb81f35",
                      "quantityToRedeem": 3
                    },
                    {
                      "promotionCode": "d93a01c3-4c4e-4190-ace0-b4c3a8984f25",
                      "quantityToRedeem": 10
                    }
                  ]
              } 
                

      Method API consumer Description Events generated
      Create a transaction
      /v4/transactions
      Workspace (formerly Business Profile) This method lets you add a new transaction to Synerise database. transaction.charge
      Batch add or update transactions
      /v4/transactions/batch
      Workspace (formerly Business Profile) This method lets you add batch of new transactions or update existing transactions in the Synerise database. transaction.charge
    2. Send a request to Synerise to redeem promotion/loyalty points by using the following method. To prevent fraud, this request should be sent as soon as possible.
      If you included a promotion information in the request that adds a transaction to Synerise, this step can be skipped.

      Method API consumer Description Events generated
      Redeem a promotion
      /v4/promotions/promotion/redeem
      Workspace (formerly Business Profile), Synerise User This method lets you redeem a promotion and loyalty points. client.removePoints
      Batch redeem promotions
      /v4/promotions/promotion/batch-redeem
      Workspace (formerly Business Profile), Synerise User This method lets you redeem up to 100 promotions and loyalty points at a time. client.removePoints

Rounding prices

While executing the Process basket and Process anonymous Profile’s basket methods, the prices of items after deductions are rounded according to Bankers Rounding.

Combining promotions

When a customer is entitled to more than one promotion which are mutually exclusive, you can define the exact behavior depending on the promotion scope.

  • For entire basket

    • If don’t want to combine promotions, select one of the modes:
      • Default, no configuration required: A customer is assigned a promotion with the highest priority (priority is defined in the process of creating a promotion in Synerise).
      • The engine selects the most beneficial (highest) discount - To apply this strategy, contact Synerise support.
    • If you want to combine promotions, enable combining the amount of basket discounts assigned to a customer using the Update settings for current Workspace method. In the request, include the saleSettings object with the parameters that let you enable combining basket discounts and define the settings:
      • combineBasketDiscounts - this parameter lets you enable combining basket discounts, by default this option is disabled (false)
      • priceValueBaseStrategy - this object lets you define the base price for subsequent discounts (from the original price or from the price after the first discount)
      • discountOrder - this object lets you define the order of applying discounts for the purposes of the strategy selected in priceValueBaseStrategy
  • For selected items
    If there is more than one promotion applicable for a customer, the system:

    1. Calculates the discount from combining the percentage and amount discounts on a given item. If only one of the types exists, the other one is ignored in the calculation.
    2. Checks the discount from applying an exact price promotion.
    3. Applies one of the above options to maximize the resulting discount for the customer.

    For example, a customer is entitled to 3 promotions for various items simultaneously (Promotion A, Promotion B, and Promotion C):

    Discount type Discount value Item value before Item value after discount
    Promotion A Amount -$5 $15 $10
    Promotion B Percentage -10% $25 $22,5
    Promotion C Exact price n/a $14,99 $11,99

    This means that the system will apply Promotion A and Promotion B, because the combination of percentage and amount discounts gives a customer a $7 discount, whereas the exact price discounts gives only a $3 discount.

Partial variant

Synerise sends the ID of the promotion to your backend and your backend calculates the amount to be deducted from the prices according to the logic defined in the promotion. The promotion must be also created in your backend.

Prerequisites

  • Have customers in your database.
  • Implement a tracking code in the website. This will let you track the activity of your customers except for offline points of sales and mobile applications.
  • Implement collecting transaction events in real-time - recommended if the redemption of promotions relies on data sent within the transaction event, real-time processing is essential to prevent fraud.
  • To display promotions through documents and screen views with promotions in a mobile application, implement mobile SDK.
  • Import a product feed into Synerise, so you can select items included in a promotion.
  • Optionally, import a list of stores to the Catalogs module, so you can select the stores where the promotion is active.
  • Create a promotion with the same ID as promotion in Synerise in your point of sale.

Process outline

Partial variant implementation
Partial variant implementation
  1. Create a promotion in your shop (for example, cash register).
  2. In Synerise, import promotions to Synerise.
  3. Display a promotion in the communication channel of your choice and if you want to limit the number of redemptions (which is obligatory when a promotion involves spending loyalty points), you need to implement in your communication channel (such as a mobile app, a website and so on) a solution that lets your customers activate a promotion before they use it. Use one of the following methods for implementing this solution:
    Method API consumer Description Events generated
    Batch activate promotions
    /v4/promotions/promotion/batch-activate
    Profile (formerly client), Anonymous profile (formerly client) This method lets you activate a number of promotions at a time. client.activatePromotion
    Batch activate promotions as Workspace
    /v4/promotions/promotion/batch-activate-for-client/{identifierType}/{identifierValue}
    Workspace (formerly business profile), Synerise User This method lets you activate a number of promotions at a time. client.activatePromotion
  4. During the checkout process:
    1. Send a request for the list of promotions available to the customer by using the following method:

      Method API consumer Description Events generated
      Get Profile promotions by a custom filter
      /v4/promotions/promotion/get-for-client-by-custom-settings/{identifierType}/{identifierValue}
      Workspace (formerly Business Profile), Synerise User This method lets you retrieve the list of promotions available to the customer. It is recommended to execute this method during the checkout process. client.promotionRequest
    2. Synerise responds with a list of promotions to which a customer is entitled.

  5. After a customer makes a purchase:
    1. Record the transaction(s) to Synerise database using one of the methods in the table below. If you skip including the promotion in the transaction, proceed to the next step. If you will send promotion data in the transaction, contact the Synerise support to enable it for your workspace and include an object with the value of the code parameter of the promotion in the request body, so Synerise can redeem it automatically. For example:

            {
              "client": {
                "customId": "string",
                ...
              },
              "metadata": {},
              "orderId": "be466362-71e9-4bdd-ad11-bfacead5276b",
              "paymentInfo": {
                "method": "CASH"
              },
              "products": [
                {
                  "cancel": false,
                  "finalUnitPrice": {
                    "amount": 3.25,
                    "currency": "USD"
                  },
                  ...
                }
              ],
            "promotionDetails": [
                  {
                    "promotionCode": "b1e794ff-f3b7-4530-aa80-44931eb81f35",
                    "quantityToRedeem": 3
                  },
                  {
                    "promotionCode": "d93a01c3-4c4e-4190-ace0-b4c3a8984f25",
                    "quantityToRedeem": 10
                  }
                ]
            } 
              

      Method API consumer Description Events generated
      Create a transaction
      /v4/transactions
      Workspace (formerly Business Profile) This method lets you add a new transaction to Synerise database. transaction.charge
      Batch add or update transactions
      /v4/transactions/batch
      Workspace (formerly Business Profile) This method lets you add batch of new transactions or update existing transactions in the Synerise database. transaction.charge
    2. Send a request to Synerise to redeem promotion/loyalty points. This request should be sent as soon as possible to prevent fraud.
      If you included a promotion information in the request that adds a transaction to Synerise, this step can be skipped.

      Method API consumer Description Events generated
      Redeem a promotion
      /v4/promotions/promotion/redeem
      Workspace (formerly Business Profile), Synerise User This method lets you redeem a promotion and loyalty points. client.removePoints
      Batch redeem promotions
      /v4/promotions/promotion/batch-redeem
      Workspace (formerly Business Profile), Synerise User This method lets you redeem up to 100 promotions and loyalty points at a time. client.removePoints

Displaying promotions


You can display promotions on your website, in a mobile application, or on other devices (for example, digital signage). You can do it in the following ways:

  • Using the API:

    Method API consumer Description Events generated
    Get a Profile’s promotion as Profile
    /v4/promotions/promotion/get-for-client
    Profile (formerly client), Anonymous profile (formerly client) This method lets you retrieve, sort, and filter all promotions available to a profile. To filter by the channel in which you want to display the promotion, use tagNames (you must add tags to the promotions when creating them). n/a
  • Create a document that contains a promotion insert in its body and display the document in a mobile application using the following methods:

    Example promotion insert:

      {% promotion %} 58b68c6f-b22a-4860-8869-28fe3d529f94 {% endpromotion %}
      

    Where 58b68c6f-b22a-4860-8869-28fe3d529f94 is a UUID of a promotion.

😕

We are sorry to hear that

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

😉

Awesome!

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

Close modal icon Placeholder alt for modal to satisfy link checker