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

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

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

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: