Shipping Methods

Shipping Methods define where orders can be shipped and what the costs are.

Representations

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
  • description - String - Optional
  • 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.

ShippingMethodDraft

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

  • name - String - Required
  • key - String - Optional
  • description - String - Optional
  • taxCategory - ResourceIdentifier to 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.

ShippingRate

  • price - Money
  • freeAbove - Money - Optional
    The shipping is free if the order total (the sum of line item prices) exceeds the freeAbove value.
  • 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 order total (the sum of line item prices) exceeds the freeAbove value.
  • 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
Example
{
  "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

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:

  • CartValue is used when the shipping rate maps to the sum of the line item prices
  • CartClassification is used when the shipping rate maps to an abstract cart categorization expressed through a string, e.g. green, yellow, red or light, medium, heavy
  • CartScore is used when the shipping rate maps to an abstract cart categorization expressed through an integer, e.g. 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 CartValue:

{
  "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 CartClassification:

{
  "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 CartScore:

{
  "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 CartClassification
  • 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
OAuth2 Scopes: view_orders:{projectKey} or manage_my_orders:{projectKey}
Response Representation: ShippingMethod

Get ShippingMethod by Key

Endpoint: /{projectKey}/shippping-methods/key={key}
Method: GET
OAuth2 Scopes: view_orders:{projectKey} or manage_my_orders:{projectKey}
Response Representation: ShippingMethod

Query ShippingMethods

Endpoint: /{projectKey}/shipping-methods
Method: GET
OAuth2 Scopes: view_orders:{projectKey} or manage_my_orders:{projectKey}
Response Representation: PagedQueryResult with the results array of ShippingMethod
Query Parameters:

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
Method: GET
OAuth2 Scopes: view_orders:{projectKey} or manage_my_orders:{projectKey}
Response Representation: 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
Method: GET
OAuth2 Scopes: view_orders:{projectKey} or manage_my_orders:{projectKey}
Response Representation: 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 Method: GET OAuth2 Scopes: view_orders:{projectKey} Response Representation: Array of ShippingMethod Query Parameters:

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

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

Create ShippingMethod

Endpoint: /{projectKey}/shipping-methods
Method: POST
OAuth2 Scopes: manage_orders:{projectKey}
Request Representation: ShippingMethodDraft
Response Representation: ShippingMethod

Update ShippingMethod

Update ShippingMethod by ID

Endpoint: /{projectKey}/shipping-methods/{id}
Method: POST
OAuth2 Scopes: manage_orders:{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
OAuth2 Scopes: manage_orders:{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
Please find below the individual update actions provided on this endpoint.


Set Key

  • action - String - "setKey"
  • key - String - Optional
    If key is absent or null, it is removed if it exists.

Change Name

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

Set Description

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

Change TaxCategory

Change isDefault

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

Add ShippingRate

Remove ShippingRate

Add Zone

  • action - String - "addZone"
  • zone - Reference to a Zone - Required

Remove Zone

  • action - String - "removeZone"
  • zone - Reference to 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.

Delete ShippingMethod

Delete ShippingMethod by ID

Endpoint: /{projectKey}/shipping-methods/{id}
Method: DELETE
OAuth2 Scopes: manage_orders:{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
OAuth2 Scopes: manage_orders:{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.