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”.

ShippingMethodDraft

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

ShippingRate

ShippingRateDraft

ZoneRate

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

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:

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:

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

CartClassification

CartScore with fixed price

Sets a fixed price for a score.

CartScore with function

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

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.

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:

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:

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:

Update ShippingMethod by Key

Endpoint: /{projectKey}/shipping-methods/key={key}
Method: POST
OAuth2 Scopes: manage_orders:{projectKey}
Response Representation: ShippingMethod
Fields:

Update Actions
Please find below the individual update actions provided on this endpoint.


Set Key

Change Name

Set Description

Change TaxCategory

Change isDefault

Add ShippingRate

Remove ShippingRate

Add Zone

Remove Zone

Set Predicate

Delete ShippingMethod

Delete ShippingMethod by ID

Endpoint: /{projectKey}/shipping-methods/{id}
Method: DELETE
OAuth2 Scopes: manage_orders:{projectKey}
Response Representation: ShippingMethod
Query Parameters:

Delete ShippingMethod by Key

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