Using Tiered Shipping Rates

Fixed Shipping Rate versus Tiered Shipping Rates

For many merchants it suffices to have one Shipping Rate (expressed in different currencies) per ShippingMethod. We call this a fixed shipping rate. No matter the content or the conditions of the cart, the shipping rate is always the same. In addition, with a fixed shipping rate, you can define a Free Above threshold. This means that any cart will have free shipping if the cart value (the sum of the line item prices) exceeds the Free Above threshold.

For merchants that operate with a more detailed and dynamic logic when it comes to shipping rates, we offer Tiered Shipping Rates. With Tiered Shipping Rates, you are able to let the shipping rate decrease or increase based on tiers defined by you. Examples:

• shipping rate should decrease based on the cart value, that means the more money the customer is spending, the cheaper shipping should be.
• shipping rate should increase based on the weight of the line items in the cart, that means the heavier the delivery will be, the more expensive shipping should be.
• shipping rate should be configurable based on an abstract shipping score or classification determined by a merchant specific logic, that means the merchant builds his own algorithm taking a series of parameters into consideration and outputs a shipping score for the cart which then maps to a shipping rate within the commercetools platform.

Enabling Tiered Shipping Rates

You enable Tiered Shipping Rates under Project Settings. Here you find a parameter called ShippingRateInputType. This is an optional parameter and if not set, you will have the default configuration of fixed shipping rates enabled. For enabling Tiered Shipping Rates, you have to define the type of tiers you want to map your shipping rate to. Three types exist: Cart Value, Cart Classification and Cart Score.

• Cart Value is used when the shipping rate maps to the sum of the line item prices
• Cart Classification is used when the shipping rate maps to an abstract cart categorization expressed through a string, for example green, yellow, red or light, medium, heavy
• Cart Score is used when the shipping rate maps to an abstract cart categorization expressed through an integer, for example shipping score or weight ranges.

Defining the Tiers and their Shipping Rates

Once the ShippingRateInputType has been set, you are ready to define your tiers and the shipping rate they should map to. You do so by defining the array called tiers within the ShippingRate object. The following examples illustrate tiered shipping rates for each of the supported input types.

In the example below, the input type is CartValue. You see how the shipping rate gradually gets lower until it becomes free of charge when the cart value exceeds $200.

This is the same example, encoded in JSON:

{
  "id": "shipping-method-1",
  "version": 1,
  "name": "DHL",
  "taxCategory": {
    "typeId": "tax-category",
    "id": "tax-category-1"
  },
  "isDefault": false,
  "zoneRates": [
    {
      "zone": {
        "typeId": "zone",
        "id": "zone-1"
      },
      "shippingRates": [
        {
          "price": {
            "currencyCode": "EUR",
            "centAmount": 400
          },
          "tiers": [{
            "type" : "CartValue",
            "minimumCentAmount": 5000,
            "price": {
              "currencyCode": "EUR",
              "centAmount": 300
            }
          },
          {
            "type" : "CartValue",
            "minimumCentAmount": 7500,
            "price": {
              "currencyCode": "EUR",
              "centAmount": 200
            }
          },
          {
            "type" : "CartValue",
            "minimumCentAmount": 1000,
            "price": {
              "currencyCode": "EUR",
              "centAmount": 0
            }
          }
          ]
        }
      ]
    }
  ]
}

In the following example, the input type is CartClassification. Should no explicit classification be provided by you for a given cart during checkout, the shipping rate will be $10. If the cart is classified as Medium, the shipping rate is $25 and so forth.

This is the same example, encoded in JSON:

{
  "id": "shipping-method-1",
  "version": 1,
  "name": "DHL",
  "taxCategory": {
    "typeId": "tax-category",
    "id": "tax-category-1"
  },
  "isDefault": false,
  "zoneRates": [
    {
      "zone": {
        "typeId": "zone",
        "id": "zone-1"
      },
      "shippingRates": [
        {
          "price": {
            "currencyCode": "EUR",
            "centAmount": 1000
          },
          "tiers": [{
            "type" : "CartClassification",
            "value": "Medium",
            "price": {
              "currencyCode": "EUR",
              "centAmount": 2500
            }
          },
          {
            "type" : "CartClassification",
            "value": "Heavy",
            "price": {
              "currencyCode": "EUR",
              "centAmount": 5000
            }
          }
          ]
        }
      ]
    }
  ]
}

In the example below, the input type is CartScore and the score represents the total weight of the cart expressed in grams. You see how a cart containing line items with a combined weight of 50 grams or less will have a shipping rate of $1.75. As the weight increases, the shipping rate goes up.

In the example below, the input type is CartScore and the score represents and abstract encapsulation that represents how much shipping should cost. What is especially interesting about this example is how the shipping rate can be expressed as a linear function. For scores until 35, the shipping rate jumps up in set intervals from $2 to $6 to $8. For all scores higher than 35, the shipping rate will be calculated based on the defined function, for example a shipping score of 40 will map to a shipping rate of $10.

This is the same example, encoded in JSON. Note that in the function, the rate is expressed in cent amounts.

{
  "id": "shipping-method-1",
  "version": 1,
  "name": "DHL",
  "taxCategory": {
    "typeId": "tax-category",
    "id": "tax-category-1"
  },
  "isDefault": false,
  "zoneRates": [
    {
      "zone": {
        "typeId": "zone",
        "id": "zone-1"
      },
      "shippingRates": [
        {
          "price": {
            "currencyCode": "USD",
            "centAmount": 500
          },
          "tiers": [{
            "type" : "CartScore",
            "score": 5,
            "price": {
              "currencyCode": "USD",
              "centAmount": 750
            }
          },
          {
            "type" : "CartScore",
            "score": 10,
            "price": {
              "currencyCode": "USD",
              "centAmount": 1000
            }
          },
          {
            "type" : "CartScore",
            "score": 15,
            "priceFunction": {
              "currencyCode": "USD",
              "function": "(50 * x) + 750"
            }
          }
          ]
        }
      ]
    }
  ]
}

The above examples are intended to illustrate the possible ways of defining tiered shipping rates from a business perspective.

How does the Shipping Rate get identified during checkout?

When creating a cart, the parameter called shippingRateInput can be set on the CartDraft. The value set here will be used as look-up value to determine the shipping rate according to the definition of the tiers. If no value is set, or there is no tier for the value, the default shipping rate will be found.

An exception to this is when the Shipping Input Type is CartValue. Here the commercetools platform arrives at the sum of line item prices itself and looks up the shipping rate accordingly.

The shipping rate will be calculated when the shippingRateInput is updated on the cart or when the shippingMethod is updated on the ShippingInfo of the cart. Additionally, when the Shipping Input Type is CartValue, or when a fixed shipping rate has a Free Above threshold set, the shipping rate is also calculated when the total price of the cart changes.