HCL Commerce Enterprise

Case Study: HCL Commerce contract modeling

HCL Commerce contracts are the foundation for determining what customers can purchase in an online store, and at what price. The contracts functions are flexible in that it can support many types of e-commerce business models and their complex business requirements. This flexibility is powerful, and an optimal contract design can minimize the amount of effort that is required to manage business accounts and contracts. As well, an optimal design can minimize the amount of system resources that are required and thus enhance system performance.

Fundamental concepts

After you understand these concepts, you can combine them to form an optimal design for a commerce site.

A contract defines the terms and conditions under which a customer shops while they are in a commerce site. These terms modify the customer's shopping experience, including what products the customer can purchase, what prices they are entitled to, and what shipping and payment options they might use. To enable a contract to be accessed by customers in a store, the contract is deployed to the store.
Terms and Conditions
The most commonly used term and condition is the Catalog Filter term. This term is the basis for setting entitled products and prices. The Catalog Filter term has the following settings:
Entire catalog is selected
The customer can purchase everything in the master catalog, except for any excluded categories or products.
Entire catalog is not selected
The customer can purchase the categories and products that are included, except for any excluded categories or products.
Customer is entitled to multiple Catalog Filter terms, and any term excludes a category or product
The customer cannot purchase that category or product under the applicable contract.
Percentage adjustment set for the entire catalog, specific categories, and specific products
Within one term, the lowest level setting in the catalog hierarchy takes the pricing precedence.
Fixed prices can be set on specific products
Creates a custom price list, which has a higher pricing precedence than the store's master price list. Therefore, the fixed price overrides any price from the master price list.

If a customer is entitled to multiple Catalog Filter terms, the customer is also entitled to the lowest price from the set of terms. The price list precedence also helps determine which price term takes priority.

In some business scenarios, the pricing and product terms for a customer are maintained in an external system. These terms need to be imported into HCL Commerce to provide the correct entitlement in the online store. In this situation, it is preferable to have the contract refer to a price list and a product set by using a corresponding Price business policy and a Product Set business policy. The contract uses the appropriate Price and Product Set terms and conditions to refer the respective business policy.

Management Center supports a catalog filter that works differently than the HCL Commerce Accelerator catalog filter described here. For example, the Management Center catalog filter is used for setting product entitlement terms only; for pricing terms, you can create a price rule in Management Center and assign it to a contract. To learn more about the Management Center catalog filtering and pricing features you can use in contracts, see Catalog Filter and Pricing tool.

The commerce system determines who is allowed to use a contract from the 'Buyer' participants that are associated with a contract. Buyer participants can be an Organization or a Member Group, and a contract might have multiple Buyer participants. A contract can also have an empty Buyer participant, which means that all customers are allowed to use that contract.

When a customer logs on to site, they are entitled to:

  • All contracts in which their immediate parent organization, or any parent organization is a Buyer participant. The immediate parent organization can be the one to which the member is directly assigned, or an organization in which they have the OrganizationParticipant role.
  • All contracts in which a member group they belong to is a Buyer participant.
  • All contracts in which there is an empty Buyer participant (unless this is restricted by their business account; more on that later).

If a customer is a guest shopper, or is not logged in, then they are only entitled to the contracts with empty Buyer participants.

Customer contracts
A customer contract is one that has a Buyer participant. This is distinguished from a base contract, which does not have any Buyer participants. (Having an empty Buyer participant is different from not having any Buyer participant.) When the HCL Commerce system determines a customer's entitled contracts, it is from the set of customer contracts that are deployed in the store.
Base contracts
A base contract is a contract without any Buyer participants. Base contracts are used to contain a set of terms and conditions that can be shared by many contracts. No customer is directly entitled to a base contract. A customer is allowed to use the terms and conditions from a base contract only if one of their customer contracts refers to the base contract.

A contract might refer directly to one base contract only, but there can be a hierarchy of contracts, which allows a contract to share the terms from several base contracts. Placing as many terms as possible in base contracts minimizes the contract management necessary, and reduces the amount of system resources required.

Base contracts can be created in a customer-facing store to be shared by any contract in the store. As well, base contracts can be created in an asset store that allows the base contracts to be shared by contracts in many different stores.

