Reference - Product Price and Pricelist Data XML Import Specification

1 Introduction

This document describes the product-price-definition and product-price-list import XML format. The product-price-list-entry is linked to a product by the product SKU (stock keeping unit).

The price list defines a specific product price, price range, or a percentage of the product list price. The percentage price calculation requires the product list price being stored with the product during the product import.

The XSD schema (bc_pricing.xsd) validates the XML content of product-price-definition and product-price-list data.

See Impex - Price documentation for further information.

Note

product-price-definition is no longer used in ICM. However, since it is still included in the xsd schema file, it will be described here even though it is obsolete.



2 XSD Schema

Here you see the content of the current xsd schema file. Its details are described in the chapters below.

bc_pricing.xsd
<?xml version="1.0" encoding="UTF-8"?>
<!-- Minor schema version is increased from 6.2.2 to 6.3 since an optional element 'customers' is added -->
<!-- Minor schema version of bc_pricing/impex is increased from 7.0 to 7.1 since an optional attribute 'import-mode' is added for ProductPriceListEntry type -->
<xsd:schema targetNamespace="http://www.intershop.com/xml/ns/enfinity/7.1/bc_pricing/impex" xmlns:dt="http://www.intershop.com/xml/ns/enfinity/6.5/core/impex-dt" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:jxb="http://java.sun.com/xml/ns/jaxb" xmlns="http://www.intershop.com/xml/ns/enfinity/7.1/bc_pricing/impex" elementFormDefault="qualified" jxb:version="1.0">
	<xsd:include schemaLocation="core.xsd"/>
	<xsd:import namespace="http://www.w3.org/XML/1998/namespace" schemaLocation="xml.xsd"/>
	<xsd:import namespace="http://www.intershop.com/xml/ns/enfinity/6.5/core/impex-dt" schemaLocation="dt.xsd"/>
	
	<xsd:element name="enfinity">
		<xsd:complexType>
			<xsd:choice minOccurs="0" maxOccurs="unbounded">
				<xsd:element ref="product-price-definition"/>
				<xsd:element ref="product-price-list"/>
			</xsd:choice>
			<xsd:attributeGroup ref="documentVersion"/>
		</xsd:complexType>
		<xsd:key name="product-price-list">
			<xsd:selector xpath="product-price-list"/>
			<xsd:field xpath="@id"/>
			<xsd:field xpath="@priceType"/>
		</xsd:key>
	</xsd:element>
	<xsd:element name="product-price-definition" type="ProductPriceDefinitionType"/>
	<xsd:element name="product-price-list" type="ProductPriceListType">
		<xsd:key name="price-list-scale">
			<xsd:selector xpath="price-list-scale"/>
			<xsd:field xpath="@currency"/>
		</xsd:key>
		<xsd:key name="product-price-list-entry">
			<xsd:selector xpath="product-price-list-entry"/>
			<xsd:field xpath="@sku"/>
		</xsd:key>
	</xsd:element>
	<xsd:complexType name="ProductPriceDefinitionType">
		<xsd:sequence>
			<xsd:element name="price-scale-table" maxOccurs="unbounded">
				<xsd:complexType>
					<xsd:complexContent>
						<xsd:restriction base="PriceScaleTable">
							<xsd:all>
								<xsd:element name="valid-from" type="simpleType.DateTime" minOccurs="0"/>
								<xsd:element name="valid-to" type="simpleType.DateTime" minOccurs="0"/>
								<xsd:element name="customer-segment" type="CustomerSegment" minOccurs="0"/>
								<xsd:element name="price-scale-entries" type="PriceScaleEntries"/>
								<xsd:element name="custom-attributes" type="complexType.CustomAttributes" minOccurs="0"/>
							</xsd:all>
							<xsd:attribute name="currency" type="simpleType.Generic.Currency.Mnemonic" use="required"/>
							<xsd:attribute name="type-code" type="xsd:positiveInteger" use="prohibited"/>
						</xsd:restriction>
					</xsd:complexContent>
				</xsd:complexType>
			</xsd:element>
		</xsd:sequence>
		<xsd:attribute name="sku" type="simpleType.Generic.String.256" use="required"/>
		<xsd:attribute name="type-code" type="xsd:positiveInteger" default="1"/>
		<xsd:attribute name="rule" type="simpleType.Generic.String.256"/>
		<xsd:attribute name="import-mode" type="simpleType.ImportMode"/>
	</xsd:complexType>
	<xsd:complexType name="ProductPriceListType">
		<xsd:sequence>
			<xsd:element name="display-name" type="complexType.Generic.Attribute.String" minOccurs="0" maxOccurs="unbounded"/>
			<xsd:element name="description" type="complexType.Generic.Attribute.String" minOccurs="0" maxOccurs="unbounded"/>
			<xsd:element name="enabled" type="xsd:boolean" minOccurs="0"/>
			<xsd:element name="priority" type="xsd:double" minOccurs="0"/>
			<xsd:element name="valid-from" type="simpleType.DateTime" minOccurs="0"/>
			<xsd:element name="valid-to" type="simpleType.DateTime" minOccurs="0"/>
			<xsd:element name="target-groups" type="TargetGroups" minOccurs="0" maxOccurs="1"/>
			<xsd:choice>
				<xsd:sequence>
					<xsd:element name="price-list-scale" type="PriceListScale" maxOccurs="unbounded">
						<xsd:key name="relative-price-entry-key">
							<xsd:selector xpath="relative-price-entry"/>
							<xsd:field xpath="@quantity"/>
						</xsd:key>
					</xsd:element>
					<xsd:element name="products" type="Products" minOccurs="0">
						<xsd:key name="product-key">
							<xsd:selector xpath="product"/>
							<xsd:field xpath="@sku"/>
						</xsd:key>
					</xsd:element>
				</xsd:sequence>
				<xsd:element name="product-price-list-entry" type="ProductPriceListEntry" minOccurs="0" maxOccurs="unbounded"/>
			</xsd:choice>
			<xsd:element name="custom-attributes" type="complexType.CustomAttributes" minOccurs="0"/>
		</xsd:sequence>
		<xsd:attribute name="id" type="simpleType.Generic.String.256" use="required"/>
		<xsd:attribute name="priceType" type="simpleType.Generic.String.256" use="required"/>
		<xsd:attribute name="import-mode" type="simpleType.ImportMode"/>
	</xsd:complexType>
	<xsd:complexType name="ProductPriceListEntry">
		<xsd:sequence>
			<xsd:element name="price-scale-table" maxOccurs="unbounded">
				<xsd:complexType>
					<xsd:complexContent>
						<xsd:restriction base="PriceScaleTable">
							<xsd:all>
								<xsd:element name="valid-from" type="simpleType.DateTime" minOccurs="0"/>
								<xsd:element name="valid-to" type="simpleType.DateTime" minOccurs="0"/>
								<xsd:element name="customer-segment" type="CustomerSegment" minOccurs="0"/>
								<xsd:element name="price-scale-entries" type="PriceScaleEntries"/>
								<xsd:element name="custom-attributes" type="complexType.CustomAttributes" minOccurs="0"/>
							</xsd:all>
							<xsd:attribute name="currency" type="simpleType.Generic.Currency.Mnemonic" use="required"/>
							<xsd:attribute name="type-code" type="xsd:positiveInteger" use="required"/>
						</xsd:restriction>
					</xsd:complexContent>
				</xsd:complexType>
			</xsd:element>
		</xsd:sequence>
		<xsd:attribute name="sku" type="simpleType.Generic.String.256" use="required"/>
		<xsd:attribute name="import-mode" type="simpleType.ImportMode"/>
	</xsd:complexType>
	<xsd:complexType name="CustomerSegments">
		<xsd:sequence>
			<xsd:element name="customer-segment" type="CustomerSegment" minOccurs="0" maxOccurs="unbounded"/>
		</xsd:sequence>
	</xsd:complexType>
	<xsd:complexType name="Customers">
		<xsd:sequence>
			<xsd:element name="customer" type="Customer" minOccurs="1" maxOccurs="unbounded"/>
		</xsd:sequence>
	</xsd:complexType>
	<xsd:complexType name="PriceListScale">
		<xsd:sequence>
			<xsd:element ref="relative-price-entry" maxOccurs="unbounded"/>
		</xsd:sequence>
		<xsd:attribute name="currency" type="simpleType.Generic.Currency.Mnemonic" use="required"/>
	</xsd:complexType>
	<xsd:complexType name="Products">
		<xsd:sequence>
			<xsd:element name="product" maxOccurs="unbounded">
				<xsd:complexType>
					<xsd:attribute name="sku" type="simpleType.Generic.String.256" use="required"/>
				</xsd:complexType>
			</xsd:element>
		</xsd:sequence>
	</xsd:complexType>
	<xsd:complexType name="CustomerSegment">
		<xsd:attribute name="id" type="simpleType.Generic.String.256" use="required"/>
		<xsd:attribute name="repository-id" type="simpleType.Generic.String.256" use="required"/>
	</xsd:complexType>
	<xsd:complexType name="Customer">
		<xsd:attribute name="id" type="simpleType.Generic.String.256" use="required"/>
	</xsd:complexType>
	<xsd:complexType name="PriceScaleTable">
		<xsd:all>
			<xsd:element name="valid-from" type="simpleType.DateTime" minOccurs="0"/>
			<xsd:element name="valid-to" type="simpleType.DateTime" minOccurs="0"/>
			<xsd:element name="customer-segment" type="CustomerSegment" minOccurs="0"/>
			<xsd:element name="price-scale-entries" type="PriceScaleEntries">
				<xsd:key name="price-scale-entry-key">
					<xsd:selector xpath="price-scale-entry|fixed-price-entry|relative-price-entry"/>
					<xsd:field xpath="@quantity"/>
				</xsd:key>
			</xsd:element>
			<xsd:element name="custom-attributes" type="complexType.CustomAttributes" minOccurs="0"/>
		</xsd:all>
		<xsd:attribute name="currency" type="simpleType.Generic.Currency.Mnemonic" use="required"/>
		<xsd:attribute name="type-code" type="xsd:positiveInteger"/>
	</xsd:complexType>
	<xsd:complexType name="PriceScaleEntries">
		<xsd:sequence>
			<xsd:element ref="price-scale-entry" minOccurs="0" maxOccurs="unbounded"/>
		</xsd:sequence>
	</xsd:complexType>
	<xsd:complexType name="PriceScaleEntryType">
		<xsd:all>
			<xsd:element name="value" type="xsd:decimal"/>
			<xsd:element name="custom-attributes" type="complexType.CustomAttributes" minOccurs="0"/>
		</xsd:all>
		<xsd:attribute name="quantity" type="xsd:decimal" use="required"/>
		<xsd:attribute name="unit" type="simpleType.Generic.Quantity.Unit" default="n/a"/>
		<xsd:attribute name="net-price" type="xsd:boolean" default="false"/>
		<xsd:attribute name="tax-rate" type="xsd:decimal"/>
		<xsd:attribute name="type-code" type="xsd:positiveInteger"/>
	</xsd:complexType>
	<xsd:complexType name="TargetGroups" mixed="false">
        <xsd:all>
            <xsd:element name="customer-segments" type="CustomerSegments" minOccurs="0" maxOccurs="1">
                <xsd:unique name="uniqueCustomerSegment">
                    <xsd:selector xpath="./customer-segment"/>
                    <xsd:field xpath="@id"/>
                    <xsd:field xpath="@repository-id"/>
                </xsd:unique>
            </xsd:element>
            <xsd:element name="customers" type="Customers" minOccurs="0" maxOccurs="1">
                <xsd:unique name="uniqueCustomer">
                    <xsd:selector xpath="./customer"/>
                    <xsd:field xpath="@id"/>
                </xsd:unique>
            </xsd:element>
        </xsd:all>
    </xsd:complexType>
	<xsd:element name="product-price-list-entry" type="ProductPriceListEntry"/>
	<xsd:element name="price-scale-entry" type="PriceScaleEntryType"/>
	<xsd:element name="fixed-price-entry" substitutionGroup="price-scale-entry">
		<xsd:complexType>
			<xsd:complexContent>
				<xsd:restriction base="PriceScaleEntryType">
					<xsd:all>
						<xsd:element name="value" type="xsd:decimal"/>
						<xsd:element name="custom-attributes" type="complexType.CustomAttributes" minOccurs="0"/>
					</xsd:all>
					<xsd:attribute name="type-code" type="xsd:positiveInteger" use="prohibited"/>
				</xsd:restriction>
			</xsd:complexContent>
		</xsd:complexType>
	</xsd:element>
	<xsd:element name="relative-price-entry" substitutionGroup="price-scale-entry">
		<xsd:complexType>
			<xsd:complexContent>
				<xsd:restriction base="PriceScaleEntryType">
					<xsd:all>
						<xsd:element name="value" type="xsd:decimal"/>
						<xsd:element name="custom-attributes" type="complexType.CustomAttributes" minOccurs="0"/>
					</xsd:all>
					<xsd:attribute name="type-code" type="xsd:positiveInteger" use="prohibited"/>
				</xsd:restriction>
			</xsd:complexContent>
		</xsd:complexType>
	</xsd:element>
