Create and assign promotions by XML

Creation of a multichannel promotion can either be done in the Engage UI, by the API or by XML file import.

The assignment of multichannel promotion to specific contacts can be done either in the Engage UI or by XML file import.

This article goes through creating and assigning multichannel promotions via XML file import.

Note

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

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>

Attribute	Format	Description
*promotionName	String	The promotion's name as shown in the POS, for example.
*externalPromotionId	String	The external ID of the promotion. It must be unique for a new promotion to be created. Max 450 characters.

Items marked with * are mandatory.

Extended

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>

Attribute	Format	Description
*promotionName	String	The promotion's name as shown in the POS, for example.
*externalPromotionId	String	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		If none is specified, then one channel of each type ECOM and POS will be created.Can only be set on creation.
redemptionChannel.type	ECOM/POS
redemptionChannel.valueType	EXTERNALOFFER	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.

Items marked with * are mandatory.

Important

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>

Attribute	Format	Description
*promotion.externalPromotionId	String 450	The external id of the promotion. Max 450 characters.
*promotionCode.externalPromotionCodeId	String 450	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	Engage contact ID for the contact. If used/included, the externalContactId will be ignored. Max length 255.
*promotionCode.externalContactId	String	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 higher 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 higher 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 codet o a promotion will set the published status of the promotion to "true".

Items marked with * are mandatory

Create multichannel 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.

In this section: