Feature Pack 8

Promotions XML input file

You can use an XML input file to create or change promotions for a store. When you are creating an input file to load promotion data, you can include various XML elements and values in your file. The XML elements that you must include in your input file depend on the properties, description, purchase conditions, rewards, and redemption methods for the promotions that you are loading.

Tip: You can create a promotion in the Promotions tool and then export the promotion with the Data Extract utility to quickly get a sample Promotion XML file. You can use as this XML file as the input file for the Data Load utility to import the promotion into other environments, such as multiple test environments.
The promotion input XML file must be composed of three sections:
<Base>
The elements within this parent element define the identifying and general properties for a promotion.
<Description>
The promotion description information. Include a separate <Description> for each defined language that your store supports for the promotion.
<Elements>
The promotion purchase condition and reward information. Each direct child <Type> element in the <Elements> element is a separate type of condition or reward.

When you create your input file for loading promotion data, you must use the correct name for the child XML elements in the <Base> and <Description> elements. You do not need to set a value for every one of the following elements. When you do not set a value for one of the following elements, the Data Load utility sets the value for the corresponding database column to be NULL.

XML elements within the <Base> section

When you create your input file for loading promotion data, you must use the correct name for the child XML elements in the <Base> section. You do not need to set a value for every one of the following elements. When you do not set a value for one of the following elements, the Data Load utility sets the value for the corresponding database column to be NULL.

PromotionId
The unique ID for the promotion. You must include this element when you are changing promotions. If you are creating a promotion with the Data Load utility, do not include this value. When you are creating a promotion, use the AdministrativeName element.

This element maps to PX_PROMOTION.PX_PROMOTION_ID

AdministrativeName
The administrative name of the promotion. You must include this element when you are creating promotions. The Data Load utility uses this element to resolve an ID for the promotion. If a load operation encounters a duplicate value for the administrative name, the Data Load utility does not load the promotion with the duplicate name.

Maps to PX_PROMOAUTH.ADMINSTVENAME

PromotionGroupIdentifier
The name of the promotion group that the promotion belongs within.

Maps to PX_GROUP.GRPNAME

PromotionGroupStoreIdentifier
The identifier of the store that owns the promotion group that the promotion belongs within.

Maps to PX_GROUP.STOREENT_ID

Comments
The comments for the promotion.

Maps to PX_PROMOAUTH.COMMENTS

Priority
The priority of the promotion.

Maps to PX_PROMOTION.PRIORITY

Exclusive
The exclusivity of the promotion. You can include the following values for this element.
0
The promotion can be combined with any other promotion.
1
The promotion cannot be combined with any other promotions that are in the same promotion group.
2
The promotion cannot be combined with any other promotions.
3
The promotion cannot be combined with any promotions that is in the product level promotion group.
4
The promotion can be stacked on top of other promotions that are in the same promotion group.

Maps to PX_PROMOTION.EXCLSVE

LastUpdateByLogonId
The user logon ID of the business user that last modified the promotion.

Maps to PX_PROMOTION.LOGONID

PerOrderLimit
The number of times that the promotion can be applied to a single order. The default value is -1, which sets no limit.

Maps to PX_PROMOTION.PERORDLMT

PerShopperLimit
The number of times that a shopper can redeem the promotion. The default value is -1, which sets no limit.

Maps to PX_PROMOTION.PERSHOPPERLMT

ApplicationLimit
The overall limit that the promotion can be redeemed. The default value is -1, which sets no limit.

Maps to PX_PROMOTION.TOTALLMT

TargetSales
The target sales figure for the promotion.

Maps to PX_PROMOTION.TGTSALES

PromotionTypeName
The promotion rule type.

Maps to PX_PROMOAUTH.PROMOTIONTYPE

ControlParameter
Control information for the user interface.

Maps to PX_PROMOAUTH.CTLPARAM

StartDate
The starting date for the promotion.

Maps to PX_PROMOTION.STARTDATE

EndDate
The end date for the promotion.

Maps to PX_PROMOTION.ENDDATE

DailyStartTime
The daily start time for the promotion (as if on 2000/01/01).

