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:

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:

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).

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

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

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

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:

  • Android
  • Flutter
  • iOS
  • React Native

  Example promotion insert:

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

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