Shipping Methods

With Shipping Methods you can specify which shipping services you want to provide to your customers for deliveries to different areas of the world at rates you can define. Furthermore, you can extend this resource according to your needs to store custom content, metadata, or to model your workflow.

A maximum number of 100 shipping methods can be created per project. Learn more about this limit.

Representations

ShippingRatePriceTier

CartValue

CartClassification

CartScore with fixed price

CartScore with function

PriceFunction

ShippingMethod

A shipping method defines a specific way of shipping, with different rates for different geographic locations. Example shipping methods are DHL, DHL Express and UPS.

id - String
The unique ID of the shipping method.
key - String - Optional
User-specific unique identifier for the shipping method.
version - Number
The current version of the shipping method.
createdAt - DateTime
lastModifiedAt - DateTime
name - String
localizedName - LocalizedString - Optional
localizedDescription - LocalizedString - Optional
description - String - Optional
This field has been deprecated in favor of localizedDescription.
taxCategory - Reference to a TaxCategory
zoneRates - Array of ZoneRate
isDefault - Boolean
One shipping method in a project can be default.
predicate - String - Optional
A Cart predicate which can be used to more precisely select a shipping method for a cart.
custom - CustomFields - Optional

ShippingMethodDraft

This representation needs to be given with a Create ShippingMethod request.

name - String - Required
localizedName - LocalizedString - Optional
key - String - Optional
localizedDescription - LocalizedString - Optional
description - String - Optional
This field has been deprecated in favor of localizedDescription.
taxCategory - ResourceIdentifier of a TaxCategory - Required
zoneRates - Array of ZoneRateDraft - Optional
isDefault - Boolean - Optional
If true the shipping method will be the default one in a project.
predicate - String - Optional
A Cart predicate which can be used to more precisely select a shipping method for a cart.
custom - CustomFieldsDraft - Optional
The custom fields.

ShippingRate

price - CentPrecisionMoney
freeAbove - CentPrecisionMoney - Optional
The shipping is free if the sum of the (custom) line item prices reaches the freeAbove value.
Note: Alternatively, free shipping can also be achieved using a Cart Discount on the ShippingCost Target. We highly recommend using either of these methods, but not both together.
tiers - Array of ShippingRatePriceTier
A list of shipping rate price tiers.
isMatching - Boolean - Optional
Only appears in response to requests for shipping methods by cart or location to mark this shipping rate as one that matches the cart or location.

ShippingRateDraft

price - Money
freeAbove - Money - Optional
The shipping is free if the sum of the (custom) line item prices reaches the freeAbove value.
Note: Alternatively, free shipping can also be achieved using a Cart Discount on the ShippingCost Target. We highly recommend using either of these methods, but not both together.
tiers - Array of ShippingRatePriceTier - Optional
A list of shipping rate price tiers.

ZoneRate

Defines shipping rates (prices) for a specific zone. Shipping rates is an array because the rates for different currencies can be defined.

zone - Reference to a Zone
shippingRates - Array of ShippingRate
The array does not contain two shipping rates with the same currency.

The following example defines the "DHL" ShippingMethod with different rates for Europe, US mainland and Hawaii with Alaska. Shipping with DHL has the following rates:

Germany, UK and France costs 10 EUR or 12 USD.
US without Alaska and Hawaii costs 20 EUR or 24 USD
Alaska and Hawaii costs 30 EUR or 34 USD

Examplejson

{
  "id": "zone-1",
  "version": 1,
  "name": "Europe",
  "locations": [
    { "country": "DE" },
    { "country": "UK" },
    { "country": "FR" }
  ]
}

{
  "id": "zone-2",
  "version": 1,
  "name": "US Mainland",
  "locations": [
    { "country": "US" }
  ]
}

{
  "id": "zone-3",
  "version": 1,
  "name": "US Hawaii and Alaska",
  "locations": [
    {
      "country": "US",
      "state": "Hawaii"
    },
    {
      "country": "US",
      "state": "Alaska"
    }
  ]
}

{
  "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
          }
        },
        {
          "price": {
            "currencyCode": "USD",
            "centAmount": 1200
          }
        }
      ]
    },
    {
      "zone": {
        "typeId": "zone",
        "id": "zone-2"
      },
      "shippingRates": [
        {
          "price": {
            "currencyCode": "EUR",
            "centAmount": 2000
          }
        },
        {
          "price": {
            "currencyCode": "USD",
            "centAmount": 2400
          }
        }
      ]
    },
    {
      "zone": {
        "typeId": "zone",
        "id": "zone-3"
      },
      "shippingRates": [
        {
          "price": {
            "currencyCode": "EUR",
            "centAmount": 3000
          }
        },
        {
          "price": {
            "currencyCode": "USD",
            "centAmount": 3400
          }
        }
      ]
    }
  ]
}

ZoneRateDraft

zone - ResourceIdentifier for a Zone
shippingRates - Array of ShippingRateDraft
The array must not contain two shipping rates with the same currency.

ShippingRatePriceTier

ShippingRatePriceTiers must be enabled and defined on the Project and are used together with the shippingRateInput field on the Cart.

A price tier is selected instead of the default price when a certain threshold or specific cart value is reached. If no tiered price is suitable for the cart, the base price of the shipping rate is used.

There exist three different kinds of ShippingRatePriceTiers:

CartValueType is used when the shipping rate maps to the sum of the line item prices
CartClassificationType 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
CartScoreType is used when the shipping rate maps to an abstract cart categorization expressed through an integer, for example shipping score or weight ranges. Scores can be mapped to a fixed price, or dynamically calculated with a function.

The following example shows ShippingMethods with the 3 different ways how tiered prices are created:

This example shows how to create tiered prices based on the CartValueType:

{
  "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
            }
          }
          ]
        }
      ]
    }
  ]
}

This example shows how to create tiered prices based on the CartClassificationType:

{
  "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
            }
          }
          ]
        }
      ]
    }
  ]
}

This example shows how to create tiered prices based on the CartScoreType:

{
  "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"
            }
          }
          ]
        }
      ]
    }
  ]
}

CartValue

type - String - "CartValue"
minimumCentAmount - Number
price - Money
isMatching - Boolean - Optional\
Only appears in response to requests for shipping methods by cart to mark this shipping rate price tier as the one that matches the cart.

CartClassification

type - String - "CartClassification"
value - String Must be a valid key of the CartClassificationType
price - Money
isMatching - Boolean - Optional\
Only appears in response to requests for shipping methods by cart to mark this shipping rate price tier as the one that matches the cart.

CartScore with fixed price

Sets a fixed price for a score.

type - String - "CartScore"
score - Number
price - Money
isMatching - Boolean - Optional\
Only appears in response to requests for shipping methods by cart to mark this shipping rate price tier as the one that matches the cart.

CartScore with function

Allows to calculate a price dynamically for a range of scores.

type - String - "CartScore"
score - Number
priceFunction - PriceFunction
isMatching - Boolean - Optional\
Only appears in response to requests for shipping methods by cart to mark this shipping rate price tier as the one that matches the cart.

PriceFunction

To calculate a price based on the score, you can use +, -, * as well as parens. The score is inserted with x. The function returns the cent amount. For example, if you want to charge $1.99 for a score of 1, $3.99 for a score of 2, $5.99 for a score of 3 and so on, the function is: (200 * x) - 1). If you want to charge $4.50, $6.00, and $7.50 for express shipping, the function is: (150 * x) + 300.

currencyCode - String The currency code compliant to ISO 4217. Must be the same as the currencyCode of the default price.
function - String

Get ShippingMethod

Get ShippingMethod by ID

