Promotions flow
Promotions can be created and assigned to contacts in Engage, and then fetched for display in your e-com or POS. You will need to redeem (mark as used) any promotion that is applied to a purchase.
Prerequisites
Some things need to be done before a promotion can be used.
Set up the promotion in your own ECOM/POS/ERP with whatever discount rules apply.
Set up a matching promotion in Engage.
In Engage, assign the promotion to one or several contacts.
An active promotion can either be exported by XML from Engage to the integrating system, or it can be fetched over the Engage API in real-time. This section will focus on fetching promotions in real-time via API.
The endpoints
GET /api/v2/contacts/{contactId}/promotions
POST /api/v2/contacts/{contactId}
POST /api/v2/contacts/{contactId}/promotions/{promotionId}/redeem
Displaying promotions
When working with promotions you'll need to decide if they are to be shown in the POS or in the customer's My Pages or both, and build the functionality for doing that yourself. These steps will just go through how promotions are fetched and redeemed, not how they are displayed.
Redeeming promotions
Redeeming a promotion in Engage is vital to prevent is from being used again, and to also connect it to the purchase where it was used, for purposes of segmenting and reporting.
First, fetch a customer's active promotions with this endpoint:
GET /api/v2/contacts/{contactId}/promotionsAs integrator, you can filter out promotions based on their redemption channel (for example if some promotions are only available offline / online) by using POS, ECOM, OTHER in the header of the call.
In the API response, Engage returns the available promotions for that customer.
You can now use your price logic to apply the promotion as a deduction at checkout.
If a customer has updated their information during the purchase, Engage needs to receive that updated information. For this, use the usual endpoint for updating contact data:
POST /api/v2/contacts/{contactId}Now redeem the promotion with the /redeem endpoint to stop it being used again:
POST /api/v2/contacts/{contactId}/promotions/{promotionId}/redeemThis will set the promotion to “used” in Engage for that contact.
The promotion should also be included in the same API call used to register the transaction, along with the rest of the transaction's data, to allow Engage to match the receipt to the promotion:
POST /api/v2/receiptsSee here for how you include the promotion's ID in the payload to this endpoint.
Redeem promotions error handling
When no response is received from the Engage API, or when the response has error code 500, you'll need a plan in place to ensure that no data is lost until the connection is restored.
Retry: If your first call is unsuccessful, perform a retry. Follows the recommendations here.
Local file: If errors remain, or no response is received, you should be ready to save the data for the redeemed promotion to local XML files in your system. Then, when the connection has been restored, these files can be transferred to Engage via the FTP server. Data uploaded like this is placed in a queue and handled asynchronously.
If you've updated contact information, then you'll have to handle that as well, in the case of the connection being down. See this section for how that works.
Tip
When uploading XML files via the FTP, contact GUIDs will not be returned from Engage for any new contacts created. Therefore, the next time that contact is identified, you'll need to check if their GUID already exists in your systems, and save it there if it doesn't, to reduce unnecessary API calls and improve your flow.