> ## Documentation Index
> Fetch the complete documentation index at: https://developer.voyado.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Promotions XML create & assign

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.

<Warning>
  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.
</Warning>

## Create multichannel promotion

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

<AccordionGroup>
  <Accordion title="See minimal XML">
    This is the minimal amount of information you need in your XML file to create a promotion:

    ```xml Minimal information theme={null}
    <?xml version="1.0"?>
    <promotions>
        <createOrUpdate>
            <promotion>
                <promotionName></promotionName>
                <externalPromotionId></externalPromotionId>
            </promotion>
        </createOrUpdate>
    </promotions>
    ```

    <ResponseField name="promotionName" type="String" required>
      The promotion's name as shown in the POS, for example.
    </ResponseField>

    <ResponseField name="externalPromotionId" type="String" required>
      External ID of the promotion. Must be unique for a new promotion to be created. Max 450 characters.
    </ResponseField>
  </Accordion>

  <Accordion title="See extended XML">
    Here is the complete XML model for creating a promotion.

    ```xml theme={null}
    <?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>
    ```

    <ResponseField name="promotionName" type="String" required>
      The promotion's name as shown in the POS, for example.
    </ResponseField>

    <ResponseField name="externalPromotionId" type="String" required>
      The external ID of the promotion. It must be unique for a new promotion to be created. Max 450 characters.
    </ResponseField>

    <ResponseField name="published" type="Boolean">
      Will default to "true" if not specified.
    </ResponseField>

    <ResponseField name="validFromDate" type="Date">
      If not specified and this is a new promotion, the current date will be used.
    </ResponseField>

    <ResponseField name="validToDate" type="Date">
      The last day of validity.
    </ResponseField>

    <ResponseField name="presentation.heading" type="String">
      Will default to `promotionName` if not specified
    </ResponseField>

    <ResponseField name="presentation.description" type="String">
      Will default to `promotionName` if not specified
    </ResponseField>

    <ResponseField name="redemptionChannels" type="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.
    </ResponseField>

    <ResponseField name="redemptionChannel.type" type="String" required>
      Must be `ECOM` or `POS`.
    </ResponseField>

    <ResponseField name="redemptionChannel.valueType" type="String">
      Valid values: `EXTERNALOFFER`, `PERCENT`, `MONEY`, `MANUAL`. If the `redemptionChannels` element is omitted entirely, all channels default to `EXTERNALOFFER`.
    </ResponseField>

    <ResponseField name="redemptionChannel.value" type="String">
      Will default to `promotionName` if not specified. Max 512 characters.
    </ResponseField>

    <ResponseField name="redemptionChannel.instruction" type="String">
      Defaults to null if not specified.
    </ResponseField>

    <Tip>
      A promotion that is active and has a `validFromDate` in the future can be found under **Scheduled Promotions** in the Engage UI.
    </Tip>
  </Accordion>
</AccordionGroup>

## Assign promotion to contact

Adding a promotion code to a promotion will set the "published status" of the promotion to "true".

```xml theme={null}
<?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>
```

<ResponseField name="promotion.externalPromotionId" type="String 450" required>
  The external id of the promotion. Max 450 characters.
</ResponseField>

<ResponseField name="promotionCode.externalPromotionCodeId" type="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.
</ResponseField>

<ResponseField name="promotionCode.contactId" type="String" required>
  Engage contact ID (GUID) for the contact. Max length 255.
</ResponseField>

<ResponseField name="promotionCode.externalContactId" type="String">
  **Deprecated.** Will be removed in a future version. Do not use.
</ResponseField>

<ResponseField name="promotionCode.validFromDate" type="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.
</ResponseField>

<ResponseField name="promotionCode.validToDate" type="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.
</ResponseField>

<ResponseField name="promotionCode.code" type="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".
</ResponseField>

## Create and assign to specific contacts

In this example, the promotion is created and assigned in the same file.

<Tip>
  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.
</Tip>

<Tip>
  There is a maximum 10,000 promotion codes per promotion per file.
</Tip>

```xml theme={null}
<?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.