Endpoint: /{projectKey}/shipping-methods/{id}
Method: GET
OAuth 2.0 Scopes: view_orders:{projectKey}, view_shipping_methods:{projectKey} or manage_my_orders:{projectKey}
Response Representation: ShippingMethod

Get ShippingMethod by Key

Endpoint: /{projectKey}/shipping-methods/key={key}
Method: GET
OAuth 2.0 Scopes: view_orders:{projectKey}, view_shipping_methods:{projectKey} or manage_my_orders:{projectKey} Response Representation: ShippingMethod

Query ShippingMethods

Endpoint: /{projectKey}/shipping-methods
Method: GET
OAuth 2.0 Scopes: view_orders:{projectKey}, view_shipping_methods:{projectKey} or manage_my_orders:{projectKey}
Response Representation: PagedQueryResult with results containing an array of ShippingMethod
Query Parameters:

where - Query Predicate - Optional
sort - Sort - Optional
expand - Expansion - Optional
limit - Number - Optional
offset - Number - Optional

Get ShippingMethods for a Cart

Retrieves all the shipping methods that can ship to the shipping address of the given cart. Each shipping method contains exactly one shipping rate with the flag isMatching set to true. This shipping rate will be used if the shipping method is added to the cart.

Endpoint: /{projectKey}/shipping-methods/matching-cart
Method: GET
OAuth 2.0 Scopes: view_orders:{projectKey}, view_shipping_methods:{projectKey} or manage_my_orders:{projectKey}
Response Representation: PagedQueryResult with results containing an array of ShippingMethod
Query Parameters:

cartId - String - Required
The ID of the cart with a shipping address set.
expand - Expansion - Optional

Get ShippingMethods for a Cart in a Store by ID

Endpoint: /{projectKey}/in-store/key={storeKey}/shipping-methods/matching-cart
Method: GET
OAuth 2.0 Scopes: view_orders:{projectKey}, view_orders:{projectKey}:{storeKey}, view_shipping_methods:{projectKey}, manage_my_orders:{projectKey} or manage_my_orders:{projectKey}:{storeKey}
Response Representation: PagedQueryResult with results containing an array of ShippingMethod
Query Parameters:

cartId - String - Required
The ID of the cart with a shipping address set.
expand - Expansion - Optional

Get ShippingMethods for a Location

Retrieves all the shipping methods that can ship to the given Location. If the currency parameter is given, then the shipping methods must also have a rate defined in the specified currency. Each shipping method contains at least one shipping rate with the flag isMatching set to true. If the currency parameter is given, exactly one shipping rate will contain it.

Endpoint: /{projectKey}/shipping-methods/matching-location
Method: GET
OAuth 2.0 Scopes: view_orders:{projectKey}, view_shipping_methods:{projectKey} or manage_my_orders:{projectKey}
Response Representation: PagedQueryResult with results containing an array of ShippingMethod
Query Parameters:

country - String - Required
A two-digit country code as per ISO 3166-1 alpha-2.
state - String - Optional
currency - String - Optional
The currency code compliant to ISO 4217.
expand - Expansion - Optional

Get ShippingMethods for an OrderEdit

Retrieves all the shipping methods that can ship to the given Location for an OrderEdit.

Endpoint: /{projectKey}/shipping-methods/matching-orderedit Method: GET OAuth 2.0 Scopes: view_orders:{projectKey} or view_shipping_methods:{projectKey} Response Representation: PagedQueryResult with results containing an array of ShippingMethod Query Parameters:

orderEditId - String - Required The ID of the OrderEdit
country - String - Required A two-digit country code as per ISO 3166-1 alpha-2.
state - String - Optional

In case the OrderEdit preview cannot be created an EditPreviewFailed error is raised.

Create ShippingMethod

Endpoint: /{projectKey}/shipping-methods
Method: POST
OAuth 2.0 Scopes: manage_orders:{projectKey} or manage_shipping_methods:{projectKey} Request Representation: ShippingMethodDraft
Response Representation: ShippingMethod

