You are here:
Promotions Import and Export in B2C Commerce
Use the promotion.xsd to specify an import and export file for both
campaigns and promotions. This topic applies to B2C Commerce.
Top Level Element and Mass Data Import Structure Examples in B2C Commerce
Structure examples for defining campaign and promotion elements at the top level and for mass data support. This topic applies to B2C Commerce.
The top-level campaign or promotion elements can appear as follows:
<!-- top-level element -->
<xsd:element name="promotions">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="campaign" type="Campaign" minOccurs="0" maxOccurs="unbounded" />
<xsd:element name="promotion" type="Promotion" minOccurs="0" maxOccurs="unbounded" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>For importing mass data, use this structure:
<!-- fake element for mass data support -->
<xsd:element name="campaign" type="Campaign" />
<xsd:element name="promotion" type="Promotion" />Promotion Campaigns in B2C Commerce
A campaign is a complex data type within the promotion.xsd schema that
is primarily used to group promotions. This topic applies to B2C Commerce.
Campaigns are also associated with customer groups. Specify customer groups as within a promotion import/export file, or separately using the customergroup.xsd. The following example is within the promotion.xsd:
<xsd:complexType name="CustomerGroups" mixed="false">
<xsd:sequence>
<xsd:element name="customer-group" type="CustomerGroup" minOccurs="0" maxOccurs="unbounded" />
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="CustomerGroup" mixed="false">
<xsd:attribute name="group-id" type="Generic.NonEmptyString.256" use="required" />
</xsd:complexType>Promotion Classes in B2C Commerce
All promotion classes (product, order, shipping, and bonus) share certain elements that
are defined at the level of the promotion XML element and specified in
promotion.xsd. This topic applies to B2C Commerce.
The differences between the main promotion classes (product, order, and shipping) are represented as an optional choice of promotion class specific rule elements.
<xsd:choice minOccurs="0" maxOccurs="1">
<xsd:element name="product-promotion-rule" type="ProductPromotionRule" />
<xsd:element name="shipping-promotion-rule" type="ShippingPromotionRule" />
<xsd:element name="order-promotion-rule" type="OrderPromotionRule" />
</xsd:choice>Import and export excluded product rules with order promotions
using the excluded-products element.
<!-- order promotions -->
<xsd:complexType name="OrderPromotionRule" mixed="false">
<xsd:sequence>
<!-- new element-->
<xsd:element name="excluded-products" type="ProductSpecification" minOccurs="0" maxOccurs="1" />
<!-- end of new element-->
...
</xsd:sequence>
</xsd:complexType>The qualifying-products element is supported for shipping and order
promotions.
This is a sample of how an order promotions import and export XML appears:
<promotion campaign-id="Demo Campaign" promotion-id="OP_10_500">
<enabled-flag>true</enabled-flag>
<qualifiers>
<customer-groups/>
</qualifiers>
<exclusivity>class</exclusivity>
<name xml:lang="x-default">10% off orders $500 and up</name>
<callout-msg xml:lang="x-default">10% off orders $500 and up.</callout-msg>
<details xml:lang="x-default">10% off orders $500 and up.</details>
<order-promotion-rule>
<!-- excluded product section -->
<excluded-products>
<included-products>
<condition-group>
<category-condition catalog-id="mainproduct-catalog">
<category-id>GiftCerts</category-id>
</category-condition>
</condition-group>
</included-products>
</excluded-products>
<!-- end of excluded product section -->
<discounts condition-type="order-total">
<discount>
<threshold>500.0</threshold>
<percentage>10.0</percentage>
</discount>
</discounts>
</order-promotion-rule>
</promotion>
non-qualifying-products element is deprecated. It is supported on
import but not on export.Exporting Individual Promotions
You can import and export individual promotions within Business Manager. This topic applies to B2C Commerce.
Importing/Exporting Rank and Exclusive Attributes in B2C Commerce
The promotion attributes Rank and Exclusive are supported in the promotion .xsd. This topic applies to B2C Commerce.
- The value list of the system attribute rank can be overwritten by the import/export functionality.
- The value list of the system attribute exclusive is not customizable.
The promotion.xsd schema is now extended as follows:
<!-- shipping promotion-->
<xsd:complexType name="ShippingPromotionRule" mixed="false">
<xsd:sequence>
<xsd:element
name="qualifying-products"
type="ProductSpecification"
minOccurs="0"
maxOccurs="1" />
<!-- new element-->
<xsd:element
name="shipping-methods"
type="PromotedShippingMethods"
minOccurs="1"
maxOccurs="1"/>
<xsd:element
name="discounts"
type="TieredShippingDiscounts" />
<xsd:element
name="max-applications"
type="MaxApplications"
minOccurs="0"
maxOccurs="1" />
</xsd:sequence>
</xsd:complexType>
<xsd:simpleType name="ShippingPromotionConditionType">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="shipment-total" />
<xsd:enumeration value="product-quantity" />
<!-- new element-->
</xsd:restriction>
</xsd:simpleType>
See the Promotion.xsd for further details on the input/output format.
The promotion.xsd supports the free discount type.
The complex type BogoProductDiscount includes the discount type.
<xsd:complexType name="BogoProductDiscount" mixed="false">
<xsd:sequence>
<xsd:element
name="threshold"
type="Threshold"
minOccurs="1"
maxOccurs="1" />
<xsd:choice minOccurs="1" maxOccurs="1">
<xsd:element
name="fixed-price"
type="Amount" />
<xsd:element
name="percentage"
type="Percentage" />
<xsd:element
name="amount"
type="Amount" />
<xsd:element
name="free"
type="EmptyElement"/>
<!-- new element -->
</xsd:choice>
<xsd:element
name="eligible-quantity"
type="Quantity"
minOccurs="1"
maxOccurs="1"/>
</xsd:sequence>
</xsd:complexType>
The complex type TieredShippingDiscount also includes the new discount type.
<xsd:complexType name="TieredShippingDiscount" mixed="false">
<xsd:sequence>
<xsd:element
name="threshold"
type="Threshold"
minOccurs="1"
maxOccurs="1" />
<xsd:choice minOccurs="1" maxOccurs="1">
<xsd:element
name="fixed-price"
type="Amount" />
<xsd:element
name="percentage"
type="Percentage" />
<xsd:element
name="amount"
type="Amount" />
<xsd:element
name="free"
type="EmptyElement"/>
<!-- new element -->
</xsd:choice>
</xsd:sequence>
</xsd:complexType>
The element free is an empty XML element.
Example:
...
<discounts condition-type="product-quantity">
<discount>
<threshold>2.0</threshold>
<free/>
</discount>
</discounts>
Buy X for Total Product Promotion in B2C Commerce
Add a Buy X for Total product promotion to a campaign. This topic applies to B2C Commerce.
The total-discounts element represents the Buy x for total promotion type. The total-discounts element is of type TotalProductDiscount within the existing promotion import or export file.
The following is sample XML:
<promotion campaign-id="Demo Campaign" promotion-id="PP_20OFF">
<enabled-flag>true</enabled-flag>
<qualifiers>
<customer-groups/>
</qualifiers>
<rank>10</rank>
<exclusivity>no</exclusivity>
<name xml:lang="x-default">ShirtsForTotalPrice</name>
<callout-msg
xml:lang="x-default">Buy 2 shirts for $20 total or 3 shirts for $23 total</callout-msg>
<product-promotion-rule>
<!-- only discounted products supported for new promotion type -->
<discounted-products>
<included-products>
<condition-group>
<category-condition catalog-id="product-catalog">
<category-id>Shirts</category-id>
</category-condition>
</condition-group>
</included-products>
</discounted-products>
<total-discounts>
<discount>
<total-fixed-price>20.00</total-fixed-price>
<eligible-quantity>3</eligible-quantity>
</discount>
<discount>
<total-fixed-price>30.00</fixed-price>
<eligible-quantity>5</eligible-quantity>
</discount>
</total-discounts>
</product-promotion-rule>
</promotion>
Customer Group Import and Export for Promotions in B2C Commerce
Customer groups are related to campaigns. Use the
customergroup.xsd schema with promotions. This topic applies to B2C Commerce.
The following sample XML contains a campaign (without actual promotions) that has two customer groups.
<campaign campaign-id="c1">
<description>A sample campaign.</description>
<enabled-flag>true</enabled-flag>
<start-date>2008-01-17T11:04:24</start-date>
<end-date>2008-01-17T11:04:31</end-date>
<customer-groups>
<customer-group group-id="gold-customers" />
<customer-group group-id="platinum-customers" />
</customer-groups>
</campaign>Source Code Import and Export for Promotions in B2C Commerce
Use the sourcecode.xsd schema to import and export for
promotions. This topic applies to B2C Commerce.
The following XML sample outlines a product promotion that is marked as explicitly triggered by two sample source code groups:
<product-promotion promotion-id="simple-product-promo" campaign-id="c1">
...
<sourcecodes>
<sourcecode group-id="sample-group-1" />
<sourcecode group-id="sample-group-2" />
</sourcecodes>
...
</product-promotion>Import of Promotion and Campaign Coupon Assignments in B2C Commerce
The promotion.xsd schema can define how to specify coupons that are
attached to promotions and campaigns. This topic applies to B2C Commerce.
Specific coupon details are defined in the
coupon.xsd schema.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xsd:schema
xmlns="http://www.demandware.com/xml/impex/promotion/2008-01-31"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xml="http://www.w3.org/XML/1998/namespace"
targetNamespace="http://www.demandware.com/xml/impex/promotion/2008-01-31"
elementFormDefault="qualified"
attributeFormDefault="unqualified">
<xsd:import namespace="http://www.w3.org/XML/1998/namespace" schemaLocation="xml.xsd" />
<!-- top-level element -->
<xsd:element name="promotions">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="campaign" type="Campaign" minOccurs="0" maxOccurs="unbounded" />
<xsd:element name="promotion" type="Promotion" minOccurs="0" maxOccurs="unbounded" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>This portion is where you specify the coupons that are parts of a campaign.
<xsd:complexType name="Campaign" mixed="false">
<xsd:sequence>
. . .
<xsd:element name="coupons" type="PromotionCoupons" minOccurs="0" maxOccurs="1" />
. . .
</xsd:sequence>
. . .
</xsd:complexType>This portion is where you specify the coupons that are parts of a promotion.
<xsd:complexType name="Promotion" mixed="false">
<xsd:sequence>
. . .
<xsd:element name="coupons" type="PromotionCoupons" minOccurs="0" maxOccurs="1" />
. . .
</xsd:sequence>
. . .
</xsd:complexType>
. . .This portion is where you define coupons names and IDs.
<xsd:complexType name="PromotionCoupons" mixed="false">
<xsd:sequence>
<xsd:element name="coupon" type="Coupon" minOccurs="0" maxOccurs="unbounded" />
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="Coupon" mixed="false">
<xsd:attribute name="coupon-id" type="Generic.NonEmptyString.256" use="required" />
</xsd:complexType>
. . .This portion is where you define PromotionQualifiers
as a generic type.
<xsd:complexType name="PromotionQualifiers" mixed="false">
<xsd:sequence>
. . .
<xsd:element name="coupons" type="EmptyElement" minOccurs="0" maxOccurs="1" />
</xsd:sequence>
</xsd:complexType>
. . .
</xsd:schema>Product Promotions Import and Export in B2C Commerce
A product promotion rule adds all required information to target certain products with product-specific discount rules. This topic applies to B2C Commerce.
Product Attribute Conditions Import and Export for Promotions in B2C Commerce
The promotion.xsd schema supports product specifications that contain product attribute conditions. This topic applies to B2C Commerce.
Support occurs through these complex types:
- ProductSpecification.ConditionGroup
- ProductSpecification.ProductAttributeFilter
Rank and Exclusivity Import and Export for Promotions in B2C Commerce
Import and export functionality also includes rank and exclusivity attributes. This topic applies to B2C Commerce.
In the following rank and exclusivity example, the PromotionExclusivity setting is mandatory and the xsd element can't be declared as mandatory for technical reasons. B2C Commerce sets a default value of no. for a new promotion in case the element isn't specified.
<xsd:complexType name="Promotion" mixed="false">
<xsd:sequence>
<xsd:element name="enabled-flag" type="xsd:boolean" minOccurs="0" maxOccurs="1" />
<xsd:element name="qualifiers" type="PromotionQualifiers" minOccurs="0" maxOccurs="1" />
<!-- NEW -->
<xsd:element name="rank" type="xsd:int" minOccurs="0" maxOccurs="1" />
<xsd:element name="exclusive" type="PromotionExclusivity" minOccurs="0" maxOccurs="1" />
<xsd:restriction base="xsd:string">
<xsd:enumeration value="no" />
<xsd:enumeration value="class" />
<xsd:enumeration value="global" />
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="PromotionExclusivity">
<xsd:element name="name" type="LocalizedString" minOccurs="0" maxOccurs="unbounded" />
...
</xsd:sequence>
...
</xsd:complexType>The complex types BogoProductDiscount and TieredShippingDiscount contain the discount types.
<xsd:element name="fixed-price" type="Amount" />
<xsd:element name="percentage" type="Percentage" />
<xsd:element name="amount" type="Amount" />
<xsd:element name="free" type="EmptyElement" />Promotion Product Rule Attribute Conditions in B2C Commerce
When importing your catalog, make sure to consider product attributes. This topic applies to B2C Commerce.
Although product attributes can be numeric, the product attribute value is only a string. Strings are the lowest common denominator of all supported attribute types. The import logic validates operator and attribute values based on metadata definitions. These definitions are similar to what exist for custom product attributes in catalog imports.
The following are the validation rules:
- The import logic checks attribute IDs, operators, and values using XML schema validation; they must not be empty strings.
- The attribute-id value is used to retrieve the attribute definition from the Product system object type. If no such attribute definition exists, the condition is skipped.
- If the attribute condition type is not supported, the condition is skipped.
- If an attribute condition supports only one value, and multiple values appear in the XML, a warning is logged and the first value is used.
- Only supported operators are allowed (value types). If the system detects an unsupported operator, it skips the attribute condition.
- If one of multiple values is invalid, the entire attribute condition is skipped.
This table illustrates the validation rules.
| Value Type | Value | Multiple 'attribute-value' elements allowed? | Operator |
|---|---|---|---|
| String | - | yes | - |
| Integer | numeric value without decimal places | no | Operator "less than" is mapped to internal operator "less than or equals". Operator "greater than" is mapped to internal operator "greater than or equals". |
| Boolean | value equals to 'true' or 'false' | no | - |
| Set of String | - | yes | - |
| Set of Integer | numeric value without decimal places | no | Operator "less than" is mapped to internal operator "less than or equals". Operator "greater than" is mapped to internal operator "greater than or equals". |
| Enum of String | one of the values of attribute definition | no | - |
| Enum of Integer | numeric value without decimal places | no | Operator "less than" is mapped to internal operator "less than or equals". Operator "greater than" is mapped to internal operator "greater than or equals". |
This table shows how B2C Commerce evaluates attribute conditions based on their type.
| Value Type | Supported Operators | Multiple Values Supported | Client-side Value Editor | Sample Condition |
|---|---|---|---|---|
| String | equals | yes (OR combined) | text field | product attribute "size" equals "10" |
| Integer | greater than or equals, equals, less than or equals | no | text field | product attribute "size" greater than or equals "4" |
| Boolean | equals | no | combo box | product attribute "enabled" is "true" |
| Set of String | equals | yes (OR combined) | text field | product attribute "Image Aspect Ratio" equals "16:9" |
| Set of Integer | greater than or equals, equals, less than or equals | no | text field | product attribute "width" greater than or equals "3" |
| Enum of String | equals | no | combo box | product attribute "weight" equals "27 lbs" |
| Enum of Integer | greater than or equals, equals, less than or equals | no | combo box | product attribute "width" equals "3" |
Include and Exclude Conditions for Promotions in B2C Commerce
As part of the promotion product rule, import and export any include and exclude conditional qualifiers (including Price Books). This topic applies to B2C Commerce.
In addition, export conditional qualifiers as part of the shipping cost rule (shipping method import).
Order Promotions Import/Export in B2C Commerce
Order promotions are simpler than product promotions, their XML schema a subset of the previously-described product promotions schema. This topic applies to B2C Commerce.
This sample shows a tiered order promotion granting a $10 or $25 discount on the order, provided the merchandise total exceeds $100 or $200, respectively.
<promotion promotion-id="simple-order-promo" campaign-id="c1">
<enabled-flag>true</enabled-flag>
<name xml:lang="x-default">Simple OrderPromotion</name>
<order-promotion-rule>
<discounts>
<discount>
<threshold>100</threshold>
<amount>10</amount>
</discount>
<discount>
<threshold>200</threshold>
<amount>25</amount>
</discount>
</discounts>
</order-promotion-rule>
</promotion>This sample shows a simple order bonus promotion that add a free product (SKU1) to the order if the customer purchased something (order total threshold greater than 0).
<promotion promotion-id="bonus-order-promo" campaign-id="c1">
<enabled-flag>true</enabled-flag>
<name xml:lang="x-default">Bonus OrderPromotion</name>
<order-promotion-rule>
<discounts>
<discount>
<threshold>0</threshold>
<bonus>
<bonus-products>
<product-id>SKU1</product-id>
</bonus-products>
</bonus>
</discount>
</discounts>
</order-promotion-rule>
</promotion>Use the element <payment-methods> and the complex type
PromotedPaymentMethods to create discounts on an order based on payment
method. This example promotion gives a 10% discount to any order that uses
Paypal as the payment method.
<promotion promotion-id="paymentpromo">
<enabled-flag>false</enabled-flag>
<searchable-flag>false</searchable-flag>
<exclusivity>no</exclusivity>
<callout-msg xml:lang="x-default">Use Paypal to receive 10% off your order!</callout-msg>
<details xml:lang="x-default">10% for paypal</details>
<order-promotion-rule>
<payment-methods>
<method-id>PayPal</method-id>
</payment-methods>
<discount-only-qualifying-products>true</discount-only-qualifying-products>
<discounts condition-type="order-total">
<discount>
<threshold>0.0</threshold>
<percentage>10.0</percentage>
</discount>
</discounts>
</order-promotion-rule>
</promotion>Shipping Promotions Import/Export in B2C Commerce
The import/export format for shipping promotions is similar to that of order promotions. The major difference is that shipping promotions let you define discounted shipping methods. This topic applies to B2C Commerce.
This sample XML shows a tiered shipping promotion granting a 50% or 100% discount on selected shipping methods provided the qualifying products total exceeds $50 or $100 respectively.
<promotion promotion-id="tiered-shipping-promo" campaign-id="c1">
<enabled-flag>true</enabled-flag>
<name xml:lang="x-default">Tiered ShippingPromotion</name>
<shipping-promotion-rule>
<shipping-methods>
<method-id>ups-ground</method-id>
<method-id>ups-air</method-id>
</shipping-methods>
<discounts condition-type="shipment-total">
<discount>
<threshold>50</threshold>
<percentage>50</percentage>
</discount>
<discount>
<threshold>100</threshold>
<fixed-price>0</fixed-price>
</discount>
</discounts>
</shipping-promotion-rule>
</promotion>The promotion in the above example has a condition-type of
"shipment-total". Alternatively, a shipping promotion can specify a condition-type of
"product-quantity". Such promotions require that a certain quantity of qualifying products be
in the shipment in order for the discount to apply. The XML for this type of promotion
includes a <qualifying-products> section before the
<discounted-methods>.
In general, a shipping promotion with a condition-type of "product-quantity" requires that a specified number of qualifying products and no excluded products be in the shipment. However, whether or not a shipping promotions permits or prohibits excluded products is configurable. The optional element <prohibit-excluded-products> which accepts values of true or false can be included in the promotion XML to control this behavior. If you omit the element for a newly imported promotion, B2C Commerce prohibits excluded products.
See the schema promotion.xsd for details.
Promotion Schedule Import/Export in B2C Commerce
All promotion classes support an optional promotion schedule that controls when a promotion is active. This topic applies to B2C Commerce.
The following is a snippet from the Promotion Schedule section of the promotion.xsd.
<xsd:complexType name="PromotionSchedule" mixed="false">
<xsd:sequence>
<xsd:element name="start-date" type="xsd:dateTime" minOccurs="0" maxOccurs="1" />
<xsd:element name="end-date" type="xsd:dateTime" minOccurs="0" maxOccurs="1" />
<xsd:element name="recurrence" type="PromotionSchedule.Recurrence" minOccurs="0" maxOccurs="1" />
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="PromotionSchedule.Recurrence" mixed="false">
<xsd:sequence>
<xsd:element name="day-of-week" type="PromotionSchedule.DayOfWeek" minOccurs="0" maxOccurs="1" />
<xsd:element name="time-of-day" type="PromotionSchedule.TimeOfDay" minOccurs="0" maxOccurs="1" />
</xsd:sequence>
</xsd:complexType>This sample XML contains a schedule for the month of January (see start end date) that limits promotions to Monday, Friday, Saturday and Sunday between 9 AM and 7 PM (on those days).
<schedule>
<start-date>2008-01-01T13:32:01</start-date>
<end-date>2008-01-31T13:33:30</end-date>
<recurrence>
<day-of-week>
<weekday>Monday</weekday>
<weekday>Friday</weekday>
<weekday>Saturday</weekday>
<weekday>Sunday</weekday>
</day-of-week>
<time-of-day>
<time-from>09:00:00</time-from>
<time-to>19:00:00</time-to>
</time-of-day>
</recurrence>
</schedule>