</xsd:schema>

3 XML Definition Product

3.1 Root Elements

3.1.1 enfinity Element

This is the root element definition of enfinity element. It shows what kind of objects are valid inside this element declaration.

The enfinity element can contain from zero to unlimited product-price-definition data elements OR from zero to unlimited product-price-list data elements.

Having both product-price-definition and product-price-list data elements in one import file is not supported. Details for both these elements are described below.

enfinity
<xsd:element name="enfinity">
	<xsd:complexType>
		<xsd:choice minOccurs="0" maxOccurs="unbounded">
			<xsd:element ref="product-price-definition"/>
			<xsd:element ref="product-price-list"/>
		</xsd:choice>
		<xsd:attributeGroup ref="documentVersion"/>
	</xsd:complexType>
	<xsd:key name="product-price-list">
		<xsd:selector xpath="product-price-list"/>
		<xsd:field xpath="@id"/>
		<xsd:field xpath="@priceType"/>
	</xsd:key>
</xsd:element>

3.1.2 ProductPriceList Element

In this reference just the product-price-list object is described.

This element has the type complexType ProductPriceListType. The properties (content elements) of this type are described in section Elements of complexType ProductPriceListType.

product-price-list
<xsd:element name="product-price-list" type="ProductPriceListType">
	<xsd:key name="price-list-scale">
		<xsd:selector xpath="price-list-scale"/>
		<xsd:field xpath="@currency"/>
	</xsd:key>
	<xsd:key name="product-price-list-entry">
		<xsd:selector xpath="product-price-list-entry"/>
		<xsd:field xpath="@sku"/>
	</xsd:key>