Update ShippingMethod

Update ShippingMethod by ID

Endpoint: /{projectKey}/shipping-methods/{id}
Method: POST
OAuth 2.0 Scopes: manage_orders:{projectKey} or manage_shipping_methods:{projectKey}
Response Representation: ShippingMethod
Fields:

version - Number - Required
The expected version of the ShippingMethod on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
actions - Array of UpdateAction - Required
The list of update actions to be performed on the ShippingMethod.

Update ShippingMethod by Key

Endpoint: /{projectKey}/shipping-methods/key={key}
Method: POST
OAuth 2.0 Scopes: manage_orders:{projectKey} or manage_shipping_methods:{projectKey}
Response Representation: ShippingMethod
Fields:

version - Number - Required
The expected version of the ShippingMethod on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
actions - Array of UpdateAction - Required
The list of update actions to be performed on the ShippingMethod.

Update actions

Set Localized Description

Set Key

action - String - "setKey"
key - String - Optional
If key is absent or null, the existing key, if any, will be removed.

Change Name

action - String - "changeName"
name - String - Required

Set Localized Name

action - String - "setLocalizedName"
localizedName - LocalizedString - Optional

Set Description

This action is deprecated in favor of setLocalizedDescription.

action - String - "setDescription"
description - String - Optional

Set Localized Description

action - String - "setLocalizedDescription"
localizedDescription - LocalizedString - Optional

Change TaxCategory

action - String - "changeTaxCategory"
taxCategory - ResourceIdentifier of a TaxCategory - Required

Change isDefault

action - String - "changeIsDefault"
isDefault - Boolean - Required
Only one ShippingMethod in a project can be default.

Add ShippingRate

action - String - "addShippingRate"
zone - ResourceIdentifier for a Zone - Required
shippingRate - ShippingRateDraft - Required

Remove ShippingRate

action - String - "removeShippingRate"
zone - ResourceIdentifier for a Zone - Required
shippingRate - ShippingRateDraft - Required

Add Zone

action - String - "addZone"
zone - ResourceIdentifier for a Zone - Required

Remove Zone

action - String - "removeZone"
zone - ResourceIdentifier for a Zone - Required

Set Predicate

action - String - "setPredicate"
predicate - String - Optional
A valid Cart predicate. If predicate is absent or null, it is removed if it exists.

Set CustomType

This action sets or removes the custom type for an existing shipping method.

action - String - "setCustomType"
type - ResourceIdentifier of a Type - Optional
If absent, the custom type and any existing CustomFields are removed.
fields - * - Optional
A valid JSON object, based on the FieldDefinitions of the Type. Sets the custom fields to this value.
This action overwrites any existing custom type and fields.

Set CustomField

This action sets, overwrites, or removes any existing custom field for an existing shipping method.

action - String - "setCustomField"
name - String - Required
value - Value - Optional
If value is absent or null, this field will be removed if it exists. Trying to remove a field that does not exist will fail with an InvalidOperation error. If value is provided, set the value of the field defined by the name.

Delete ShippingMethod

Delete ShippingMethod by ID

Endpoint: /{projectKey}/shipping-methods/{id}
Method: DELETE
OAuth 2.0 Scopes: manage_orders:{projectKey} or manage_shipping_methods:{projectKey}
Response Representation: ShippingMethod
Query Parameters:

version - Number - Required
The expected version of the ShippingMethod to be deleted. If the expected version does not match the actual version, a 409 Conflict will be returned.

Delete ShippingMethod by Key

Endpoint: /{projectKey}/shipping-methods/key={key}
Method: DELETE
OAuth 2.0 Scopes: manage_orders:{projectKey} or manage_shipping_methods:{projectKey}
Response Representation: ShippingMethod
Query Parameters:

version - Number - Required
The expected version of the ShippingMethod to be deleted. If the expected version does not match the actual version, a 409 Conflict will be returned.