Skip to main content
Multichannel promotions can be created and assigned to specific contacts:
  • In the Engage UI
  • Via the API
  • 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 multichannel promotion

Your XML file can either contain the minimum of information or have a number of extra fields.
This is the minimal amount of information you need in your XML file to create a promotion:
Minimal information
<?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.
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 with value type EXTERNALOFFER. Important: Redemption channels can only be configured when the promotion is first created via XML import. Subsequent imports updating the same promotion (matched by externalPromotionId) will NOT modify redemption channels.
​
redemptionChannel.type
String
required
Must be ECOM or POS.
​
redemptionChannel.valueType
String
Valid values: EXTERNALOFFER, PERCENT, MONEY, MANUAL. If the redemptionChannels element is omitted entirely, all channels default to EXTERNALOFFER.
​
redemptionChannel.value
String
Will default to promotionName if not specified. Max 512 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. Must be unique across all promotions (not just unique in the current promotion). Max 450 characters.
​
promotionCode.contactId
String
required
Engage contact ID (GUID) for the contact. Max length 255.
​
promotionCode.externalContactId
String
Deprecated. Will be removed in a future version. Do not use.
​
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
required
The code exposed to the customer. Adding a promotion code to a promotion will set the published status of the promotion to “true”.

​
Create and assign to specific contacts

In this example, the promotion is created and assigned in the same file.
Only one promotion per file is supported. To import multiple promotions, place multiple XML files in the import folder. The job processes all .xml files sequentially.
There is a maximum 10,000 promotion codes per promotion per 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>
                    <validFromDate></validFromDate>
                    <validToDate></validToDate>
                    <code></code>
                </promotionCode>
            </promotionCodes>
        </promotion>
    </createOrUpdate>
</promotions>
See the previous section for the field descriptions.

​
File handling after import

After the import job processes a file, you will get one of these results:
  • Successful import: The file is moved to an “Archive” subfolder within the import directory.
  • Validation or import failure: The file is moved to an “Error” subfolder, along with a “.log” file containing error details and line numbers.
  • File sharing violation or SQL timeout: The file remains in the import folder and will be retried on the next job run.