Understanding the contract model in WebSphere Commerce V5

This article explains when you can use a particular pricing or product term and condition, and the effect of the term and condition to a customer in WebSphere Commerce 5.4, 5.5 and 5.6.

Share:

Howard Borenstein (borenst@ca.ibm.com), Software Engineer, IBM Canada

Howard Borenstein is a software developer at the IBM Toronto Lab in Toronto, Ontario, Canada. He is the lead developer of the Business Relationship Management component of WebSphere Commerce.



11 February 2004

Introduction

IBM® WebSphere® Commerce 5.4 and 5.5 contracts entitle customers to purchase designated products in a store at a specified price under specific conditions. Contract terms and conditions are rules that cover the actual implementation of the contract. The terms and conditions cover product pricing, returns and refunds, payment, shipping, and order approval. This article helps you understand the different pricing and product terms and conditions available in WebSphere Commerce. Examples illustrate how the terms and conditions interact with each other, and help you decide which terms and conditions are appropriate for your customer's contracts. Instructions are provided on where to set up the terms and conditions using the WebSphere Commerce Accelerator and the correct syntax for the XML contract import.


Overview of products and pricing

A contract contains terms and conditions that define how a contract is implemented for a customer organization. In Figure 1, these terms and conditions reference business policies. A business policy is a set of rules followed by a business for a particular business process. Business policies facilitate the creation of contract terms and conditions by predefining some standard parameters applicable to the term and condition. When creating a term and condition, you are presented with a list of relevant business policies available in the store, and you can choose the appropriate business policy. The product terms and conditions refer to product set business policies for categories that are often used in contracts. Creating product set business policies allows the same category to be shared in multiple contracts. The pricing terms and conditions refer to price business policies that contain the list of prices for the products in the catalog.

Figure 1. Contract overview
Contract overview

What is for sale and at what price

To sell a product in a contract, the product must have a price. Therefore, the list of products for sale under a contract is determined from price lists (also known as trading position containers) specified in the contract. There is one price list for the entire master catalog that is commonly used in pricing terms and conditions. However, you can use multiple price lists. For example, you can have a manufacturer's suggested retail price MSRP list based price list and a cost based price list. Some contracts can specify a mark down on the MSRP list prices, and other contracts can specify a mark up on the cost prices.

There are two ways to specify the price offered to a customer: percentage and fixed. A percentage price is a percentage change to the list price of the product. If the list price changes, the price available to the customer changes. You can offer the percentage change to the list price for the entire contents of a price list, or on a subset of the price list. Fixed pricing specifies the exact price charged for the product under the contract. The price does not change when the product's list price changes.

If you do not want to sell the entire content of a price list, then you need to specify the product inclusion and exclusion terms and conditions. If you do not want to sell a category or product specified in a price list, then specify that product in an excluded product set (more on product sets later in this article). If you only want to sell a subset of a price list, then specify the categories and products in an included product set. The important aspect of specifying product set inclusion is that only those categories and products are for sale in the contract. Once you specify the product inclusion, only those products listed are for sale. If a product is contained in both inclusion and exclusion product sets, then the exclusion specification takes precedence. When you exclude a product in a contract, it overrides any other inclusion specification.

When a customer is browsing the store, if there are product inclusion terms, then the customer sees all the products specified in the inclusion product sets, except for any products specified in any exclusion product sets. If there are no inclusion terms, then they see all the products specified in the price lists specified in the pricing terms, except for any products specified in any exclusion product sets.

The price offered to the customer is based on two criteria: precedence and lowest price. A price list has a precedence value. If a price is found for a product in multiple price lists, then the price is taken from the price list with the higher precedence. If the prices lists have identical precedence, then the lower price is offered to the customer.

Standard and custom product sets

Product sets contain a list of products to which a contract term and condition can refer for price adjustments or product inclusion/exclusion. There are two types of product sets: standard and custom. With a standard product set, the list of products is kept synchronized with any catalog updates. If a new category or product is added to or removed from the master catalog, the applicable product set will be updated with the changes. A customer purchasing under a contract that is using standard product sets will be entitled to the products in the current version of the catalog. Standard product sets often are creating for all the products in a category. You can create a standard product set for a category by selecting the "To be used in contracts" checkbox in the Product Management category tool. A custom product set creates a fixed list of products at the time a contract is published. Any changes to the master catalog are not made to the custom product set, and the customer is only entitled to the list of products that existed at the time the contract was published.