Maps to PX_PROMOAUTH.DAILYSTARTTIME

DailyEndTime
The daily end time for the promotion (as if on 2000/01/01).

Maps to PX_PROMOAUTH.DAILYENDTIME

Sunday
Indicates whether the promotion is available on Sunday. You can include the following values for this element.
0
The promotion is not available.
1
The promotion is available.

Maps to PX_PROMOAUTH.WEEKDAY_SUN

Monday
Indicates whether the promotion is available on Monday. You can include the following values for this element.
0
The promotion is not available.
1
The promotion is available.

Maps to PX_PROMOAUTH.WEEKDAY_MON

Tuesday
Indicates whether the promotion is available on Tuesday. You can include the following values for this element.
0
The promotion is not available.
1
The promotion is available.

Maps to PX_PROMOAUTH.WEEKDAY_TUE

Wednesday
Indicates whether the promotion is available on Wednesday. You can include the following values for this element.
0
The promotion is not available.
1
The promotion is available.

Maps to PX_PROMOAUTH.WEEKDAY_WED

Thursday
Indicates whether the promotion is available on Thursday. You can include the following values for this element.
0
The promotion is not available.
1
The promotion is available.

Maps to PX_PROMOAUTH.WEEKDAY_THU

Friday
Indicates whether the promotion is available on Friday. You can include the following values for this element.
0
The promotion is not available.
1
The promotion is available.

Maps to PX_PROMOAUTH.WEEKDAY_FRI

Saturday
Indicates whether the promotion is available on Saturday. You can include the following values for this element.
0
The promotion is not available.
1
The promotion is available.

Maps to PX_PROMOAUTH.WEEKDAY_SAT

Type
The type of promotion. You can include the following values for this element.
0
The promotion can be applied to customers that belong to one or more of the targeted customer profiles. If the targeted profile file list is empty, the promotion applies to all customers
1
The promotion applies to only the customers that are explicitly granted the promotion, such as through a coupon.

Maps to PX_PROMOTION.TYPE

Effectivedays
If the promotion is a private promotion, this element indicates how many days after the coupon is issued that the coupon becomes active.

Maps to PX_PROMOTION.EFFECTIVE

Expirationdays
If the promotion is a private promotion, this element indicates how many days after the coupon is issued that the coupon expires.

Maps to PX_PROMOTION.EXPIRE

AllowTransfer
If this promotion is a private promotion, this element indicates whether the coupons for the promotion can be transferred. You can include the following values for this element.
0
The promotion coupons cannot be transferred.
1
The promotion coupons can be transferred.

Maps to PX_PROMOTION.TRANSFER

PromotionCodeRequired
Indicates whether a promotion code is needed to redeem the promotion. You can include the following values for this element.
0
A promotion code is not needed to redeem the promotion.
1
A promotion code is needed.

Maps to PX_PROMOTION.CDREQUIRED

PromotionCodeCue
The public promotion code for the promotion.

Maps to PX_PROMOTION.CODE

DisplayLevel
Indicates where the amounts that are calculated by the calculation code are to display. You can include the following values for this element.
0
OrderItem
1
Order
2
Product
3
Item
4
Contract

Maps to CALCODE.DISPLAYLEVEL

CodeType
The type or promotion code that is needed to redeem the promotion.
0
Public promotion code.
1
Generated code.
2
Imported code.

Maps to PX_CDSPEC.CODETYPE

Pattern
The promotion code generation pattern for generating advanced promotion codes.

Maps to PX_CDSPEC.PATTERN

Count
The number of promotion codes that are to be generated for the promotion.

Maps to PX_CDSPEC.COUNT

CodeStatus
The status of the promotion codes for the promotion. You can include the following values for this element.
0
Not populated.
1
Populated.
2
Processing.
3
Canceled.
4
Generation failed.
5
Importing failed.

Maps to PX_CDSPEC.CODESTATUS

Transferable
Indicates whether promotion codes can be transferred. You can include the following values for this element.
0
Promotion codes can be transferred.
1
Promotion codes cannot be transferred.

Maps to PX_CDSPEC.TRANSFERABLE

XML elements within the <Description> section

