Table of Contents


This document presents the workflows necessary to integrate Optimove with an external promo/bonus system. Integrating a promo/bonus system with Optimove via API allows Optimove to manage customer campaigns that also automatically grant bonuses, discounts, incentives, etc. to individual customers.

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

Basic Flow Overview

Flow 1: Register a Listener to Receive Notifications

So that your system can be informed by Optimove whenever a campaign offering a promo/bonus is ready to be executed, you need to deploy a “listener” and register it with the Optimove REST API.

Register the URL of your service using the RegisterEventListener API call.

Once your listener is registered, Optimove will notify it any time 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 promo/bonus details from Optimove, and update the promo/bonus system accordingly. See Flow 4, below, for details.

You can optionally configure your campaign to be sent only to customers for whom the promotion was already successfully activated (using EventTypeID=5 when registering the listener). See Flow 6, below, for more information about setting up this type of campaign.

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

Flow 2: Synchronize the List of Available Promotions

In order for the promotions in the promo/bonus system to be available to marketers for use in campaigns within the Optimove user interface, 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:

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

Flow 4: Activate Promotions for Relevant Customers

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

  1. Login using the Login API call (see here for more information).
  2. 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:
    • TargetGroupID – used in step 3, below
    • Duration – used to determine when the promo/bonus 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)
    • LeadTime – when not zero, used to delay the application of the promotion codes until a later day
  3. Retrieve the promo code, Action IDs and the list of Customer IDs for the Campaign ID using the GetCustomerExecutionDetailsByCampaign API call.

    • By default, 10,000 rows are returned for each call (assuming that there are at least 10,000 records to return). For details about requesting subsequent pages of results and/or to use 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 promo/bonus system with this data so that each customer will be eligible for the proper promotions, discounts, incentives, etc. 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.

Illustrated Sample Use Case

Let's say you created a recurring campaign that is sent to particular customers every day. The campaign has a two-day duration, i.e., the customer has two days within which to use the campaign’s promo/bonus offer. So, customers receiving the campaign on 1 January should be removed from the list of eligible customers on 3 January.

Flow 5: Upon Campaign Cancellation of a Campaign

If a marketer deletes a campaign from the Optimove Marketing Plan, your system can retrieve the list of customers who had been included in the campaign, in order to deactivate their promotions from your promotion system. This process requires the following steps:

  1. Register a listener for this process using the RegisterEventListener API call with EventTypeID=4 (refer to the Optimove API Usage Guide for details on calling RegisterEventListener). 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 which had been included in the specified campaign.
  4. Your system deactivates the promotions in the promotion system for the retrieved list of customer IDs.

Flow 6 (Optional): Limit Campaign Delivery to Customers for Whom the Promotion was Activated

You may want to ensure that your campaign is sent only to customers for whom the promotion was already activated in your promo/bonus system.

For example, perhaps you want to send an email campaign to 1000 customers, offering a particular promotion (e.g., 10% off the entire store). You will set up the campaign in Optimove so that Optimove will first activate this promotion for the customers in your promotion system. Only after the promotion was successfully activated for customers will those customers receive the email campaign. Optimove will not send the campaign to any customers for whom the promo activation failed (whatever the reason for the failure).

The following steps describe how such a campaign is accomplished:

1. Register a Listener

Your system needs to register a listener to receive notifications for conditional-execution campaigns as described in Flow 1, above, using EventTypeID=5. Refer to the RegisterEventListener API call documentation for details. This step only needs to be done once for all future promotion-conditional campaigns.

2. Create a template including a promo code personalization tag

If you are using one of Optimove's native channels (Optipush and Optimail), you should use Optimove's Manage Templates to build a template containing the promo code as a personalization tag. There are two options for setting this up:

  • Generic promo code: the promo code is generic for each campaign, meaning that all customers in the same campaign will be assigned the same promo code.
    In this case, use the General tag, as seen in the image below:

  • Personalized promo code: each customer receives a unique promo code.
    In this case, use the Customer Data tag, as shown in the image below:Note: if this attribute is not available as a Customer Data tag in your Optimove instance, ask your CSM to create the "promo code" attribute for you.

3. Select Conditional Execution for the Campaign

When setting up the campaign, select the Conditional Execution checkbox. This instructs Optimove not to send this campaign before the ClearanceRequiredBy arrives and, then, only to customers for whom the promotion was successfully activated.


  • The ClearanceRequiredBy date/time is caluclated by Optimove based on the execution channel(s) specified for the campaign, and is communicated to the listener at the time of EventTypeID=5 notification.
  • If the Conditional Execution checkbox does not appear in your Optimove UI, ask your CSM to activate it for you.

4. Optimove Notifies the Listener that the Campaign is Ready to be Sent

Once the campaign has been processed and is ready to be sent, Optimove notifies the listener your system specified for EventTypeID=5. At this point, Optimove will wait until the ClearanceRequiredBy time has arrived before actually scheduling the campaign for execution.

5. Update Optimove with your customers' unique promo codes

Use this step only in case of generating personalized promo codes.

After you have activated the promo codes in your promotion system, use the Updatecustomerattributes API call in order to update each user's promo code attribute in Optimove.

6. Activate the Promotions for Customers in your Promotion System

Once your listener receives notification that the campaign is ready, your system calls GetProcessedCampaignCustomers to retrieve the list of customers included in this campaign and the promotion(s) associated with each customer (refer to the Optimove API Usage Guide for details on calling GetProcessedCampaignCustomers).

Your system then uses this data to activate the promotions for each customer in your promo system.

7. Notify Optimove Regarding Customers for Whom the Promotion has been Activated

Once the promotions have been activated, your system notifies Optimove regarding which promotions are now active for which customers. This is accomplished using the UpdateCustomerPromotionStatus API call (refer to the Optimove API Usage Guide for details on calling UpdateCustomerPromotionStatus).

8. Optimove Sends the Campaign to Eligible Customers

Once the entire list of customers is updated or when the campaign's specified ClearanceRequiredBy time arrives (whichever occurs first), Optimove will schedule the campaign for execution only to those customer IDs for which PromosUpdated was specified as true using the UpdateCustomerPromotionStatus API call by that time.