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:
| 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:
- Define the jurisdiction groups and jurisdictions.
- Define the shipping modes.
- Define the calculation codes.
- Define the calculation rules.
- Define the calculation scales.
- Define the calculation ranges.
- Define the look-up results for the calculation ranges.
- Associate the calculation scales with the calculation rules.
- Attach the calculation code with the all catalog entries.
- Associate the calculation rules with the fulfillment center.
- Optional: Set the default shipping mode for the store.
- 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 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:
| 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:
| 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) |
| 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) |
| 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) |
| 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:
| 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.
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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 |
| 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:
| 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:
| 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:
| 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:
| 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.