</xsd:element>

3.1.3 ProductPriceDefinition Element (obsolete)

In this reference just the product-price-definition object is described. It is used for scaled prices without pricelists that are used in procurement. (obsolete)

This element has the type complexType ProductPriceDefinitionType. The properties (content elements) of this type are described in section Elements of complexType ProductPriceDefinitionType.

product-price-definition
<xsd:element name="product-price-definition" type="ProductPriceDefinitionType"/>

3.2 Elements of complexType ProductPriceDefinitionType (obsolete)

In this reference the details of the sub element price-scale-table of element product-price-definition are described.

  • The product-price-definition has several attributes: sku, type-code, rule and import-mode.
Attribute nameAttribute type / optionalDescriptionDB-tableRelates to
skuString.256 - requiredReference to the productPriceDefinitionProductBinding.ProductSKUProduct.SKU
type-code

Positive int (default=1) - optional

PriceDefinitionProductBinding.TypeCode

PriceScaleTable.TypeCode


ruleString.256 - optionalThe ID of a rule. The type of the rule is not fixed. It may be one of any rule engine.PriceDefinitionProductBinding.RuleID

import-mode

Optional

If not set, uses global setting

Used to define an individual import mode for this object

Options are: INITIAL, IGNORE, UPDATE, REPLACE, OMIT, DELETE



  • The product-price-definition must have at least one price-scale-table sub-element.
  • The price-scale-table sub-element used here is based on type PriceScaleTable but is used with local restrictions described below.


ProductPriceDefinitionType
<xsd:complexType name="ProductPriceDefinitionType">
	<xsd:sequence>
		<xsd:element name="price-scale-table" maxOccurs="unbounded">
			<xsd:complexType>
				<xsd:complexContent>
					<xsd:restriction base="PriceScaleTable">
						<xsd:all>
							<xsd:element name="valid-from" type="simpleType.DateTime" minOccurs="0"/>
							<xsd:element name="valid-to" type="simpleType.DateTime" minOccurs="0"/>
							<xsd:element name="customer-segment" type="CustomerSegment" minOccurs="0"/>
							<xsd:element name="price-scale-entries" type="PriceScaleEntries"/>
							<xsd:element name="custom-attributes" type="complexType.CustomAttributes" minOccurs="0"/>
						</xsd:all>
						<xsd:attribute name="currency" type="simpleType.Generic.Currency.Mnemonic" use="required"/>
						<xsd:attribute name="type-code" type="xsd:positiveInteger" use="prohibited"/>
					</xsd:restriction>
				</xsd:complexContent>
			</xsd:complexType>
		</xsd:element>
	</xsd:sequence>
	<xsd:attribute name="sku" type="simpleType.Generic.String.256" use="required"/>
	<xsd:attribute name="type-code" type="xsd:positiveInteger" default="1"/>
	<xsd:attribute name="rule" type="simpleType.Generic.String.256"/>
	<xsd:attribute name="import-mode" type="simpleType.ImportMode"/>
</xsd:complexType>

3.2.1 price-scale-table Element

The xml tag price-scale-table type is PriceScaleTable. It has multiple optional elements and local restrictions which are described here.

NameElement typeDescription

valid-from

valid-to

Date

  • optional

Defines the time frame in which the price-scale-table data is used.

  • The pattern of both is locale-specific.
  • The name of the pattern is impexDateTimePattern.
  • It is deployed in the regional settings.
  • The value for the locale 'en-US' is 'MM/dd/yy hh:mm:ss a'.
  • The value for the locale 'de-DE' is 'dd.MM.yyyy HH:mm:ss'.

customer-segment

CustomerSegment

  • optional
  • Allows one assignment to user groups. See further details in section customer-segment.

There are one required and one prohibited attribute.

NameAttribute typeDescriptionDB-table
currency

Currency.Mnemonic

  • required
The currency code of the price to be imported (e.g. 'USD', 'EUR', or 'GBP').PriceScaleTable.CurrencyCode
type-code

positiveInteger

  • prohibited
This parameter is prohibited here. Contrary to its use in element product-price-list.



There are two complex sub elements:

3.2.2 complexType PriceScaleTable (for ProductPriceDefinitionType)

The price-scale-table element is of complexType PriceScaleTable.

  • Its elements and attributes used for ProductPriceDefinitionType have restrictions.
  • This describes the complexType PriceScaleTable itself, but only if it differs from the price-scale-table element described in section price-scale-table Element.

Only one required sub-element price-scale-entries of type PriceScaleEntries and its sub-elements are new compared to the price-scale-table element. See price_scale_entries for detailed decription.

These sub-elements underneath price-scale-entries are three variations of complexType PriceScaleEntryType with name: price-scale-entry, fixed-price-entry and relative-price-entry.

PriceScaleTable
<xsd:complexType name="PriceScaleTable">
	<xsd:all>
		<xsd:element name="valid-from" type="simpleType.DateTime" minOccurs="0"/>
		<xsd:element name="valid-to" type="simpleType.DateTime" minOccurs="0"/>
		<xsd:element name="customer-segment" type="CustomerSegment" minOccurs="0"/>
		<xsd:element name="price-scale-entries" type="PriceScaleEntries">
			<xsd:key name="price-scale-entry-key">
				<xsd:selector xpath="price-scale-entry|fixed-price-entry|relative-price-entry"/>
				<xsd:field xpath="@quantity"/>
			</xsd:key>
		</xsd:element>
		<xsd:element name="custom-attributes" type="complexType.CustomAttributes" minOccurs="0"/>
	</xsd:all>
	<xsd:attribute name="currency" type="simpleType.Generic.Currency.Mnemonic" use="required"/>
	<xsd:attribute name="type-code" type="xsd:positiveInteger"/>
</xsd:complexType>

3.2.3 customer-segment

The element customer-segment has two required attributes: id and repository-id.

  • The element customer-segment represents assignments of price scale tables to user groups. Each price scale table may be assigned to one user group.
  • They are used to assign user groups to this price-scale-table. So they have to exist in the system for the assignment to work.
  • Example: <customer-segment id="Everyone" repository-id="inSPIRED-inTRONICS-Anonymous"/>

Details for users and user groups can be found in Reference - Customer Data XML Import Specification.

NameAttribute typeDescriptionDB-tableRelates to
id

String.256

  • required
The user-group idPriceScaleTable.UserGroupIDUserGroup.ID
type-code

String.28

  • required
The user-group domainID


PriceScaleTable.UserGroupDomainID

UserGroup.DomainID

(Domain.UUID)

CustomerSegment
<xsd:complexType name="CustomerSegment">
	<xsd:attribute name="id" type="simpleType.Generic.String.256" use="required"/>
	<xsd:attribute name="repository-id" type="simpleType.Generic.String.256" use="required"/>
</xsd:complexType>

3.2.4 price-scale-entries

The element price-scale-entries of the complex type PriceScaleEntries has one optional element price-scale-entry which in turn is of type PriceScaleEntryType.

The element price-scale-entries is a container for elements that represents price scales.

  • The elements fixed-price-entry and relative-price-entry are members of a substitution group that can occur at all places where price-scale-entry elements are allowed.
  • They are restrictions of price-scale-entry. The elements fixed-price-entry and relative-price-entry differ from price-scale-entry in that they must not have any type-code attribute.
    • As type-code attribute for elements fixed-price-entry and relative-price-entry, type-code '1' is used implicitly.
  • For further details see PriceScaleEntryType.

Element fixed-price-entry and relative-price-entry contain product prices:

  • Element fixed-price-entry defines a fixed price for a specific product (e.g.: 50 USD).
    • It basically replaces the product list price if it exists. So the product list price is not required for this kind of price.
  • Element relative-price-entry defines a product price relative to the list price and currency of that product (e.g.: 2%).
    • This means a relative price works only if a list price exists for the product. Otherwise the defined percentage cannot be calculated as product price.
PriceScaleEntries
<xsd:complexType name="PriceScaleEntries">
	<xsd:sequence>
		<xsd:element ref="price-scale-entry" minOccurs="0" maxOccurs="unbounded"/>
	</xsd:sequence>
</xsd:complexType>

<xsd:element name="price-scale-entry" type="PriceScaleEntryType"/>
<xsd:element name="fixed-price-entry" substitutionGroup="price-scale-entry">
	<xsd:complexType>
		<xsd:complexContent>
			<xsd:restriction base="PriceScaleEntryType">
				<xsd:all>
					<xsd:element name="value" type="xsd:decimal"/>
					<xsd:element name="custom-attributes" type="complexType.CustomAttributes" minOccurs="0"/>
				</xsd:all>
				<xsd:attribute name="type-code" type="xsd:positiveInteger" use="prohibited"/>
			</xsd:restriction>
		</xsd:complexContent>
	</xsd:complexType>
</xsd:element>
<xsd:element name="relative-price-entry" substitutionGroup="price-scale-entry">
	<xsd:complexType>
		<xsd:complexContent>
			<xsd:restriction base="PriceScaleEntryType">
				<xsd:all>
					<xsd:element name="value" type="xsd:decimal"/>
					<xsd:element name="custom-attributes" type="complexType.CustomAttributes" minOccurs="0"/>
				</xsd:all>
				<xsd:attribute name="type-code" type="xsd:positiveInteger" use="prohibited"/>
			</xsd:restriction>
		</xsd:complexContent>
	</xsd:complexType>
</xsd:element>

3.2.5 PriceScaleEntryType

The element price-scale-entry of type PriceScaleEntryType has two sub-elements and several attributes.

The price-scale-entry elements contain the actual price settings which are used to find the price for a specific product.

  • The product-price-list-entry defines the relation to a product via its SKU.
  • The price-scale-table element below defines the currency and the price type.
  • The elements with type PriceScaleEntryType: fixed-price-entry, relative-price-entry and price-scale-entry contain the actual price value.

The required element value contains the decimal price value. Depending on the PriceScaleEntryType type it represents either a percentage (relative-price-entry) or a fixed price (fixed-price-entry).

The attributes and their description:

Attribute (required)TypeDescriptionDB-table

quantity

(true)

decimal
  • The quantity for which the price is used
  • Multiple entry elements define a range
PriceScaleEntry.QuantityLevelValue
unitString.256The quantity unitPriceScaleEntry.QuantityLevelUnit
net-pricebooleanIf true it is a gross price; false a net-price (default)PriceScaleEntry.NetPriceFlag
tax-ratedecimalThe tax ratePriceScaleEntry.TaxRate
type-codepositive Integer

Specifies the type of the price scale:

Numeric valueType name / descriptionID used in code
1Price scale of type amountPRICE_SCALE_ENTRY_TYPE_AMOUNT
2Price scale of type percentagePRICE_SCALE_ENTRY_TYPE_PERCENTAGE
3Quantity-triggered surchargePRICE_SCALE_ENTRY_TYPE_QUANTITY_TRIGGERED_SURCHARGE
4Value-triggered surchargePRICE_SCALE_ENTRY_TYPE_VALUE_TRIGGERED_SURCHARGE
  • See interface PriceScaleEntryConstants.java for more details

For the element price-scale-entry the type-code can be set individually.

For the elements fixed-price-entry and relative-price-entry the type-code in the XML is prohibited and implicitly set to '1'.

PriceScaleEntry.TypeCode

The sub-elements and their description:

ElementRequiredTypeDescription
valuetruedecimal

The value of the price-entry

TypeDescriptionDB-table
fixed-price-entry

Is stored as SingleBasePrice

The code is the currency attribute from the parent price-scale-table element

PriceScaleEntry.SingleBasePriceCode

PriceScaleEntry.SingleBasePriceValue

relative-price-entryIs stored as a percentagePriceScaleEntry.Percentage
price-scale-entryThe scaled price valuePriceScaleEntry
custom-attributesfalsecomplexType. CustomAttributescomplexType.CustomAttributes contains one ore more custom-attribute elements.
PriceScaleEntryType
<xsd:complexType name="PriceScaleEntryType">
	<xsd:all>
		<xsd:element name="value" type="xsd:decimal"/>
		<xsd:element name="custom-attributes" type="complexType.CustomAttributes" minOccurs="0"/>
	</xsd:all>
	<xsd:attribute name="quantity" type="xsd:decimal" use="required"/>
	<xsd:attribute name="unit" type="simpleType.Generic.Quantity.Unit" default="n/a"/>
	<xsd:attribute name="net-price" type="xsd:boolean" default="false"/>
	<xsd:attribute name="tax-rate" type="xsd:decimal"/>
	<xsd:attribute name="type-code" type="xsd:positiveInteger"/>
</xsd:complexType>

3.3 Elements of complexType ProductPriceListType

This section describes ProductPriceListType in more detail.

3.3.1 ProductPriceListType

The xml tag product-price-list type is ProductPriceListType. It has multiple optional elements which are described here.

  • The elements' functions are as their names suggest (display-name, description, enabled, priority, valid-from, valid-to, target-groups).
  • The elements enabled, valid-fromand valid-to define if the product-price-list data are actually used as part of the product price finding process.
  • The element priority defines the hierarchy in which this product-price-list data is handled in the product price finding process.
  • With the target-groups the price list can be assigned to and used for a specific user (customer) or a group of users (customer-segment). See section target-groups for further details.

There are two required and one optional attributes.

  • The required id is the name given when the price list is created.
  • The required priceType is the type (usually: Sale Price) of the price list selectable in a drop-down box.
  • The third, but optional attribute is the import-mode. This import-mode setting is only responsible for this one product-price-list element.
    • It can differ from the globally selected import mode. (See import mode description for information about the available import modes.)

The xml tag product-price-list allows three sub-elements.

  • These elements are: price-list-scale elements, products elements and product-price-list-entry elements.
  • A choice of either price-list-scale elements or a products element is allowed, and zero to unlimited product-price-list-entry elements.
  • A description of all the sub-elements can be found in section price-list-scale.
ProductPriceListType
<xsd:complexType name="ProductPriceListType">
	<xsd:sequence>
		<xsd:element name="display-name" type="complexType.Generic.Attribute.String" minOccurs="0" maxOccurs="unbounded"/>
		<xsd:element name="description" type="complexType.Generic.Attribute.String" minOccurs="0" maxOccurs="unbounded"/>
		<xsd:element name="enabled" type="xsd:boolean" minOccurs="0"/>
		<xsd:element name="priority" type="xsd:double" minOccurs="0"/>
		<xsd:element name="valid-from" type="simpleType.DateTime" minOccurs="0"/>
		<xsd:element name="valid-to" type="simpleType.DateTime" minOccurs="0"/>
		<xsd:element name="target-groups" type="TargetGroups" minOccurs="0" maxOccurs="1"/>
		<xsd:choice>
			<xsd:sequence>
				<xsd:element name="price-list-scale" type="PriceListScale" maxOccurs="unbounded">
					<xsd:key name="relative-price-entry-key">
						<xsd:selector xpath="relative-price-entry"/>
						<xsd:field xpath="@quantity"/>
					</xsd:key>
				</xsd:element>
				<xsd:element name="products" type="Products" minOccurs="0">
					<xsd:key name="product-key">
						<xsd:selector xpath="product"/>
						<xsd:field xpath="@sku"/>
					</xsd:key>
				</xsd:element>
			</xsd:sequence>
			<xsd:element name="product-price-list-entry" type="ProductPriceListEntry" minOccurs="0" maxOccurs="unbounded"/>
		</xsd:choice>
		<xsd:element name="custom-attributes" type="complexType.CustomAttributes" minOccurs="0"/>
	</xsd:sequence>
	<xsd:attribute name="id" type="simpleType.Generic.String.256" use="required"/>
	<xsd:attribute name="priceType" type="simpleType.Generic.String.256" use="required"/>
	<xsd:attribute name="import-mode" type="simpleType.ImportMode"/>
</xsd:complexType>

3.3.2 target-groups

The target-groups of a price list and its sub elements are used to assign the price list to a specific user (customer) or a group of users (customer-segment).

The assignment of users and user groups makes the price list available for the assigned user and/or user group and is part of the product price finding process.

The element customer-segments and its sub-element customer-segment assign groups of users to the price list.

  • Allowed is zero to only one customer-segments element, but it can contain from zero to unlimited customer-segment elements.
    • The customer-segment element has an id and a repository-id attribute.
    • The combination of both attributes must be unique.
    • During the import both attributes are used to assign already existing user groups to the price list.
  • The element customers and its sub element customer is used to assign specific users to the price list.
    • Allowed is zero to only one customers element, but it can contain from one to unlimited customer elements.
      • The customer element has an id attribute.
      • This attribute must be unique.
      • During the import the id attribute is used to assign an already existing user to the price list.
TargetGroups
<xsd:complexType name="TargetGroups" mixed="false">
	<xsd:all>
		<xsd:element name="customer-segments" type="CustomerSegments" minOccurs="0" maxOccurs="1">
			<xsd:unique name="uniqueCustomerSegment">
				<xsd:selector xpath="./customer-segment"/>
				<xsd:field xpath="@id"/>
				<xsd:field xpath="@repository-id"/>
			</xsd:unique>
		</xsd:element>
		<xsd:element name="customers" type="Customers" minOccurs="0" maxOccurs="1">
			<xsd:unique name="uniqueCustomer">
				<xsd:selector xpath="./customer"/>
				<xsd:field xpath="@id"/>
			</xsd:unique>
		</xsd:element>
	</xsd:all>
</xsd:complexType>

3.3.2.1 customer-segments

The element customer-segments is of type CustomerSegments:

  • It is optional and can have multiple customer-segment sub-element entries.

The element customer-segment has two required attributes:

  • Attribute id and repository-id combined are a unique identifier to a user group in the ICM.
  • They are used to assign user groups to this price-scale-table. So they have to exist in the system for the assignment to work.
  • Example: <customer-segment id="Everyone" repository-id="inSPIRED-inTRONICS-Anonymous"/>
NameTypeDescriptionDB-tableRelates to
idString.256Both combined are a unique identifier to a user group in the ICM.PriceListUserGroupAssignment.userGroupIDUserGroup.ID
repository-idString.256
PriceListUserGroupAssignment.userGroupDomainIDUserGroup.DomainID
CustomerSegments
<xsd:complexType name="CustomerSegments">
	<xsd:sequence>
		<xsd:element name="customer-segment" type="CustomerSegment" minOccurs="0" maxOccurs="unbounded"/>
	</xsd:sequence>
</xsd:complexType>

<xsd:complexType name="CustomerSegment">
	<xsd:attribute name="id" type="simpleType.Generic.String.256" use="required"/>
	<xsd:attribute name="repository-id" type="simpleType.Generic.String.256" use="required"/>
</xsd:complexType>

3.3.2.2 customers

The element customers is of type Customers:

  • It is optional and can have multiple customer sub-element entries.

The element customer has one required attribute:

  • Attribute id is a unique identifier to a customer in the ICM.
  • The attribute is used to assign users to the price-scale-table. So it has to exist in the system for the assignment to work.
  • Example: <customer-segment id="Patricia"/>
NameTypeDescriptionRelates to
idString.256A unique identifier to a user in the ICMUserGroupUserAssignment.UserID
Customers
<xsd:complexType name="Customers">
	<xsd:sequence>
		<xsd:element name="customer" type="Customer" minOccurs="1" maxOccurs="unbounded"/>
	</xsd:sequence>
</xsd:complexType>

<xsd:complexType name="Customer">
	<xsd:attribute name="id" type="simpleType.Generic.String.256" use="required"/>
</xsd:complexType>

3.3.3 price-list-scale

The element price-list-scale is a container for relative price entries. A price list scale is a means to provide some business logic to the price list import. It specifies that for each of its relative price entries one price scale entry has to be created for each product in the importing domain. This results in one entry in the database tables PriceScaleTableAssignment and PriceScaleTable each, corresponding to the price list scale itself, and it leads to multiple entries in the table PriceScaleEntry corresponding to relative price entries contained in the price list scale. Each price list scale of a price list must have a unique value for its currency attribute.

PriceListScale
<xsd:complexType name="PriceListScale">
	<xsd:sequence>
		<xsd:element ref="relative-price-entry" maxOccurs="unbounded"/>
	</xsd:sequence>
	<xsd:attribute name="currency" type="simpleType.Generic.Currency.Mnemonic" use="required"/>
</xsd:complexType>

3.3.3.1 relative-price-entry

The element relative-price-entry is described in section price-scale-entries.

relative-price-entry
<xsd:element name="relative-price-entry" substitutionGroup="price-scale-entry">
	<xsd:complexType>
		<xsd:complexContent>
			<xsd:restriction base="PriceScaleEntryType">
				<xsd:all>
					<xsd:element name="value" type="xsd:decimal"/>
					<xsd:element name="custom-attributes" type="complexType.CustomAttributes" minOccurs="0"/>
				</xsd:all>
				<xsd:attribute name="type-code" type="xsd:positiveInteger" use="prohibited"/>
			</xsd:restriction>
		</xsd:complexContent>
	</xsd:complexType>
</xsd:element>

The complexType PriceScaleEntryType is described in section PriceScaleEntryType.

PriceScaleEntryType
<xsd:complexType name="PriceScaleEntryType">
	<xsd:all>
		<xsd:element name="value" type="xsd:decimal"/>
		<xsd:element name="custom-attributes" type="complexType.CustomAttributes" minOccurs="0"/>
	</xsd:all>
	<xsd:attribute name="quantity" type="xsd:decimal" use="required"/>
	<xsd:attribute name="unit" type="simpleType.Generic.Quantity.Unit" default="n/a"/>
	<xsd:attribute name="net-price" type="xsd:boolean" default="false"/>
	<xsd:attribute name="tax-rate" type="xsd:decimal"/>
	<xsd:attribute name="type-code" type="xsd:positiveInteger"/>
</xsd:complexType>

3.3.4 Products

The optional element Products is a container for product elements. It is used to narrow the set of products that should be part of the price list.

The element product models an assignment from the enclosing price list to a product in the importing domain which has to be a product repository (price lists and all their related objects reside in product repositories).

The product is identified by the value of the attribute sku in combination with the importing domain. The value of the attribute sku must be unique in comparison to the other product elements of the enclosing price list element.

Products
<xsd:complexType name="Products">
	<xsd:sequence>
		<xsd:element name="product" maxOccurs="unbounded">
			<xsd:complexType>
				<xsd:attribute name="sku" type="simpleType.Generic.String.256" use="required"/>
			</xsd:complexType>
		</xsd:element>
	</xsd:sequence>
</xsd:complexType>

3.3.5 product-price-list-entry

The xml tag product-price-list-entry type is ProductPriceListEntry. It has multiple elements and attributes which are described in this section.

There are two attributes: import-mode and sku.

  • The required attribute sku relates to the product the price is used for.
  • The optional attribute import-mode is setting the import mode for this one product-price-list-entry element.
    • It can differ from the globally selected import mode. (See import mode description for information about the available import modes.)

There exists at least one and an unlimited number of the sub-element price-scale-table. Its details are described in the following.

ProductPriceListEntry
<xsd:complexType name="ProductPriceListEntry">
	<xsd:sequence>
		<xsd:element name="price-scale-table" maxOccurs="unbounded">
			<xsd:complexType>
				<xsd:complexContent>
					<xsd:restriction base="PriceScaleTable">
						<xsd:all>
							<xsd:element name="valid-from" type="simpleType.DateTime" minOccurs="0"/>
							<xsd:element name="valid-to" type="simpleType.DateTime" minOccurs="0"/>
							<xsd:element name="customer-segment" type="CustomerSegment" minOccurs="0"/>
							<xsd:element name="price-scale-entries" type="PriceScaleEntries"/>
							<xsd:element name="custom-attributes" type="complexType.CustomAttributes" minOccurs="0"/>
						</xsd:all>
						<xsd:attribute name="currency" type="simpleType.Generic.Currency.Mnemonic" use="required"/>
						<xsd:attribute name="type-code" type="xsd:positiveInteger" use="required"/>
					</xsd:restriction>
				</xsd:complexContent>
			</xsd:complexType>
		</xsd:element>
	</xsd:sequence>
	<xsd:attribute name="sku" type="simpleType.Generic.String.256" use="required"/>
	<xsd:attribute name="import-mode" type="simpleType.ImportMode"/>
</xsd:complexType>

3.3.5.1 price-scale-table

The xml tag price-scale-table type is PriceScaleTable. It has multiple optional elements which are described in this section.

  • The optional elements valid-from and valid-to define the time frame in which the price-scale-table data is used.
  • The optional element customer-segment allows one assignment to user groups. See the section customer-segment for further details.

There is one required and one optional attribute:

There are two complex sub elements:

PriceScaleTable
<xsd:complexType name="PriceScaleTable">
	<xsd:all>
		<xsd:element name="valid-from" type="simpleType.DateTime" minOccurs="0"/>
		<xsd:element name="valid-to" type="simpleType.DateTime" minOccurs="0"/>
		<xsd:element name="customer-segment" type="CustomerSegment" minOccurs="0"/>
		<xsd:element name="price-scale-entries" type="PriceScaleEntries">
			<xsd:key name="price-scale-entry-key">
				<xsd:selector xpath="price-scale-entry|fixed-price-entry|relative-price-entry"/>
				<xsd:field xpath="@quantity"/>
			</xsd:key>
		</xsd:element>
		<xsd:element name="custom-attributes" type="complexType.CustomAttributes" minOccurs="0"/>
	</xsd:all>
	<xsd:attribute name="currency" type="simpleType.Generic.Currency.Mnemonic" use="required"/>
	<xsd:attribute name="type-code" type="xsd:positiveInteger"/>