Terms and conditions that are applicable to many customers, or many of a single customer's contracts, must be placed in a base contract. All the contracts that refer to the base contract shares the terms from the base contract. Any changes that are made to a base contract are automatically included in any customer contract that refers to the base contract.

For an extended site, you can create a storefront asset store base for default contract. In the extended site store, the following types of contracts can refer to the storefront asset store base for default contract and share its terms and conditions:
  • Default contracts
  • B2B directBase for default contracts
For examples of contract modeling by using base for default contracts, see Catalog filter assignment and contracts and Price rule assignment and contracts.
Default contract
A store has a default contract, which allows guest and unregistered shoppers to shop in the store. The contract has an empty Buyer participant. The default contract typically has terms and conditions that specifies the entire master catalog is for sale at standard prices.

Default contracts can inherit terms from base for default contracts.

Business accounts
Base contracts are the most common way to share terms and conditions. However, terms that are only applicable to a particular customer must be placed in the customer's business account. All contracts under the business account shares the terms from the account. These terms include purchase orders and credit line.
As described, a customer can be entitled to a set of customer contracts. Based on your design, there might be situations where you allow the customer to use a subset of those entitled contracts in their current shopping session only. For example, a customer might be entitled to three contracts, each one for a department of their company. However, the business requires that each department must have a separate order. When the customer logs in, they choose which department they are purchasing for, and the corresponding contract for that department is set into the customer's session. Therefore, the customer sees the products for the appropriate department. This process ensures that the order applies to one department.
A customer might have only one immediate parent organization in the HCL Commerce organization hierarchy, and thus is only allowed to use only the contracts that are entitled to that organization. This can be restrictive in many situations. A customer might be allowed to shop on behalf of several organizations. To achieve this, the customer can have the OrganizationParticipant role in many organizations. When the customers logs in, they can choose which organization they want to purchase for. This organization is set into the customer's session, and it becomes the active organization. The customer is then allowed to use all the contracts that are entitled to the selected active organization. By default, the session's active organization is the customer's immediate parent organization.

Case study in contract modeling

The following example illustrates how to use these concepts to create an optimal contract design for an online store. A company has a B2B commerce site for its customers. The following requirements need to be supported for their customers:
  • Customers have one or more bill-to addresses
  • Each bill-to address has one or more associated ship-to addresses
  • When a customer is shopping, they shop for one bill-to/ship-to combination at a time
  • Customers are entitled to purchase a subset of the master catalog
  • Customers get list price unless they have a custom price defined which overrides the list price

