Example: Shipping charges

This example shows how you can use the calculation framework to calculate shipping charges for a store.

Example description

Your store ships products worldwide from one fulfillment center, called FulfillmentA.

You use one shipping carrier to deliver all shipments from the fulfillment center. The shipping carrier offers two shipping methods: regular delivery and express delivery.

The shipping charges are based on the total weight of the shipment in grams. The amount of the charges depends on the geographical zone to which the shipment will be delivered. The three zones are zone A, zone B, and the rest of the world. Both geographical zone A and geographical zone B consist of a single country or region.

The shipping charges are determined using the following table:

Shipping rates

The following table describes shipping rates by zones for regular and express charges.

Description of charge Zone A Zone B Rest of the world
Regular Express Regular Express Regular Express
Basic shipping charge for packages less than 2kg 1.50 2.75 2.00 3.50 3.00 5.00
Additional charge for each kg over 2 kg but less than 10 kg 0.75 1.00 1.25 1.75 2.00 2.50
Additional charge for each kg over 10 kg but less than 20 kg 0.50 0.75 1.00 1.50 1.75 2.00
Additional charge for each kg over 20 kg 0.25 0.50 0.75 1.25 1.50 1.75

The currency of the shipping charges is the local currency of the country or region where your store is located.

Shipping charges example implementation

To use the calculation framework to calculate shipping charges for this example, complete the following steps:

  1. Define the jurisdiction groups and jurisdictions.
  2. Define the shipping modes.
  3. Define the calculation codes.
  4. Define the calculation rules.
  5. Define the calculation scales.
  6. Define the calculation ranges.
  7. Define the look-up results for the calculation ranges.
  8. Associate the calculation scales with the calculation rules.
  9. Attach the calculation code with the all catalog entries.
  10. Associate the calculation rules with the fulfillment center.
  11. Optional: Set the default shipping mode for the store.
  12. Optional: Set the default shipping calculation code for the store. You would only complete this step if your store does not already have a default calculation code defined for shipping charges.

Important: Text identifiers are used in the following sections to make it easier to see the relationships between components.

Text identifiers are often not valid in the HCL Commerce database. You should convert the text identifiers to integers or allow WebSphere Commerce to generate the identifiers for you.

Defining shipping jurisdiction groups and shipping jurisdictions

The first step in using the calculation framework for shipping charge calculations is to define the shipping jurisdiction groups to which shipments are delivered. You must also define the relationships defining which jurisdictions belong to which jurisdiction groups.

Jurisdictions and jurisdiction groups are used by the ShippingCalculationRuleQualify calculation method to determine which calculation rule to use, based on the shipping address of the order.

The information for jurisdictions, jurisdiction groups, and the relationships between them are defined in the following database tables:

JURSTGROUP
This table defines jurisdiction groups.
JURST
This table defines jurisdictions.
JURSTGPREL
This table defines which jurisdictions belong to which jurisdiction groups.

Based on the description in Shipping charges example description, the jurisdictions, jurisdiction groups and the relationships between them can be defined based on the following table:

Geographical zone Jurisdiction Jurisdiction group
Zone A Country or region A GroupA
Zone B Country or region B GroupB
Rest of the world All countries or regions in the world, including country or region A and country or region B World

We later take advantage of the precedence property when we associate shipping charge calculation rules with the three jurisdiction groups in Associate shipping charge calculation rules with fulfillment centers.

Defining shipping modes

A shipping mode represents a combination of a shipping carrier and a shipping service. Shipping mode information is stored in the SHIPMODE and SHPMODEDSC database tables.

The example store uses only one carrier that provides two different delivery methods, so the example store will have two shipping modes as follows:

Shipping modes
Shipping mode Description
Regular Regular delivery mode provided by store's shipping carrier
Express Express delivery mode provided by store's shipping carrier

Defining the shipping calculation code

You must define one calculation code in this example because the shipping charges apply to all items in an order. The calculation code must be associated with a CalculationCodeQualify calculation method so that the correct calculation rule can be chosen based on the address of the order.

Here are the key properties that you must define for the calculation code:

Property Value Description of value
Grouping method 0 No grouping since shipping charges are based on the total weight of all items in an order
Qualification flag 0 The CalculationCodeQualify calculation method specified for this calculation code will not be invoked
Identifying string Shipping example This is a character string that uniquely identifies this calculation code, given a particular calculation usage and store or store group.
Published 1 Calculation code is active
Calculation usage ID -2 This is the ID for shipping calculation usage
CalculationCodeQualify calculation method -22 This is the ID for CalculationCodeQualifyCmd
CalculationCodeApply calculation method -24 This is the ID for ShippingCalculationCodeApplyCmd
CalculationCodeCalculate calculation method -23 This is the ID for CalculationCodeCalculateCmd

Defining shipping calculation rules

A calculation rule is required for each shipping mode for each jurisdiction group. This example requires six calculation rules:

  • Calculate regular shipping charge for GroupA jurisdiction group.
  • Calculate express shipping charge for GroupA jurisdiction group.
  • Calculate regular shipping charge for GroupB jurisdiction group.
  • Calculate express shipping charge for GroupB jurisdiction group.
  • Calculate regular shipping charge for World jurisdiction group.
  • Calculate express shipping charge for World jurisdiction group.

These rules are all shipping calculation rules, so you should specify that the ShippingCalculationRuleQualify calculation method should be used with these calculation rules.

For this example, all of the calculation rules will have the same properties as shown in the following table:

Values for shipping charge calculation rules
Property Value Description of value
Calculation code ShipCalcCode Shipping charge calculation code defined earlier
Identifying number a different number for each calculation rule This is a number that, along with its calculation code, uniquely identifies this calculation rule. This number must be unique for each calculation rule belonging to the same calculation code.
Qualification flag 1 Invoke the qualify calculation method defined for this calculation rule to check that this calculation rule applies to each item in the order
Combination 1 The results of this calculation rule can be combined with other calculation rules having a 0 combination property
CalculationRuleQualify calculation method -26 This is the ID for ShippingCalculationRuleQualifyCmd
CalculationRuleCalculate calculation method -27 This is the ID for CalculationRuleCalculateCmd

For the rest of the example, these calculation rules will be referred to as follows:

  • GroupARegularRule (GroupA regular shipping charge calculation rule)
  • GroupAExpressRule (GroupA express shipping charge calculation rule)
  • GroupBRegularRule (GroupB regular shipping charge calculation rule)
  • GroupBExpressRule (GroupB express shipping charge calculation rule)
  • WorldRegularRule (World regular shipping charge calculation rule)
  • WorldExpressRule (World express shipping charge calculation rule)

Defining shipping charge calculation scales

A calculation scale is required for each shipping mode for each jurisdiction group. The calculation scales for this example are based on the weight of the order in kilograms, so the calculation scales must be associated with a unit of measurement.

The shipping charges are based on the total weight of the OrderItems in an order, so the WeightCalculationScaleLookupCmd calculation method is used at the CalculationScaleLookup calculation method for this calculation scale.

This example requires six calculation scales as follows:

  • GroupA regular shipping charge scale
  • GroupA express shipping charge scale
  • GroupB regular shipping charge scale
  • GroupB express shipping charge scale
  • World regular shipping charge scale
  • World express shipping charge scale

For this example, all of the calculation scales will have the same properties as shown in the following table:

Property Value Description of value
Calculation usage -2 Shipping charge calculation usage
Identifying string Shipping example This is a character string that uniquely identifies this calculation scale, given a particular calculation usage and store or store group.
CalculationScaleLookup calculation method -29 WeightCalculationScaleLookupCmd
Unit of measurement KGM This calculation scale is based on weights in kilograms. The calculation scale look-up number is in kilograms as well.

For the rest of the example, these calculation scales will be referred to as follows:

  • GroupARegularScale (GroupA regular shipping charge calculation scale)
  • GroupAExpressScale (GroupA express shipping charge calculation scale)
  • GroupBRegularScale (GroupB regular shipping charge calculation scale)
  • GroupBExpressScale (GroupB express shipping charge calculation scale)
  • WorldRegularScale (World regular shipping charge calculation scale)
  • WorldExpressScale (World express shipping charge calculation scale)

Defining shipping charge calculation ranges

Each calculation scale that we defined in the previous step requires a set of four calculation ranges. This results in a total of 24 calculation ranges that must be defined for this example. Here are the four calculation ranges for each calculation scale:

  • 0-2 kg (basic shipping charge for packages less than 2kg)
  • 2-10 kg (additional charge for each kg over 2 kg but less than 10 kg)
  • 10-20 kg (additional charge for each kg over 10 kg but less than 20 kg)
  • 20 kg or greater (additional charge for each kg over 20 kg)

The calculation ranges are all cumulative. The results from one or more of these calculation ranges are added to determine the final shipping charge associated with each OrderItem in an order.

Here are the key properties that you must define for each calculation range:

0-2 kg calculation range properties
Property Value Description of value
Calculation range starting value 0 This calculation range applies to any OrderItem where the total order weight is 0 or more kilograms
Cumulative calculation range indicator 1 This calculation range is cumulative.
CalculationRange calculation method -33 FixedAmountCalculationRangeCmd (the look-up result is treated as a fixed monetary amount)
2-10 kg calculation range properties
Property Value Description of value
Calculation range starting value 2 This calculation range applies to any OrderItem where the total order weight is 2 or more kilograms
Cumulative calculation range indicator 1 This calculation range is cumulative
CalculationRange calculation method -34 PerUnitAmountCalculationRangeCmd (the look-up result is multiplied by the part of the total order weight that falls into this range)
10-20 kg calculation range properties
Property Value Description of value
Calculation range starting value 10 This calculation range applies to any OrderItem where the total order weight is 10 or more kilograms
Cumulative calculation range indicator 1 This calculation range is cumulative
CalculationRange calculation method -34 PerUnitAmountCalculationRangeCmd (the look-up result is multiplied by the part of the total order weight that falls into this range)
20 kg or greater calculation range properties
Property Value Description of value
Calculation range starting value 20 This calculation range applies to any OrderItem where the total order weight is 20 or more kilograms
Cumulative calculation range indicator 1 This calculation range is cumulative
CalculationRange calculation method -34 PerUnitAmountCalculationRangeCmd (the look-up result is multiplied by the part of the total order weight that falls into this range)

For the rest of the example, these calculation ranges will be referred to as follows:

  • GroupARegular0to2Range
  • GroupARegular2to10Range
  • GroupARegular10to20Range
  • GroupARegular20+Range
  • GroupAExpress0to2Range
  • GroupAExpress2to10Range
  • GroupAExpress10to20Range
  • GroupAExpress20+Range
  • GroupBRegular0to2Range
  • GroupBRegular2to10Range
  • GroupBRegular10to20Range
  • GroupBRegular20+Range
  • GroupBExpress0to2Range
  • GroupBExpress2to10Range
  • GroupBExpress10to20Range
  • GroupBExpress20+Range
  • WorldRegular0to2Range
  • WorldRegular2to10Range
  • WorldRegular10to20Range
  • WorldRegular20+Range
  • WorldExpress0to2Range
  • WorldExpress2to10Range
  • WorldExpress10to20Range
  • WorldExpress20+Range

You must specify the calculation scale ID of the calculation scale to which the calculation range belongs when defining a calculation range. The relationships between the defined calculation scales and the calculation ranges we are defining is shown in the following table:

Table 1. The following table show shipping charge calculation ranges and their associated calculation scales

The following table show shipping charge calculation ranges and their associated calculation scales

Calculation ranges Calculation scales
GroupARegular0to2Range GroupARegularScale
GroupARegular2to10Range
GroupARegular10to20Range
GroupARegular20+Range
GroupAExpress0to2Range GroupAExpressScale
GroupAExpress2to10Range
GroupAExpress10to20Range
GroupAExpress20+Range
GroupBRegular0to2Range GroupBRegularScale
GroupBRegular2to10Range
GroupBRegular10to20Range
GroupBRegular20+Range
GroupBExpress0to2Range GroupBExpressScale
GroupBExpress2to10Range
GroupAExpress10to20Range
GroupBExpress20+Range
WorldRegular0to2Range WorldRegularScale
WorldRegular2to10Range
WorldRegular10to20Range
WorldRegular20+Range
WorldExpress0to2Range WorldExpressScale
WorldExpress2to10Range
WorldExpress10to20Range
WorldExpress20+Range

Defining look-up results for shipping charge calculation ranges

Each calculation range needs a set of look-up results. Each calculation range has only one value associated with it, so only one look-up result is needed for each range. Each look-up result must be associated with the local currency of the country or region for the store because that is the currency of the shipping charges.

The following tables define the key properties that you must define for each calculation range look-up result. The currency has been omitted here, but it must be included in an actual implementation.

GroupARegular0to2LookupResult
Property Value Description of value
Look-up result 1.50 1.50 basic shipping charge for order weights under 2kg
Calculation range ID GroupARegular0to2Range The identifier of the calculation range to which this look-up result belongs
GroupARegular2to10LookupResult
Property Value Description of value
Look-up result 0.75 0.75 additional charge per kilogram for order weights greater than or equal to 2kg
Calculation range ID GroupARegular2to10Range The identifier of the calculation range to which this look-up result belongs
GroupARegular10to20LookupResult
Property Value Description of value
Look-up result 0.50 0.50 additional charge per kilogram for order weights greater than or equal to 10kg
Calculation range ID GroupARegular10to20Range The identifier of the calculation range to which this look-up result belongs
GroupARegular20+LookupResult
Property Value Description of value
Look-up result 0.25 0.25 additional charge per kilogram for order weights greater than or equal to 20kg
Calculation range ID GroupARegular20+Range The identifier of the calculation range to which this look-up result belongs
GroupAExpress0to2LookupResult
Property Value Description of value
Look-up result 2.75 2.75 basic shipping charge for order weights under 2kg
Calculation range ID GroupAExpress0to2Range The identifier of the calculation range to which this look-up result belongs
GroupAExpress2to10LookupResult
Property Value Description of value
Look-up result 1.00 1.00 additional charge per kilogram for order weights greater than or equal to 2kg
Calculation range ID GroupAExpress2to10Range The identifier of the calculation range to which this look-up result belongs
GroupAExpress10to20LookupResult
Property Value Description of value
Look-up result 0.75 0.75 additional charge per kilogram for order weights greater than or equal to 10kg
Calculation range ID GroupAExpress10to20Range The identifier of the calculation range to which this look-up result belongs
GroupAExpress20+LookupResult
Property Value Description of value
Look-up result 0.50 0.50 additional charge per kilogram for order weights greater than or equal to 20kg
Calculation range ID GroupAExpress20+Range The identifier of the calculation range to which this look-up result belongs
GroupBRegular0to2LookupResult
Property Value Description of value
Look-up result 2.00 2.00 basic shipping charge for order weights under 2kg
Calculation range ID GroupBRegular0to2Range The identifier of the calculation range to which this look-up result belongs
GroupBRegular2to10LookupResult
Property Value Description of value
Look-up result 1.25 1.25 additional charge per kilogram for order weights greater than or equal to 2kg
Calculation range ID GroupBRegular2to10Range The identifier of the calculation range to which this look-up result belongs
GroupBRegular10to20LookupResult
Property Value Description of value
Look-up result 1.00 1.00 additional charge per kilogram for order weights greater than or equal to 10kg
Calculation range ID GroupBRegular10to20Range The identifier of the calculation range to which this look-up result belongs
GroupBRegular20+LookupResult
Property Value Description of value
Look-up result 0.75 0.75 additional charge per kilogram for order weights greater than or equal to 20kg
Calculation range ID GroupBRegular20+Range The identifier of the calculation range to which this look-up result belongs
GroupBExpress0to2LookupResult
Property Value Description of value
Look-up result 3.50 3.50 basic shipping charge for order weights under 2kg
Calculation range ID GroupBExpress0to2Range The identifier of the calculation range to which this look-up result belongs
GroupBExpress2to10LookupResult
Property Value Description of value
Look-up result 1.75 1.75 additional charge per kilogram for order weights greater than or equal to 2kg
Calculation range ID GroupBExpress2to10Range The identifier of the calculation range to which this look-up result belongs
GroupBExpress10to20LookupResult
Property Value Description of value
Look-up result 1.50 1.50 additional charge per kilogram for order weights greater than or equal to 10kg
Calculation range ID GroupBExpress10to20Range The identifier of the calculation range to which this look-up result belongs
GroupBExpress20+LookupResult
Property Value Description of value
Look-up result 1.25 1.25 additional charge per kilogram for order weights greater than or equal to 20kg
Calculation range ID GroupBExpress20+Range The identifier of the calculation range to which this look-up result belongs
WorldRegular0to2LookupResult
Property Value Description of value
Look-up result 3.00 3.00 basic shipping charge for order weights under 2kg
Calculation range ID WorldRegular0to2Range The identifier of the calculation range to which this look-up result belongs
WorldRegular2to10LookupResult
Property Value Description of value
Look-up result 2.00 2.00 additional charge per kilogram for order weights greater than or equal to 2kg
Calculation range ID WorldRegular2to10Range The identifier of the calculation range to which this look-up result belongs
WorldRegular10to20LookupResult
Property Value Description of value
Look-up result 1.75 0.50 additional charge per kilogram for order weights greater than or equal to 10kg
Calculation range ID WorldRegular10to20Range The identifier of the calculation range to which this look-up result belongs
WorldRegular20+LookupResult
Property Value Description of value
Look-up result 1.50 0.25 additional charge per kilogram for order weights greater than or equal to 20kg
Calculation range ID WorldRegular20+Range The identifier of the calculation range to which this look-up result belongs
WorldExpress0to2LookupResult
Property Value Description of value
Look-up result 5.00 5.00 basic shipping charge for order weights under 2kg
Calculation range ID WorldExpress0to2Range The identifier of the calculation range to which this look-up result belongs
WorldExpress2to10LookupResult
Property Value Description of value
Look-up result 2.50 2.50 additional charge per kilogram for order weights greater than or equal to 2kg
Calculation range ID WorldExpress2to10Range The identifier of the calculation range to which this look-up result belongs
WorldExpress10to20LookupResult
Property Value Description of value
Look-up result 2.00 2.00 additional charge per kilogram for order weights greater than or equal to 10kg
Calculation range ID WorldExpress10to20Range The identifier of the calculation range to which this look-up result belongs
WorldExpress20+LookupResult
Property Value Description of value
Look-up result 1.75 1.75 additional charge per kilogram for order weights greater than or equal to 20kg
Calculation range ID WorldExpress20+Range The identifier of the calculation range to which this look-up result belongs

