Tutorial

What are Tiered Shipping Rates?

This tutorial shows the possible ways of configuring shipping rates on the commercetools platform.

What is a Fixed Shipping Rate vs. 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 (i.e. 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:

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.

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.

Shipping Rate Tier Shipping Rate
Default $4
> $50 $3
> $75 $2
> $100 $0

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 example below, the input type is CartClassification. Should no explicit classification be provided by you for a given cart during checkout, or if the classification is “Light”, the shipping rate will be $10. If the cart is classified as “Medium”, the shipping rate is $25 and so forth.

Shipping Rate Tier Shipping Rate
Default $10
Medium $25
Heavy $50

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.

Shipping Rate Tier Shipping Rate
Default $1.75
> 50 $2.50
> 100 $4.75
> 500 $7.25
> 1000 $10.50

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, e.g. a shipping score of 40 will map to a shipping rate of $10.

Shipping Rate Tier Shipping Rate
Default $2
> 5 $3
> 15 $6
> 25 $8
> 35 x - 30

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.