First, consider a simple design with no sharing at all. Each customer has a set of contracts, each representing a unique bill-to/ship-to combination. Diagram 1 illustrates an example where Customer X has 2 bill-to addresses, and each bill-to address has 2 ship-to addresses. Customer X is entitled to four customer contracts. When an employee of Customer X logs in, they are allowed to shop under the four entitled contracts. (Customer X's business account specifies that they are not entitled to shop by using the store's default contract. If the account did not have that setting, then the customer would also be entitled to a fifth contract, the store's default contract). However, there is a requirement that the shopper can shop for one bill-to/ship-to combination at a time. To fulfill this requirement, the store can present a list of entitled contracts to the shopper, and allow the shopper to choose one of the contracts. The shopper can use one selected contract during this shopping session.

Image showing a simple design as described in the preceding paragraph.

This solution, however, presents a usability concern. Each customer might have 10 bill-to addresses, and each bill-to might have at least five associated ship-to addresses. When a customer logs in, they would be presented with a list of 50 bill-to/ship-to combinations. We do not want the customer to scroll a long list. When the customers logs in, they know for which bill-to they are purchasing, and therefore they must first be presented with a list of bill-to addresses. Once a bill-to address is selected, only then will they need to select the appropriate shipping address. We could write some custom logic to present the fifty contracts in a meaningful way, but preferably the contract functionality can be used to help us present the contract selections. The bill-to addresses can be modeled as base contracts, and the associated ship-to addresses are customer contracts that refer to a bill-to contract.

Diagram 2 illustrates these contract relationships. This modified design helps in that we can first present the set of bill-to base contracts, and then only display the referring ship-to base contracts once the bill-to contract was selected. This solution still requires writing some custom code to find all the base contracts from the entitled customer contracts.

Image showing a simple design as described in the preceding paragraph.

Grouping the bill-to and associated ship-to contracts under different organizations help solve this problem. We use the active organization feature of HCL Commerce. Instead of displaying a list of base contracts, we display a list of organizations for which the customer can shop. A customer can shop for their own organization, plus any organization they are granted special shopping role under. This role is called the OrganizationParticipant role.

Customer X will no longer be directly entitled to the customer contracts. Instead, we create organizations that represent each of the bill-to addresses. These bill-to organizations will then be the Buyer participants in the ship-to customer contracts under the bill-to base contract. Customer X is given authority to use the contracts for each of the bill-to organizations by having the OrganizationParticipant role in the bill-to organization. When a member of Customer X logs in, they can be presented a list of all the organizations in which they have the OrganizationParticipant role. This essentially means they have a list of the bill-to organizations. When one of these organizations is selected, the OrganizationSetInSession command is called, and switches the user to be a member of the selected organization for this session. As a result, the customer is entitled to the contracts entitled to the selected bill-to organization. Therefore the list of ship-to contracts entitled to the bill-to organization can be presented to the customer. When the customer selects one of the ship-to contracts, that contract can be set in the session with the ContractSetInSession command, and now the customer is shopping under their selected bill-to/ship-to contract.

Image showing contract model

There are some added benefits of using the Organization Participant solution. For each active organization, the customer uses, they have a separate shopping cart. This fits nicely with our business model as each active organization is mapped to a bill-to address. Therefore, each unique billing address will have its own shopping cart and order, so each bill-to address is billed separately. However, different shipping addresses (different contracts) under the same bill-to will share order.

The billing address for each bill-to can be placed in the address book of the corresponding bill-to organization. This keeps all the billing addresses separate and easily identifiable during the checkout process. In the original design, the user must identify the correct billing address from the customer's address book. Now the billing addresses are separate in each bill-to organization's address book, and the billing address can be completed on the checkout pages by selecting the billing address from the active organization's address book.

All of a customer's contracts need to share the same product and pricing terms and conditions. A base contract is created that contains the customer's catalog filter term and condition, and all of the customer's bill-to base contracts refer to the customer's catalog filter base contract. Thus, all the customer contracts share the same terms and conditions, and the terms and condition need to be maintained under one contract. If there were any additional terms specific to a bill-to or ship-to, then they could be added to the applicable contract. Each ship-to customer contract consists of only the union of the terms and conditions from the ship-to contract, the referred to bill-to base contract, and the customer's entitlement base contract.

The customer is entitled to the store's list price, with some exceptions where the customer has their own specific price. The Catalog Filter can specify all the product and pricing information. The filter uses two price lists - the store's master price list to get the list price, and the customer's price exceptions price list. The customer's price exceptions price list has a higher precedence than the store's master price list to ensure that the price exceptions override the list price.

The customer is only allowed to purchase a subset of the master catalog. Any exclusion of categories or products can be set in the Catalog Filter.

Image showing contract model.

Design Review

To review the design:

  • ContractSetInSession was used to scope the customer's shopping session to one contract. The contract corresponded to one bill-to/ship-to combination. Use ContractSetInSession to restrict the contracts in use during the session from all the entitled contracts to which a shopper might be entitled.
  • Base contracts were used to share common terms and conditions for individual customers. Using base contracts allows for more efficient use of data within the HCL Commerce system, and requires less management effort.
  • OrganizationSetInSession was used to allow a customer to shop under multiple accounts. This allowed for an effective presentation of bill-to/ship-to choices to the customer, and helped create a different order for each bill-to.
  • Multiple price lists allowed each customer to have an individual price list that could override the standard prices available for products in the master catalog. A price list's precedence helps determine which pricing term and condition from a contract must take precedence.


There are often several ways to model a customer's product and pricing entitlement in a HCL Commerce store. However, by effectively using the fundamental contract concepts that are described in the topic, an optimal contract design can be modeled. This design can often reduce the necessary contract management, and reduce the load on system resources. It can take some time and experience to understand all the contract functions and capabilities. However, after these concepts are mastered, then the best way to model a specific store's contract requirements becomes clear.