Skip to main content

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.