Skip to main content
Creating a multichannel promotion can either be done:
  • In the Engage UI
  • Via the API
  • By XML file import
While the assignment of multichannel promotion to specific contacts can be done:
  • In the Engage UI
  • By XML file import
This article goes through creating and assigning multichannel promotions by XML file import.
When assigning a promotion by XML file, the promotion needs to exist in Engage prior to the assignment, or at least be added in the same file as the assignment.

​
Create a multichannel promotion

Your XML file can either contain the minimum of information or have a number of extra fields.

​
Minimal XML file

This is the minimal amount of information you need in your XML file to create a promotion: 
<?xml version="1.0"?>
<promotions>
    <createOrUpdate>
        <promotion>
            <promotionName></promotionName>
            <externalPromotionId></externalPromotionId>
        </promotion>
    </createOrUpdate>
<promotions>
​
promotionName
String
required
The promotion’s name as shown in the POS, for example.
​
externalPromotionId
String
required
External ID of the promotion. Must be unique for a new promotion to be created. Max 450 characters.

​
Extended XML file

Here is the complete XML model for creating a promotion. 
<?xml version="1.0"?>
<promotions>
    <createOrUpdate>
        <promotion>
            <promotionName></promotionName>
            <externalPromotionId></externalPromotionId>
            <published></published>
            <validFromDate></validFromDate>
            <validToDate></validToDate>
            <presentation>
                <heading></heading>
                <description></description>
            </presentation>
            <redemptionChannels>
                <redemptionChannel>
                    <type></type>
                    <valueType></valueType>
                    <value></value>
                    <instruction></instruction>
                </redemptionChannel>
            </redemptionChannels>
        </promotion>
    </createOrUpdate>
<promotions>
​
promotionName
String
required
The promotion’s name as shown in the POS, for example.
​
externalPromotionId
String
required
The external ID of the promotion. It must be unique for a new promotion to be created. Max 450 characters.
​
published
Boolean
Will default to “true” if not specified.
​
validFromDate
Date
If not specified and this is a new promotion, the current date will be used.
​
validToDate
Date
The last day of validity.
​
presentation.heading
String
Will default to promotionName if not specified
​
presentation.description
String
Will default to promotionName if not specified
​
redemptionChannels
Object
If none is specified, then one channel of each type ECOM and POS will be created.Can only be set on creation.
​
redemptionChannel.type
String
Must be EXTERNALOFFER in this import.
​
redemptionChannel.valueType
String
Must be EXTERNALOFFER in this import.
​
redemptionChannel.value
String
Will default to promotionName if not specified. Max 250 characters.
​
redemptionChannel.instruction
String
Defaults to null if not specified.
A promotion that is active and has a validFromDate in the future can be found under Scheduled Promotions in the Engage UI.

​
Assign promotion to contact

Adding a promotion code to a promotion will set the “published status” of the promotion to “true”. 
<?xml version="1.0"?>
<promotions>
    <createOrUpdate>
        <promotion>
            <externalPromotionId></externalPromotionId>
            <promotionCodes>
                <promotionCode>
                    <externalPromotionCodeId></externalPromotionCodeId>
                    <contactId></contactId>
                    <externalContactId></externalContactId>
                    <validFromDate></validFromDate>
                    <validToDate></validToDate>
                    <code></code>
                </promotionCode>
            </promotionCodes>
        </promotion>
    </createOrUpdate>
<promotions>
​
promotion.externalPromotionId
String 450
required
The external id of the promotion. Max 450 characters.
​
promotionCode.externalPromotionCodeId
String 450
required
The external ID of the promotion code. Needs to be unique across all promotions (not just unique in the current promotion). This is only mandatory if used for redeeming codes. Max 450 characters.
​
promotionCode.contactId
String
required
Engage contact ID for the contact. If used/included, the externalContactId will be ignored. Max length 255.
​
promotionCode.externalContactId
String
required
The external contact ID of the contact. Will be ignored if the contact ID is used/included. Max length 255.
​
promotionCode.validFromDate
Date
Overrides the promotion’s validFromDate for this customer and coupon. Must be same or later than the promotion’s validFromDate. Example: 2022-02-21.
​
promotionCode.validToDate
Date
Overrides the promotion’s validToDate for this customer and coupon. Must be same or later than the promotion’s validToDate. Example: 2022-02-22.
​
promotionCode.code
String 50
Only used when you need to expose the code to the customer. Adding a promotion code to a promotion will set the published status of the promotion to “true”.

​
Create promotion and assign to specific contacts

In this example, the promotion is created and assigned in the same file. 
<?xml version="1.0"?>
<promotions>
    <createOrUpdate>

        <promotion>
            <promotionName></promotionName>
            <externalPromotionId></externalPromotionId>
            <published></published>
            <validFromDate></validFromDate>
            <validToDate></validToDate>
            <presentation>
                <heading></heading>
                <description></description>
            </presentation>
            <redemptionChannels>
                <redemptionChannel>
                    <type></type>
                    <valueType></valueType>
                    <value></value>
                    <instruction></instruction>
                </redemptionChannel>
                ...
            </redemptionChannels>
            <promotionCodes>
                <promotionCode>
                    <externalPromotionCodeId></externalPromotionCodeId>
                    <contactId></contactId>
                    <externalContactId></externalContactId>
                    <validFromDate></validFromDate>
                    <validToDate></validToDate>
                    <code></code>
                </promotionCode>
                <promotionCode>
                ...
                </promotionCode>
            </promotionCodes>
        </promotion>

        <promotion>
            ...
        </promotion>

    </createOrUpdate>
</promotions>
See the previous section for the field descriptions.