Reminder:

These properties are missing the currency for the look-up results. The currency of the look-up results must be defined. For this example, it must match the currency of the calculation scale.

Associating shipping charge calculation scale with shipping charge calculation rules

Each of the calculation scales that have been defined must be associated with the defined calculation rules in the CRULESCALE database table. The relationship between the defined calculation scales and the defined calculation rules is shown in the following table:

Shipping calculation scales and the associated calculation rules
Calculation scale Calculation rule
GroupARegularScale GroupARegularRule
GroupAExpressScale GroupAExpressRule
GroupBRegularScale GroupBRegularRule
GroupBExpressScale GroupBExpressRule
WorldRegularScale WorldRegularRule
WorldExpressScale WorldExpressRule

Attaching shipping charge calculation codes

To use the new calculation code that you defined earlier, you must attach it to the order items. Attach it indirectly, because it applies to all items resulting from a customer purchasing a product from the store catalog, not just one item.

We will indirectly attach the calculation code by creating an entry in the CATENCALCD database table. To associate the calculation code with all items in the store catalog, use a catalog entry ID of null. The identifier for the store will be called Store.

Populate the CATENCALCD database table with the following information:

Shipping charge calculation code attachment information
Store ID Catalog entry ID Calculation code
Store null ShipCalcCode

Associate shipping charge calculation rules with fulfillment centers

You must enter information that associates a fulfillment center with a shipping charge calculation in the SHIPJCRULE database table. You do this so that the ShippingCalculationRuleQualify method chooses a calculation rule when shipping from a fulfillment center to a shipping address that matches one of the shipping jurisdiction groups.

We take advantage of the precedence property of the relationship between calculation rules and fulfillment centers. We set the following precedence property values:

  • For relationships involving the GroupA or GroupB shipping jurisdiction group, we set the precedence property value to 1.
  • For relationships involving the World shipping jurisdiction group, we set the precedence property value to 0.

This ensures that if a shipping address falls into all the shipping jurisdiction groups, the calculation rule applicable to GroupA or GroupB takes precedence over the calculation rule applicable to the World jurisdiction group.

We have one fulfillment center, three shipping jurisdiction groups, and six calculation rules in this example. The relationships between these elements is defined in the following table:

Information relating calculation rules to fulfillment centers

Information relating calculation rules to fulfillment centers

Fulfillment center Shipping jurisdiction group Precedence Shipping charge calculation rule
FulfillmentA GroupA 1 GroupARegular
GroupAExpress
GroupB 1 GroupBRegular
GroupBExpress
World 0 WorldRegular
WorldExpress

Defining the default shipping mode (optional)

You might want to define a default shipping mode for a store or a contract. Shipping modes are associated with a store and contract in the STOREDEF database table.

To determine what values are required to set a shipping mode as the default shipping mode, refer to the database schema documentation.

Defining default shipping calculation codes for a store (optional)

If your store does not already have a default calculation code for shipping charges, you might want to make the calculation code that you defined earlier your default.

Default calculation codes for a store are defined in the STENCALUSG database table. The following table contains the information required to define the default shipping calculation code for the store:

Information to define default calculation codes for the store
Store ID Calculation Usage Calculation Code
Store -2 (shipping) ShipCalcCode

Generally, a shipping calculation code is not both attached to all catalog entries in a store and also defined as the default shipping calculation code. When a shipping calculation code is attached to all catalog entries in a store, additional codes that are defined and attached later will cause the total shipping charge to be the sum of shipping charges resulting from each code. If a default shipping calculation code is defined, and no codes are attached to the catalog entries or catalog groups, you can have different shipping rate for individual catalog entries or catalog groups. Attaching a shipping calculation code to a catalog entry or catalog group overrides the default.