Pricing rules

If a customer is entitled to purchase a product from a contract, the contract returns a price for that product. A contract can have several percentage and fixed pricing terms and conditions, and each term and condition may offer a price for the same product. In addition, a contract can have the Catalog Filtering term and condition that can specify several pricing terms in one term and condition. You can use pricing rules to determine the price offered for a product, and to resolve ambiguities if multiple terms and conditions return a price for the same product.

The pricing rules are:

  1. A fixed price has the most important precedence because the fixed price list is given a higher precedence than the master catalog price list.
  2. If a product is under several percentage pricing terms and conditions, then the lowest price calculated from each term and condition is the price offered for the product.
  3. If a product is under the PriceTCMasterCatalogWithFiltering term and condition, then the lowest explicit pricing condition is the price offered for the product. An explicit pricing condition means that a category or product has been set with a specific price adjustment. The lowest explicit pricing condition is the condition specified at the lowest level in the catalog tree.
  4. If a product is under multiple PriceTCMasterCatalogWithFiltering terms and conditions, one from a Base contract and one from a Customer contract, then rule 2 applies and the lowest price from each term and condition is the price offered for the product.

Scenario 1

Term 1 - 10% off shirts
Term 2 - $30.00 for shirt SKU-123

T-shirt SKU-123 has a price reduction of 10% from term 1, and a fixed price of $30.00 from term 2. From rule 1, a fixed price takes precedence, so the price for SKU-123 is $30.00

Scenario 2

Term 1 - 10% off shirts
Term 2 - 20% off T-shirts

A T-shirt has a price reduction of 10% from term 1, and a reduction of 20% from term 2. From rule 2, a price is retrieved from multiple term and condition. The lowest price is the price offered for the product. The price for T-shirt SKU-123 is reduced by 20%.

Scenario 3

Term 1 (PriceTCMasterCatalogWithFiltering term) - 10% off shirts, 20% off T-shirts

From rule 3, a T-shirt has a price reduction of 20% because that is the lowest explicit setting for a man's shirt. A dress shirt has a price reduction of 10% because that is the lowest explicit setting for a shirt.

Scenario 4

Term 1 (PriceTCMasterCatalogWithFiltering term) - 20% off shirts, 10% off T-shirts

From rule 3, a T-shirt has a price reduction of 10% because that is the lowest explicit setting for a T-shirt. The explicit setting of 10% at a lower level in the tree takes precedence over the 20% setting at a higher level.

Scenario 5

Term 1 (PriceTCMasterCatalogWithFiltering term - Base contract) - 20% off T-shirts
Term 2 (PriceTCMasterCatalogWithFiltering term - Customer contract) - 10% off shirts

A T-shirt has a price reduction of 20% off from term 1, and a price reduction of 10% from term 2. From rule 4, there are multiple PriceTCMasterCatalogWithFiltering terms and conditions, therefore the lowest price is the price offered for the product. The price for T-shirt SKU-123 is reduced by 20%. The Customer contract cannot override a higher adjustment set by the Base contract.

Product rules

The following rules determine if a product may be purchased under a contract:

  1. If there are one or more product exclusion terms and condition, then those product may not be purchased under the contract.
  2. If there is at least one product inclusion term and condition, then the customer may order any product in the inclusion terms (there must be a price from a pricing term) and provided the product is not excluded by rule 1.
  3. If there are no product exclusion terms and conditions, then the customer may order any product for which there is a price in a price list, and which is not excluded by rule 1.

Scenario 1

Term 1 - 10% off shirts
Term 2 - Include only shirts

From rule 2, there is a product inclusion term, so only shirts are for sale and they are 10% off.

Scenario 2

Term 1 - 10% off shirts
Term 2 - Include only shirts
Term 3 - Exclude shirt SKU-123

From rule 2, there is a product inclusion term, so only shirts are for sale, and from rule 1, there is a product exclusion, so SKU-123 is not for sale. All shirts, except SKU-123, are for sale and are 10% off.


Terms and conditions

This section lists the available pricing terms and conditions. A summary is provided for each term and condition. You can create the location of this term and condition in the Commerce Accelerator, and the XML format of this term and condition. You can create a contract by using the Commerce Accelerator, or by creating and importing an XML document. The XML fragments provided here are based on the new XSD format introduced in WebSphere Commerce 5.5.

Pricing

PriceTCMasterCatalogWithOptionalAdjustment

Use this term and condition when you want to provide the entire master catalog for sale under the contract, and if you want to provide a percentage markup or markdown on the prices in the master catalog price list. You can restrict products from being sold by using a product exclusion term and condition.

To setup the term and condition, go to Contract Notebook - Products and Prices -> Percentage Pricing -> Add - Apply an adjustment on the entire master catalog.

If you are in the XML import, here's the XML fragment:

<!-- the entire catalog is available at 10% off -->
<PriceTCMasterCatalogWithOptionalAdjustment>
 <PriceAdjustment signedPercentage="-10.0"/>
 </PriceTCMasterCatalogWithOptionalAdjustment>

PriceTCPriceListWithOptionalAdjustment

Use this term and condition to offer a percentage markup and markdown on the prices in the specified price list.

In the Commerce Accelerator, it's not available.

If you are in the XML import, here's the XML fragment:

<!-- the products in the MSRP price list are available at 20% off -->
 <PriceTCPriceListWithOptionalAdjustment>
   <PricePolicyRef policyName="MSRP Price List">
      <StoreRef name="SampleStore">
          <Owner>                   
     <OrganizationRef distinguishName="o=SampleStoreOrganization,
          o=Root Organization"/>
   </Owner>
  </StoreRef>
 </PricePolicyRef>
<PriceAdjustment signedPercentage="-20.0"/>
</PriceTCPriceListWithOptionalAdjustment>

PriceTCPriceListWithSelectiveAdjustment

Use this term and condition to offer a percentage markup and markdown on the prices in the specified price list for a subset of the products. You can specify the subset to be a category or a specific list of products. The product set is either a standard or a custom product set. The example below uses a standard product set. An implication of using this term is that the entire contents of the price list are available for sale, and the contents of the subset product set are given a percentage price change.

In the Commerce Accelerator, there are two options:

  • Contract Notebook - Products and Prices -> Percentage Pricing -> Add - Apply an adjustment on the following contract optimized categories (standard product sets).
  • Contract Notebook - Products and Prices -> Percentage Pricing -> Add - Apply an adjustment on the following categories and products (custom product sets).

If you are in the XML import, here's the XML fragment:

<!-- Shirts are available at 20% off -->
<PriceTCPriceListWithSelectiveAdjustment>
 <PricePolicyRef policyName="MasterCatalogPriceList">
  <StoreRef name="SampleStore">
    <Owner>
    <OrganizationRef distinguishName="o=SampleStoreOrganization,
           o=Root Organization"/>
     </Owner>
 </StoreRef>
</PricePolicyRef>
 <PriceAdjustmentOnProductSet>
  <ProductSetInclusion>
  <ProductSetPolicyRef policyName="Shirts">
    <StoreRef name="SampleStore">
     <Owner>
       <OrganizationRef distinguishName="o=SampleStoreOrganization,  
            o=Root Organization"/>
     </Owner>
     </StoreRef>
    </ProductSetPolicyRef>
   </ProductSetInclusion>
  <PriceAdjustment signedPercentage="-20.0"/>
 </PriceAdjustmentOnProductSet>
</PriceTCPriceListWithSelectiveAdjustment>

PriceTCCustomPriceList

To specify a specific fixed price for a product, specify the list of products and the offer price in this term and condition. Any changes to the master catalog price are not offered to the customer.

In the Commerce Accelerator, go to Contract Notebook - Products and Prices -> Fixed Pricing -> Add.

If you are in the XML import, here's the XML fragment:

<!-- the specified products are available at the specified fixed prices -->
  <PriceTCCustomPriceList>
  <PriceList description="" name="SampleCustomerCustomPriceList" 
      precedence="100" type="C">
   <Offer published="Published" quantityUnit="C62" skuNumber="SKU-123">
     <OfferPrice>
     <MonetaryAmount currency="CAD" value="5"/>
    </OfferPrice>
    <Owner>
      <OrganizationRef distinguishName="o=SampleStoreOrganization,
          o=Root Organization"/>
    </Owner>
   </Offer>
   <Offer published="Published" quantityUnit="C62" skuNumber="SKU-456">
     <OfferPrice>
     <MonetaryAmount currency="CAD" value="6"/>
    </OfferPrice>
     <Owner>
     <OrganizationRef distinguishName="o=SampleStoreOrganization,
         o=Root Organization"/>
     </Owner>
   </Offer>
   <Owner>
     <OrganizationRef distinguishName="o=SampleStoreOrganization,
         o=Root Organization"/>
   </Owner>
  </PriceList>
 </PriceTCCustomPriceList>

PriceTCMasterCatalogWithFiltering

This term and condition is a new term introduced in WebSphere Commerce 5.5. You can use this term with the Catalog Filter tool to reduce the number of terms and conditions required to create a contract. With this one term and condition, you can specify all the product inclusion, exclusion, and pricing adjustments for a contract. In the CatalogSelection element, you can specify if the entire catalog from the price list is for sale, and at what adjustment. If the entire catalog is marked for sale, then you can restrict certain categories and products from being sold by adding Exclude type Selection elements. You can specify further price adjustments on a subset of the catalog with Include Selection elements.

If the entire catalog is not for sale, the list of products for sale is determined by the Include Selection elements. The precedence attribute refers to which level in the catalog tree the category and product appears. Fixed pricing is the only pricing specification not supported (use the PriceTCCustomPriceList). Currently, only standard product sets are created for selected categories (use PriceTCPriceListWithSelectiveAdjustment, ProductSetTCCustomInclusion, and ProductSetTCCustomExclusion for custom product sets).

In the Commerce Accelerator, go to Catalog Filter.

If you are in the XML import, here's the XML fragment:

<!-- the entire catalog is available at 15% off, pants 50% off, SKU-123 55% off,
  do not sell Shirts -->
 <PriceTCMasterCatalogWithFiltering>
  <PricePolicyRef policyName="MasterCatalogPriceList">
    <StoreRef name="SampleStore">
    <Owner>
      <OrganizationRef distinguishName="o=SampleStoreOrganization,
          o=Root Organization"/>
    </Owner>
   </StoreRef>
  </PricePolicyRef>
  <CatalogSelection includeEntireCatalog="true" signedPercentage="-15">
    <CatalogRef name="SampleStore Catalog">
    <Owner>
      <OrganizationRef distinguishName="o=SampleStoreOrganization,
          o=Root Organization"/>
    </Owner>
   </CatalogRef>
   <ProductSetOwner>
     <OrganizationRef distinguishName="o=SampleStoreOrganization, 
         o=Root Organization"/>
   </ProductSetOwner>
   <Selection type="Include" synchronize="true">
    <Adjustment signedPercentage="-50" precedence="1"/>
    <CatalogGroupRef groupIdentifier="Pants">
      <Owner>
      <OrganizationRef distinguishName="o=SampleStoreOrganization,
          o=Root Organization"/>
      </Owner>
   </CatalogGroupRef>
   </Selection>
   <Selection type="Include" synchronize="true">
    <Adjustment signedPercentage="-55" precedence="99999"/> 
    <CatalogEntryRef partNumber="SKU-123">
      <Owner>
      <OrganizationRef distinguishName="o=SampleStoreOrganization, 
          o=Root Organization"/>
      </Owner>
     </CatalogEntryRef>
   </Selection>
   <Selection type="Exclude" synchronize="true">
     <Adjustment signedPercentage="0" precedence="1"/>
     <CatalogGroupRef groupIdentifier="Shirts">     
     <Owner>
       <OrganizationRef distinguishName="o=SampleStoreOrganization,
           o=Root Organization"/>
     </Owner>
    </CatalogGroupRef>
   </Selection>
  </CatalogSelection>
 </PriceTCMasterCatalogWithFiltering>

You can specify multiple pricing terms and conditions in a contract, and there must be a least one pricing term.


Products

Products that are for sale under a contract are implicitly defined in the pricing terms and conditions. The following are the available product inclusion and exclusion terms and conditions that override the product rules defined in the pricing terms and conditions.

ProductSetTCExclusion

This term excludes all the products in the standard product set from being sold under the contract.

In the Commerce Accelerator, go to Contract Notebook - Selection Constraints -> Exclude for sale the following categories and products in this contract, Available exclusions.

If you are in the XML import, here's the XML fragment:

<!-- Pants are not for sale -->
<ProductSetTCExclusion>
  <ProductSetPolicyRef policyName="Pants">
   <StoreRef name="SampleStore">
     <Owner>
     <OrganizationRef distinguishName="o=SampleStoreOrganization,
         o=Root Organization"/>
     </Owner>
    </StoreRef>
   </ProductSetPolicyRef>
 </ProductSetTCExclusion>

ProductSetTCInclusion

This term allows all the products in the standard product set to be sold under the contract.

In the Commerce Accelerator, go to Contract Notebook - Selection Constraints -> Include for sale only the following categories and products in this contract, Available inclusions.

If you are in the XML import, here's the XML fragment:

<!-- only Shirts are for sale -->
<ProductSetTCInclusion>
  <ProductSetPolicyRef policyName="Shirts">
    <StoreRef name="SampleStore">
    <Owner>
      <OrganizationRef distinguishName="o=SampleStoreOrganization,
          o=Root Organization"/>
      </Owner>
    </StoreRef>
   </ProductSetPolicyRef>
 </ProductSetTCInclusion>

ProductSetTCCustomExclusion

This term excludes all the products in the custom product set from being sold under the contract.

In the Commerce Accelerator, go to Contract Notebook - Selection Constraints -> Exclude for sale the following categories and products in this contract, Excluded categories and products.

If you are in the XML import, here's the XML fragment:

<!-- Pants and SKU-123 are not for sale -->
<ProductSetTCCustomExclusion>
  <ProductSet catalogIdentifier="SampleStore Catalog" description="" 
     name="SampleCustomerProductSet1">
   <PSExclusionList>
     <CatalogEntryRef partNumber="SKU-123">
     <Owner>
       <OrganizationRef distinguishName="o=SampleStoreOrganization,
           o=Root Organization"/>
     </Owner>
    </CatalogEntryRef>
    <CatalogGroupRef groupIdentifier="Pants">
     <Owner>
     <OrganizationRef distinguishName="o=SampleStoreOrganization,
         o=Root Organization"/>
     </Owner>
    </CatalogGroupRef>
   </PSExclusionList>
    <ProductSetOwner>    
    <OrganizationRef distinguishName="o=SampleStoreOrganization,
       o=Root Organization"/>
   </ProductSetOwner>
   <CatalogOwner>
     <OrganizationRef distinguishName="o=SampleStoreOrganization,
         o=Root Organization"/>
   </CatalogOwner>

ProductSetTCCustomInclusion

This term allows all the products in the custom product set to be sold under the contract.

In the Commerce Accelerator, go to Contract Notebook - Selection Constraints -> Include for sale only the following categories and products in this contract, Included categories and products.

If you are in the XML import, here's the XML fragment:

<!-- only Shirts and SKU-456 are for sale -->
<ProductSetTCCustomInclusion>
  <ProductSet catalogIdentifier="SampleStore Catalog" description="" 
      name="SampleCustomerProductSet2">
   <PSInclusionList>
     <CatalogEntryRef partNumber="SKU-456">
     <Owner>
       <OrganizationRef distinguishName="o=SampleStoreOrganization,
           o=Root Organization"/>
     </Owner>
    </CatalogEntryRef>
    <CatalogGroupRef groupIdentifier="Shirts">
      <Owner>
      <OrganizationRef distinguishName="o=SampleStoreOrganization,
          o=Root Organization"/>
      </Owner>
   </CatalogGroupRef>
   </PSInclusionList>
   <ProductSetOwner>
     <OrganizationRef distinguishName="o=SampleStoreOrganization,
        o=Root Organization"/>
   </ProductSetOwner>
   <CatalogOwner>
     <OrganizationRef distinguishName="o=SampleStoreOrganization,
         o=Root Organization"/>
   </CatalogOwner>
  </ProductSet>
</ProductSetTCCustomInclusion>

You can specify multiple product inclusion and exclusion terms. Once you specify a product inclusion term, only those products referred to by those inclusion terms are for sale under the contract.


Conclusion

This article explained when you can use a particular term and condition, and the interaction between the term and condition. By using the appropriate set of pricing and product terms and conditions, you can specify the conditions under which a customer can purchase from an online store. The Catalog Filter tool and its associated term and condition reduce the number of terms and conditions you need to create in a contract and prevent ambiguities between the terms and conditions.

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=14576
ArticleTitle=Understanding the contract model in WebSphere Commerce V5
publish-date=02112004