</xsd:complexType>

The complexType CustomerSegment is described in section customer-segment.

CustomerSegment
<xsd:complexType name="CustomerSegment">
	<xsd:attribute name="id" type="simpleType.Generic.String.256" use="required"/>
	<xsd:attribute name="repository-id" type="simpleType.Generic.String.256" use="required"/>
</xsd:complexType>

The complexType PriceScaleEntries is described in section price-scale-entries.

PriceScaleEntries
<xsd:complexType name="PriceScaleEntries">
	<xsd:sequence>
		<xsd:element ref="price-scale-entry" minOccurs="0" maxOccurs="unbounded"/>
	</xsd:sequence>
</xsd:complexType>

<xsd:element name="price-scale-entry" type="PriceScaleEntryType"/>
<xsd:element name="fixed-price-entry" substitutionGroup="price-scale-entry">
	<xsd:complexType>
		<xsd:complexContent>
			<xsd:restriction base="PriceScaleEntryType">
				<xsd:all>
					<xsd:element name="value" type="xsd:decimal"/>
					<xsd:element name="custom-attributes" type="complexType.CustomAttributes" minOccurs="0"/>
				</xsd:all>
				<xsd:attribute name="type-code" type="xsd:positiveInteger" use="prohibited"/>
			</xsd:restriction>
		</xsd:complexContent>
	</xsd:complexType>
</xsd:element>
<xsd:element name="relative-price-entry" substitutionGroup="price-scale-entry">
	<xsd:complexType>
		<xsd:complexContent>
			<xsd:restriction base="PriceScaleEntryType">
				<xsd:all>
					<xsd:element name="value" type="xsd:decimal"/>
					<xsd:element name="custom-attributes" type="complexType.CustomAttributes" minOccurs="0"/>
				</xsd:all>
				<xsd:attribute name="type-code" type="xsd:positiveInteger" use="prohibited"/>
			</xsd:restriction>
		</xsd:complexContent>
	</xsd:complexType>
</xsd:element>

The complexType PriceScaleEntryType is described in section PriceScaleEntryType.

PriceScaleEntryType
<xsd:complexType name="PriceScaleEntryType">
	<xsd:all>
		<xsd:element name="value" type="xsd:decimal"/>
		<xsd:element name="custom-attributes" type="complexType.CustomAttributes" minOccurs="0"/>
	</xsd:all>
	<xsd:attribute name="quantity" type="xsd:decimal" use="required"/>
	<xsd:attribute name="unit" type="simpleType.Generic.Quantity.Unit" default="n/a"/>
	<xsd:attribute name="net-price" type="xsd:boolean" default="false"/>
	<xsd:attribute name="tax-rate" type="xsd:decimal"/>
	<xsd:attribute name="type-code" type="xsd:positiveInteger"/>
</xsd:complexType>

3.4 type-code - Types Currently Available

The attribute type-code is used in several places within the xsd. The currently available values are listed in this section.

The values from 0 to 99 are reserved. The type codes of custom price definitions have to be greater than 99.

See interface PriceDefinitionConstants.java for more details.

ID used in codeType name / descriptionNumeric value
SCALED_PRODUCT_LIST_PRICESsimple list price based price scale definition

1 (=default)

SCALED_PRODUCT_GROUP_PRICESuser group specific price scale definition2
CONTRACT_LIST_PRICEScontract list price definition3
CONTRACT_SCALED_LIST_PRICEScontract list price based price scale definitions4
SMALL_SCALE_SURCHARGEused to identify a small scale surcharge5

...      room for future standard type-codes...
CUSTOM_PRICE_DEFINITIONthe base for any custom price definition100

...      room for custom code type-codes


4 Sample XML

4.1 product-price-list

product-price-list
<product-price-list id="AllCustomersPriceList" priceType="ES_SalePrice">
	<display-name xml:lang="en-US">Customers Price List</display-name>
	<description xml:lang="en-US">The Price List for 2 users and 2 user-groups.</description>
	<enabled>true</enabled>
	<priority>3</priority>
    <valid-from>2020-08-13T00:00:00+02:00</valid-from>
	<valid-to>2020-08-20T00:00:00+02:00</valid-to>
	<target-groups>
		<customers>
			<customer id="Patricia"/>
			<customer id="Schneider"/>
		</customers>
		<customer-segments>
			<customer-segment id="CG_PremiumConsumers" repository-id="inSPIRED-inTRONICS-Anonymous" />
			<customer-segment id="IG_SMBCustomers" repository-id="inSPIRED-inTRONICS-Anonymous" />
		</customer-segments>
	</target-groups>
	<product-price-list-entry sku="4810740">
		<price-scale-table currency="USD" type-code="1">
			<price-scale-entries>
				<relative-price-entry quantity="1.0" unit="">
					<value>5.0</value>
				</relative-price-entry>
			</price-scale-entries>
		</price-scale-table>
		<price-scale-table currency="EUR" type-code="1">
			<price-scale-entries>
				<relative-price-entry quantity="1.0" unit="">
					<value>5.0</value>
				</relative-price-entry>
			</price-scale-entries>
		</price-scale-table>			
	</product-price-list-entry>
    <product-price-list-entry sku="3740178">
		<price-scale-table currency="USD" type-code="1">
			<valid-from>2020-08-17T00:00:00+02:00</valid-from>
			<valid-to>2020-08-18T00:00:00+02:00</valid-to>
			<price-scale-entries>
				<fixed-price-entry quantity="3.0" unit="">
					<value>5.0</value>
				</fixed-price-entry>
			</price-scale-entries>
		</price-scale-table>
		<price-scale-table currency="USD" type-code="1">
			<price-scale-entries>
				<fixed-price-entry quantity="10.0" unit="">
					<value>2.0</value>
				</fixed-price-entry>
			</price-scale-entries>
		</price-scale-table>
	</product-price-list-entry>
</product-price-list>

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Tickets