When you create your input file for loading promotion data, you must use the correct name for the child XML elements in the <Description> section. You do not need to set a value for every one of the following elements. When you do not set a value for one of the following elements, the Data Load utility sets the value for the corresponding database column to be NULL.

LanguageId
The language for the description information.

Maps to PX_DESCRIPTION.LANGUAGE_ID

AdminDescription
The administrative description of the promotion.

Maps to PX_DESCRIPTION.ADMINDESC

ShortDescription
The short description of the promotion.

Maps to PX_DESCRIPTION.SHORTDESC

LongDescription
The long description of the promotion.

Maps to PX_DESCRIPTION.LONGDESC

Field1
A custom description field for you to use for promotion information.

Maps to PX_DESCRIPTION.FIELD1

Field2
A custom description field for you to use for promotion information.

Maps to PX_DESCRIPTION.FIELD2

Field3
A custom description field for you to use for promotion information.

Maps to PX_DESCRIPTION.FIELD3

Field4
A custom description field for you to use for promotion information.

Maps to PX_DESCRIPTION.FIELD4

Field5
A custom description field for you to use for promotion information.

Maps to PX_DESCRIPTION.FIELD5

XML elements within the <Elements> section

The naming of child elements for the <Elements> section is different from the <Base> and <Description> sections. Inside the <Elements> element, you must use the correct name for only the <SubType>, <Sequence>, and <Data> child elements. For the <Type> and <Name> elements, which you can include multiple times for a promotion, you must replace the element names with the appropriate identifying name.

The following code demonstrates the structure for the child elements in the <Elements> section of the input file.
<Elements>
  <Type>
    <SubType>...</SubType>
    <Sequence>...</Sequence>
    <Data> 
      <name>value</name>
      <name>value</name>
    </Data>
    <Type>
	      <SubType>...</SubType>
      <Sequence>...</Sequence>
      <Data> 
        <name>value</name>
        <name>value</name>
      </Data>
    </Type>
    ...
  </Type>
<Elements>
<Type>
The name of a promotion condition or reward. Replace <Type> with the name of the condition or reward. For example, <PurchaseCondition>.

You can include multiple <Type> elements for a promotion. A <Type> element can be nested within another <Type> element. For example, the following code includes a <Type> element that is called <IncludePaymentTypeIdentifier>, which is nested inside a <Type> element that is called <PurchaseCondition>.

<Elements>
  <PurchaseCondition>
    ...
    <IncludePaymentTypeIdentifier>
	  ...
    </IncludePaymentTypeIdentifier>
  </PurchaseCondition>
  ...
  <Elements>

Maps to PX_ELEMENT.TYPE.

SubType
The subtype of a promotion element <Type>. Each <Type> can have a <SubType>. For example, a <Type> element that is named <PurchasingCondition> might have a <SubType> element that is called <OrderLevelPercentDiscountPurchaseCondition>.

Maps to PX_ELEMENT.SUBTYPE

Sequence
The sequence that the promotion purchase condition or reward element displays for a promotion. Each <Type> element can include a <Sequence> element.

Maps to PX_ELEMENT.SEQUENCE

Data
Indicates that name-value pair information exists for a parent <Type> element (purchase condition or reward). All child XML elements in this <Data> element are name-value pairs. Include each name-value pair as a separate element. This element does not map to any column and is for use by the Data Load utility to read the promotion input file XML and identify name-value pair elements.
<Name>
The name of a name-value pair. Replace <Name> with the appropriate name. For example, in the following code snippet from an input file Currency, MinimumPurchase, <FixedCost>, and <AdjustmentType> are all used as <Name> elements:
<Elements>
  <PurchaseCondition>
  ...
    <Data>    
      <Currency>USD</Currency>
      <MinimumPurchase>70</MinimumPurchase>
      <FixedCost>0</Fixed Cost>
      <AdjustmentType>IndividualAffectedItems</AdjustmentType>
    </Data>
  </PurchaseCondition>
  ...
<Elements>

Maps to PX_ELEMENTNVP.NAME

The value for each <Name> element, such as USD in the preceding code snippet, maps to PX_ELEMENTNVP.VALUE