Guides
AcademyOptiCircleoptimove.com

Promotion System Integration

Suggest Edits

This document provides guidance on integrating Optimove with an external promotion or bonus system via API.

This integration empowers Optimove to efficiently execute campaigns with seamless delivery of promotions to your customers.

Note: All the API calls mentioned throughout this document can be found in the Optimove API Guide. You might also want to refer to Getting Started with the Optimove API.

In this article we will cover the following topics:

Promotion System Integration for Scheduled Campaigns

Get a step-by-step guide of how information flows between Optimove and your promotion system to activate a promotion for scheduled campaigns.


There are two flows you can follow:

  • Flow 1: this is relevant if you'd like promotional campaigns to be sent to all customers in your Target Group
  • Flow 2: this is relevant if you'd like promotional campaigns to be sent _only _to customers for whom the promotion was already successfully activated within your promotion system using Conditional Execution. To allocate promotions using Conditional Execution, please refer to the 'Setting Up Conditional Execution' article.

Flow 1

Step 1: Register a Listener to Receive Notifications

For a promotion system to be notified by Optimove whenever a campaign offering a promotion is ready to be executed, you need to deploy a “listener” and register it with the Optimove REST API.

Once your listener is registered, Optimove will notify it anytime a new campaign is ready by sending an HTTP request with a payload containing the Campaign ID and event type. Then, your system will be able to retrieve the relevant customer and promotional details from Optimove and update the promotional system accordingly.

Listener registration only needs to be done once unless you wish to change your service endpoint at a later date and/or register additional routes for other execution channels.

Step 2: Synchronize the List of Available Promotions

To use promotions in the promotion system within Optimove, the list of available promotions must be synchronized between the promotion system and Optimove via API.

The API calls used to manage the promotions registered with Optimove are:

  • AddPromotions– Adds promo codes and associated names that will be available for selection when running a campaign.
  • DeletePromotions– Removes previously added promo codes.
  • GetPromotions– Returns an array of all defined promo codes and associated names.

Promotions can be activated when creating a campaign in Optimove. This enables the Optimove software to initiate a process for automatically granting promotions to individual customers in the promotion system.

Step 3: Listener Notified that a New Campaign is Ready

As soon as Optimove has completed preparing each new campaign, it will notify your registered listener and provide the Campaign’s ID.

Step 4: Activate Promotions for Relevant Customers

To update each customer in the promotion system with the proper promotion upon notification that a campaign’s details are ready for retrieval, your system needs to perform the following steps:

  1. Retrieve the campaign details using the GetCampaignDetails API call with the Campaign ID that was supplied to the listener, and extract the following details for the campaign:
    • Duration – this is used to determine when the promotion system must remove the promo codes from the specified customers (unless you call the GetCustomersActionEndedByDate function on a daily basis to determine which codes to remove for which customers).
    • Lead Time – when not zero, this is used to delay the application of the promo codes until a later day.
  2. Retrieve the promo code, Action IDs, and the list of Customer IDs for the Campaign ID using the GetCustomerExecutionDetailsByCampaign API call.

Please note:

  • By default, 10,000 rows are returned for each call (assuming there are at least 10,000 records to return). For details about requesting subsequent pages of results and/or using a smaller or larger page size, refer to Response Paging for Customer-Related Functions.
  • This function does not return control group customers in its response.

Now that you have the full list of Customer IDs and Promotion IDs for the campaign, update your promotion system with this data so that each customer will be eligible for the proper promotions during the period of time specified by the campaign.

Remember to set the eligibility expiration date for each customer based on the campaign’s specified duration period.

Managing Deleted Campaigns

If a marketer deletes a campaign in Optimove, your system can retrieve the list of customers who had been included in the campaign to deactivate their promotions from your promotion system.

To do this, carry out the following steps:

  1. Register a listener for this process using the RegisterEventListener API call with EventTypeID=4. This step only needs to be done once for all future promotion-conditional campaigns.
  2. When a campaign is canceled within Optimove, Optimove will notify the specified listener for EventTypeID=4 as described in the RegisterEventListener documentation.
  3. Upon notification to this listener, your system calls GetCanceledCampaignCustomers to retrieve the list of customer IDs that had been included in the specified campaign.
  4. Your system deactivates the promotions in the promotion system for the retrieved list of Customer IDs.

Promotion System Integration for Triggered Campaigns

Get a step-by-step guide to how information flows between Optimove and your service for the purpose of activating a promotion for real-time triggered campaigns:

Step 1: Register a Listener to Receive Notifications When Customers Meet the Trigger Criteria

Whenever Optimove detects that a customer meets the Trigger criteria, Optimove will notify your system so that you can activate the promotion in your system. For this purpose, you will need to deploy a “listener” and register it with the Optimove REST API.

Register the URL of your service using the RegisterEventListener API call with EventTypeID = 11 to a dedicated Channel ID. This only needs to be done once unless you wish to change the address of your service endpoint and/or register additional routes for other execution channels.

Once your listener is registered, Optimove will notify it any time a customer meets the Trigger criteria, by sending an HTTP request with a payload containing the campaign and customer details.

Step 2: Synchronize the List of Available Promotions

For the promotions in the promo system to be available to marketers for use in campaigns within Optimove, the list of available promotions must be synchronized between the promo/bonus system and Optimove via API. The API calls used to manage the promotions registered with Optimove are:

  • AddPromotions– Adds promo codes and associated names that will be available for selection when running a campaign.
  • DeletePromotions– Removes previously-added promo codes.
  • GetPromotions– Returns an array of all defined promo codes and associated names.

Once promotions are added to Optimove, marketers can select them when setting up a campaign. This enables the Optimove software to initiate a process for automatically granting promos/bonuses to individual customers in the promo/bonus system, as specified by campaigns:

Please note:

  • Promotions added will be synced to both the scheduled and triggered campaign builder promotion dropdown.

Step 3: Notify the Listener that a Customer has Met the Trigger Criteria

As soon as Optimove has detected that a customer has met the Trigger criteria, an HTTP request will be sent with a payload containing the promotion among other details such as the campaign and customer details. The API payload you will receive in real-time is described in RegisterEventListener under "EventTypeID = 11".

Please note:

  • By default, any attribute defined as a personalization tag and all the event and parameter values related to the trigger will be sent as part of the payload for personalization purposes. To exclude one or more of the personalization tags and parameter values for a certain channel, please contact your CSM.

Step 4: Activate Promotion for Relevant Customer

Make sure to activate the promotion in your system for the customer you received in the notification so they can use the promotion.

Important Notes about the Integration Process

  1. This integration flow is relevant for Optimove clients using Track and Trigger.
  2. Client Credentials – The code you develop to interface with Optimove via the API must utilize a different set of credentials for each individual client. Optimove or the client can provide you with these credentials. These credentials are required by the Login API call, which must be called before making any other API calls.
  3. Please contact the Product Integration Team to provide you with the exact Channel ID you should register as the real-time listener (RegisterEventListener).
  4. For Unique Promo Codes, please follow this article.

Updated 8 months ago