Documentation

Shipping Methods

With Shipping Methods you can specify which shipping services (like DHL, DHL Express, and UPS) 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.

Information icon

Free shipping can be defined via the freeAbove value in the ShippingRate, but it can also be achieved using a Cart Discount on the CartDiscountShippingCostTarget. We highly recommend using either of these methods, but not both together.

Representations

ShippingMethod

id​
String​

Unique identifier of the ShippingMethod.

version​
Int​

Current version of the ShippingMethod.

key​
String​

User-defined unique identifier of the ShippingMethod.

MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
name​
String​

Name of the ShippingMethod.

localizedName​
LocalizedString​

Localized name of the ShippingMethod.

localizedDescription​
LocalizedString​

Localized description of the ShippingMethod.

taxCategory​
TaxCategoryReference​

TaxCategory of all ZoneRates of the ShippingMethod.

zoneRates​
Array of ZoneRate​

Defines ShippingRates (prices) for specific Zones.

isDefault​
Boolean​

If true this ShippingMethod is the Project's default ShippingMethod.

predicate​
String​

Valid Cart predicate to select a ShippingMethod for a Cart.

custom​
CustomFields​

Custom Fields of the ShippingMethod.

createdAt​
DateTime​

Date and time (UTC) the ShippingMethod was initially created.

createdBy​BETA
CreatedBy​

Present on resources created after 1 February 2019 except for events not tracked.

lastModifiedAt​
DateTime​

Date and time (UTC) the ShippingMethod was last updated.

lastModifiedBy​BETA
LastModifiedBy​

Present on resources created after 1 February 2019 except for events not tracked.

Example: json
{
  "id" : "eb8991df-2dcd-4e24-83fe-5df46ec04422",
  "version" : 3,
  "name" : "DHL",
  "description" : "Standard delivery",
  "taxCategory" : {
    "typeId" : "tax-category",
    "id" : "5a21f15b-34f8-4b7f-9407-d1eb82a73eba"
  },
  "zoneRates" : [ {
    "zone" : {
      "typeId" : "zone",
      "id" : "5cb532be-c680-43ab-ba14-b664bb03dc35"
    },
    "shippingRates" : [ {
      "price" : {
        "type" : "centPrecision",
        "fractionDigits" : 2,
        "currencyCode" : "EUR",
        "centAmount" : 570
      },
      "tiers" : [ ]
    } ]
  }, {
    "zone" : {
      "typeId" : "zone",
      "id" : "ebe01381-82be-4e63-9993-d1eb8f8e588b"
    },
    "shippingRates" : [ {
      "price" : {
        "type" : "centPrecision",
        "fractionDigits" : 2,
        "currencyCode" : "USD",
        "centAmount" : 990
      },
      "tiers" : [ ]
    } ]
  } ],
  "isDefault" : false,
  "createdAt" : "2015-01-21T09:22:04.320Z",
  "lastModifiedAt" : "2016-02-24T13:36:56.748Z"
}
Clipboard icon

ShippingMethodDraft

key​
String​

User-defined unique identifier for the ShippingMethod.

MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
name​
String​

Name of the ShippingMethod.

localizedName​
LocalizedString​

Localized name of the ShippingMethod.

localizedDescription​
LocalizedString​

Localized description of the ShippingMethod.

taxCategory​
TaxCategoryResourceIdentifier​

TaxCategory for all ZoneRates of the ShippingMethod.

zoneRates​
Array of ZoneRateDraft​

Defines ShippingRates (prices) for specific zones.

isDefault​
Boolean​

If true the ShippingMethod will be the Project's default ShippingMethod.

predicate​
String​

Valid Cart predicate to select a ShippingMethod for a Cart.

custom​
CustomFieldsDraft​

Custom Fields for the ShippingMethod.

Example: json
{
  "name" : "DHL",
  "description" : "Standard delivery",
  "taxCategory" : {
    "typeId" : "tax-category",
    "id" : "5a21f15b-34f8-4b7f-9407-d1eb82a73eba"
  },
  "zoneRates" : [ {
    "zone" : {
      "typeId" : "zone",
      "id" : "5cb532be-c680-43ab-ba14-b664bb03dc35"
    },
    "shippingRates" : [ {
      "price" : {
        "currencyCode" : "EUR",
        "centAmount" : 570
      }
    } ]
  }, {
    "zone" : {
      "typeId" : "zone",
      "id" : "ebe01381-82be-4e63-9993-d1eb8f8e588b"
    },
    "shippingRates" : [ {
      "price" : {
        "currencyCode" : "USD",
        "centAmount" : 990
      }
    } ]
  } ],
  "isDefault" : false
}
Clipboard icon

ShippingMethodPagedQueryResponse

PagedQueryResult with results containing an array of ShippingMethod.

limit​
Int​

Number of results requested.

count​
Int​

Actual number of results returned.

total​
Int​

Total number of results matching the query. This number is an estimation that is not strongly consistent. This field is returned by default. For improved performance, calculating this field can be deactivated by using the query parameter withTotal=false. When the results are filtered with a Query Predicate, total is subject to a limit.

offset​
Int​

Number of elements skipped.

results​
Array of ShippingMethod​

Shipping Methods matching the query.

Example: json
{
  "limit" : 20,
  "offset" : 0,
  "count" : 1,
  "total" : 1,
  "results" : [ {
    "id" : "eb8991df-2dcd-4e24-83fe-5df46ec04422",
    "version" : 3,
    "name" : "DHL",
    "description" : "Standard delivery",
    "taxCategory" : {
      "typeId" : "tax-category",
      "id" : "5a21f15b-34f8-4b7f-9407-d1eb82a73eba"
    },
    "zoneRates" : [ {
      "zone" : {
        "typeId" : "zone",
        "id" : "5cb532be-c680-43ab-ba14-b664bb03dc35"
      },
      "shippingRates" : [ {
        "price" : {
          "type" : "centPrecision",
          "fractionDigits" : 2,
          "currencyCode" : "EUR",
          "centAmount" : 570
        },
        "tiers" : [ ]
      } ]
    }, {
      "zone" : {
        "typeId" : "zone",
        "id" : "ebe01381-82be-4e63-9993-d1eb8f8e588b"
      },
      "shippingRates" : [ {
        "price" : {
          "type" : "centPrecision",
          "fractionDigits" : 2,
          "currencyCode" : "USD",
          "centAmount" : 990
        },
        "tiers" : [ ]
      } ]
    } ],
    "isDefault" : false,
    "createdAt" : "2015-01-21T09:22:04.320Z",
    "lastModifiedAt" : "2016-02-24T13:36:56.748Z"
  } ]
}
Clipboard icon

ShippingMethodReference

Reference to a ShippingMethod.

id​
String​

Unique identifier of the referenced ShippingMethod.

typeId​
String​
"shipping-method"

References a ShippingMethod.

obj​
ShippingMethod​

Contains the representation of the expanded ShippingMethod. Only present in responses to requests with Reference Expansion for ShippingMethods.

ShippingMethodResourceIdentifier

ResourceIdentifier to a ShippingMethod.

id​
String​

Unique identifier of the referenced ShippingMethod. Either id or key is required.

key​
String​

User-defined unique identifier of the referenced ShippingMethod. Either id or key is required.

typeId​
String​
"shipping-method"

References a ShippingMethod.

ZoneRate

Defines shipping rates in different currencies for a specific Zone.

zone​
ZoneReference​

Zone for which the shipping rates are valid.

shippingRates​
Array of ShippingRate​

Shipping rates defined per currency.

ZoneRateDraft

zone​
ZoneResourceIdentifier​

Sets the Zone for which the shippng rates are valid.

shippingRates​
Array of ShippingRateDraft​

Shipping rates for the currencies configured in the Project. The array must not contain two ShippingRates with the same CurrencyCode.

ShippingRate

price​
TypedMoney​

Currency amount of the ShippingRate.

freeAbove​
TypedMoney​

Shipping is free if the sum of the (Custom) Line Item Prices reaches the specified value.

isMatching​
Boolean​

true if the ShippingRate matches given Cart or Location. Only appears in response to requests for Get ShippingMethods for a Cart or Get ShippingMethods for a Location.

tiers​
Array of ShippingRatePriceTier​

Price tiers for the ShippingRate.

ShippingRateDraft

price​
Money​

Money value of the ShippingRate.

freeAbove​
Money​

Shipping is free if the sum of the (Custom) Line Item Prices reaches the specified value.

tiers​
Array of ShippingRatePriceTier​

Price tiers for the ShippingRate.

ShippingRatePriceTier

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 ShippingRate is used.

Information icon

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

The API supports three different kinds of ShippingRatePriceTiers: CartValueTier, CartClassificationTier, and CartScoreTier.

For more comprehensive examples about usage of those, refer to Using Tiered Shipping Rates.

CartValueTier

Used when the ShippingRate maps to the sum of LineItem Prices. The value of the Cart is used to select a tier. If chosen, it is not possible to set a value for the shippingRateInput on the Cart. Tiers contain the centAmount (a value of 100 in the currency USD corresponds to $ 1.00), and start at 1.'

type​
String​
"CartValue"
minimumCentAmount​
Int​

Minimum total price of a Cart for which a shipping rate applies.

price​
Money​

Fixed shipping rate Price for a CartValue.

isMatching​
Boolean​

Appears in response to Get ShippingMethods for a Cart if the shipping rate matches the search query.

Example: json
{
  "type" : "CartValue",
  "minimumCentAmount" : 5000,
  "price" : {
    "currencyCode" : "EUR",
    "centAmount" : 300
  }
}
Clipboard icon

CartClassificationTier

Used when the ShippingRate maps to an abstract Cart categorization expressed by strings (for example, Light, Medium, or Heavy).

type​
String​
"CartClassification"
value​
String​

key selected from the values of the CartClassificationType configured in the Project.

price​
Money​

Fixed shipping rate for the selected classification.

isMatching​
Boolean​

Appears in response to Get ShippingMethods for a Cart if the shipping rate matches the search query.

Example: json
{
  "type" : "CartClassification",
  "value" : "Heavy",
  "price" : {
    "currencyCode" : "EUR",
    "centAmount" : 5000
  }
}
Clipboard icon

CartScoreTier

Used when the ShippingRate maps to an abstract Cart categorization expressed by integers (such as shipping scores or weight ranges). Either price or priceFunction is required.

type​
String​
"CartScore"
score​
Int​

Abstract value for categorizing a Cart. The range starts at 0. The default price covers 0, tiers start at 1. See Using Tiered Shipping Rates for details and examples.

price​
Money​

Defines a fixed price for the score.

priceFunction​
PriceFunction​

Dynamically calculates a Price for a range of scores.

isMatching​
Boolean​

Appears in response to Get ShippingMethods for a Cart if the shipping rate matches the search query.

Example: pricejson
{
  "type" : "CartScore",
  "score" : 5,
  "price" : {
    "currencyCode" : "USD",
    "centAmount" : 750
  }
}
Clipboard icon
Example: priceFunctionjson
{
  "type" : "CartScore",
  "score" : 15,
  "priceFunction" : {
    "currencyCode" : "USD",
    "function" : "(50 * x) + 750"
  }
}
Clipboard icon

PriceFunction

currencyCode​
CurrencyCode​

Currency code compliant to ISO 4217External link icon.

function​
String​

To calculate a Price based on the score, use +, -, * and parentheses. The score is inserted with x. The function returns the cent amount.

For example, to charge $1.99 for a score of 1, $3.99 for a score of 2, $5.99 for a score of 3 and onwards, the function is: (200 * x) - 1). To charge $4.50, $6.00, and $7.50 for express shipping, the function is: (150 * x) + 300.

Get ShippingMethod

Get ShippingMethod by ID

GET
https://api.{region}.commercetools.com/{projectKey}/shipping-methods/{id}
OAuth 2.0 Scopes:
view_orders:{projectKey}, view_shipping_methods:{projectKey}, manage_my_orders:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

id
​
String
​

id of the ShippingMethod.

Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200ShippingMethod
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/shipping-methods/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: ShippingMethodjson
{
  "id" : "eb8991df-2dcd-4e24-83fe-5df46ec04422",
  "version" : 3,
  "name" : "DHL",
  "description" : "Standard delivery",
  "taxCategory" : {
    "typeId" : "tax-category",
    "id" : "5a21f15b-34f8-4b7f-9407-d1eb82a73eba"
  },
  "zoneRates" : [ {
    "zone" : {
      "typeId" : "zone",
      "id" : "5cb532be-c680-43ab-ba14-b664bb03dc35"
    },
    "shippingRates" : [ {
      "price" : {
        "type" : "centPrecision",
        "fractionDigits" : 2,
        "currencyCode" : "EUR",
        "centAmount" : 570
      },
      "tiers" : [ ]
    } ]
  }, {
    "zone" : {
      "typeId" : "zone",
      "id" : "ebe01381-82be-4e63-9993-d1eb8f8e588b"
    },
    "shippingRates" : [ {
      "price" : {
        "type" : "centPrecision",
        "fractionDigits" : 2,
        "currencyCode" : "USD",
        "centAmount" : 990
      },
      "tiers" : [ ]
    } ]
  } ],
  "isDefault" : false,
  "createdAt" : "2015-01-21T09:22:04.320Z",
  "lastModifiedAt" : "2016-02-24T13:36:56.748Z"
}
Clipboard icon

Get ShippingMethod by Key

GET
https://api.{region}.commercetools.com/{projectKey}/shipping-methods/key={key}
OAuth 2.0 Scopes:
view_orders:{projectKey}, view_shipping_methods:{projectKey}, manage_my_orders:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

key
​
String
​

key of the ShippingMethod.

Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200ShippingMethod
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/shipping-methods/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: ShippingMethodjson
{
  "id" : "eb8991df-2dcd-4e24-83fe-5df46ec04422",
  "version" : 3,
  "name" : "DHL",
  "description" : "Standard delivery",
  "taxCategory" : {
    "typeId" : "tax-category",
    "id" : "5a21f15b-34f8-4b7f-9407-d1eb82a73eba"
  },
  "zoneRates" : [ {
    "zone" : {
      "typeId" : "zone",
      "id" : "5cb532be-c680-43ab-ba14-b664bb03dc35"
    },
    "shippingRates" : [ {
      "price" : {
        "type" : "centPrecision",
        "fractionDigits" : 2,
        "currencyCode" : "EUR",
        "centAmount" : 570
      },
      "tiers" : [ ]
    } ]
  }, {
    "zone" : {
      "typeId" : "zone",
      "id" : "ebe01381-82be-4e63-9993-d1eb8f8e588b"
    },
    "shippingRates" : [ {
      "price" : {
        "type" : "centPrecision",
        "fractionDigits" : 2,
        "currencyCode" : "USD",
        "centAmount" : 990
      },
      "tiers" : [ ]
    } ]
  } ],
  "isDefault" : false,
  "createdAt" : "2015-01-21T09:22:04.320Z",
  "lastModifiedAt" : "2016-02-24T13:36:56.748Z"
}
Clipboard icon

Query ShippingMethods

GET
https://api.{region}.commercetools.com/{projectKey}/shipping-methods
OAuth 2.0 Scopes:
view_orders:{projectKey}, view_shipping_methods:{projectKey}, manage_my_orders:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

Query parameters:
where
​
QueryPredicate
​
The parameter can be passed multiple times.
/^var[.][a-zA-Z0-9]+$/
​
Any string parameter matching this regular expression
​

Predicate parameter values.

The parameter can be passed multiple times.
sort
​
Sort
​
The parameter can be passed multiple times.
expand
​
Expansion
​
The parameter can be passed multiple times.
limit
​
Int
​

Number of results requested.

offset
​
Int
​

Number of elements skipped.

withTotal
​
Boolean
​

Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.

Response:
200ShippingMethodPagedQueryResponse
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/shipping-methods -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: ShippingMethodPagedQueryResponsejson
{
  "limit" : 20,
  "offset" : 0,
  "count" : 1,
  "total" : 1,
  "results" : [ {
    "id" : "eb8991df-2dcd-4e24-83fe-5df46ec04422",
    "version" : 3,
    "name" : "DHL",
    "description" : "Standard delivery",
    "taxCategory" : {
      "typeId" : "tax-category",
      "id" : "5a21f15b-34f8-4b7f-9407-d1eb82a73eba"
    },
    "zoneRates" : [ {
      "zone" : {
        "typeId" : "zone",
        "id" : "5cb532be-c680-43ab-ba14-b664bb03dc35"
      },
      "shippingRates" : [ {
        "price" : {
          "type" : "centPrecision",
          "fractionDigits" : 2,
          "currencyCode" : "EUR",
          "centAmount" : 570
        },
        "tiers" : [ ]
      } ]
    }, {
      "zone" : {
        "typeId" : "zone",
        "id" : "ebe01381-82be-4e63-9993-d1eb8f8e588b"
      },
      "shippingRates" : [ {
        "price" : {
          "type" : "centPrecision",
          "fractionDigits" : 2,
          "currencyCode" : "USD",
          "centAmount" : 990
        },
        "tiers" : [ ]
      } ]
    } ],
    "isDefault" : false,
    "createdAt" : "2015-01-21T09:22:04.320Z",
    "lastModifiedAt" : "2016-02-24T13:36:56.748Z"
  } ]
}
Clipboard icon

Get ShippingMethods for a Cart

GET
https://api.{region}.commercetools.com/{projectKey}/shipping-methods/matching-cart

Retrieves all the ShippingMethods that can ship to the shipping address of the given Cart. Each ShippingMethod contains exactly one ShippingRate with the flag isMatching set to true. This ShippingRate is used when the ShippingMethod is added to the Cart.

OAuth 2.0 Scopes:
view_orders:{projectKey}, view_shipping_methods:{projectKey}, manage_my_orders:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
cartId
​
String
​

ID of the Cart with a shipping address set.

Response:
200ShippingMethodPagedQueryResponse
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/shipping-methods/matching-cart?cartId={cartId} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: ShippingMethodPagedQueryResponsejson
{
  "limit" : 20,
  "offset" : 0,
  "count" : 1,
  "total" : 1,
  "results" : [ {
    "id" : "eb8991df-2dcd-4e24-83fe-5df46ec04422",
    "version" : 3,
    "name" : "DHL",
    "description" : "Standard delivery",
    "taxCategory" : {
      "typeId" : "tax-category",
      "id" : "5a21f15b-34f8-4b7f-9407-d1eb82a73eba"
    },
    "zoneRates" : [ {
      "zone" : {
        "typeId" : "zone",
        "id" : "5cb532be-c680-43ab-ba14-b664bb03dc35"
      },
      "shippingRates" : [ {
        "price" : {
          "type" : "centPrecision",
          "fractionDigits" : 2,
          "currencyCode" : "EUR",
          "centAmount" : 570
        },
        "tiers" : [ ]
      } ]
    }, {
      "zone" : {
        "typeId" : "zone",
        "id" : "ebe01381-82be-4e63-9993-d1eb8f8e588b"
      },
      "shippingRates" : [ {
        "price" : {
          "type" : "centPrecision",
          "fractionDigits" : 2,
          "currencyCode" : "USD",
          "centAmount" : 990
        },
        "tiers" : [ ]
      } ]
    } ],
    "isDefault" : false,
    "createdAt" : "2015-01-21T09:22:04.320Z",
    "lastModifiedAt" : "2016-02-24T13:36:56.748Z"
  } ]
}
Clipboard icon

Get ShippingMethods for a Cart and Location

GET
https://api.{region}.commercetools.com/{projectKey}/shipping-methods/matching-cart-location

Retrieves all the ShippingMethods that can ship to the given Location with a predicate that matches the given Cart. Each ShippingMethod contains exactly one ShippingRate with the flag isMatching set to true. This ShippingRate is used when the ShippingMethod is added to the Cart.

OAuth 2.0 Scopes:
view_orders:{projectKey}, view_shipping_methods:{projectKey}, manage_my_orders:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
country
​
String
​

A two-digit country code as per ISO 3166-1 alpha-2External link icon.

state
​
String
​

Name of the state, for example, Colorado.

cartId
​
String
​

ID of the Cart.

Response:
200ShippingMethodPagedQueryResponse
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/shipping-methods/matching-cart-location?country={country}&cartId={cartId} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: ShippingMethodPagedQueryResponsejson
{
  "limit" : 20,
  "offset" : 0,
  "count" : 1,
  "total" : 1,
  "results" : [ {
    "id" : "eb8991df-2dcd-4e24-83fe-5df46ec04422",
    "version" : 3,
    "name" : "DHL",
    "description" : "Standard delivery",
    "taxCategory" : {
      "typeId" : "tax-category",
      "id" : "5a21f15b-34f8-4b7f-9407-d1eb82a73eba"
    },
    "zoneRates" : [ {
      "zone" : {
        "typeId" : "zone",
        "id" : "5cb532be-c680-43ab-ba14-b664bb03dc35"
      },
      "shippingRates" : [ {
        "price" : {
          "type" : "centPrecision",
          "fractionDigits" : 2,
          "currencyCode" : "EUR",
          "centAmount" : 570
        },
        "tiers" : [ ]
      } ]
    }, {
      "zone" : {
        "typeId" : "zone",
        "id" : "ebe01381-82be-4e63-9993-d1eb8f8e588b"
      },
      "shippingRates" : [ {
        "price" : {
          "type" : "centPrecision",
          "fractionDigits" : 2,
          "currencyCode" : "USD",
          "centAmount" : 990
        },
        "tiers" : [ ]
      } ]
    } ],
    "isDefault" : false,
    "createdAt" : "2015-01-21T09:22:04.320Z",
    "lastModifiedAt" : "2016-02-24T13:36:56.748Z"
  } ]
}
Clipboard icon

Get ShippingMethods for a Cart in a Store by ID

GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/shipping-methods/matching-cart

Retrieves all the ShippingMethods that can ship to the shipping address of the given Cart in a given Store. Each ShippingMethod contains exactly one ShippingRate with the flag isMatching set to true. This ShippingRate is used when the ShippingMethod is added to the Cart.

OAuth 2.0 Scopes:
view_orders:{projectKey}, view_orders:{projectKey}:{storeKey}, manage_customers:{projectKey}:{storeKey}, view_shipping_methods:{projectKey}, manage_my_orders:{projectKey}, manage_my_orders:{projectKey}:{storeKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

storeKey
​
String
​

key of the Store.

Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
cartId
​
String
​

ID of the Cart with a shipping address set.

Response:
200ShippingMethodPagedQueryResponse
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/shipping-methods/matching-cart?cartId={cartId} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: ShippingMethodPagedQueryResponsejson
{
  "limit" : 20,
  "offset" : 0,
  "count" : 1,
  "total" : 1,
  "results" : [ {
    "id" : "eb8991df-2dcd-4e24-83fe-5df46ec04422",
    "version" : 3,
    "name" : "DHL",
    "description" : "Standard delivery",
    "taxCategory" : {
      "typeId" : "tax-category",
      "id" : "5a21f15b-34f8-4b7f-9407-d1eb82a73eba"
    },
    "zoneRates" : [ {
      "zone" : {
        "typeId" : "zone",
        "id" : "5cb532be-c680-43ab-ba14-b664bb03dc35"
      },
      "shippingRates" : [ {
        "price" : {
          "type" : "centPrecision",
          "fractionDigits" : 2,
          "currencyCode" : "EUR",
          "centAmount" : 570
        },
        "tiers" : [ ]
      } ]
    }, {
      "zone" : {
        "typeId" : "zone",
        "id" : "ebe01381-82be-4e63-9993-d1eb8f8e588b"
      },
      "shippingRates" : [ {
        "price" : {
          "type" : "centPrecision",
          "fractionDigits" : 2,
          "currencyCode" : "USD",
          "centAmount" : 990
        },
        "tiers" : [ ]
      } ]
    } ],
    "isDefault" : false,
    "createdAt" : "2015-01-21T09:22:04.320Z",
    "lastModifiedAt" : "2016-02-24T13:36:56.748Z"
  } ]
}
Clipboard icon

Get ShippingMethods for a Location

GET
https://api.{region}.commercetools.com/{projectKey}/shipping-methods/matching-location

Retrieves all the ShippingMethods that can ship to the given Location. ShippingMethods that have a predicate defined are automatically disqualified. If the currency parameter is given, then the ShippingMethods must also have a rate defined in the specified currency. Each ShippingMethod contains at least one ShippingRate with the flag isMatching set to true. If the currency parameter is given, exactly one ShippingRate will contain it.

OAuth 2.0 Scopes:
view_orders:{projectKey}, view_shipping_methods:{projectKey}, manage_my_orders:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

Query parameters:
sort
​
Sort
​
The parameter can be passed multiple times.
expand
​
Expansion
​
The parameter can be passed multiple times.
country
​
String
​

A two-digit country code as per ISO 3166-1 alpha-2External link icon.

state
​
String
​

Name of the state, for example, Colorado.

currency
​
String
​

The currency code compliant to ISO 4217External link icon.

Response:
200ShippingMethodPagedQueryResponse
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/shipping-methods/matching-location?country={country} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: ShippingMethodPagedQueryResponsejson
{
  "limit" : 20,
  "offset" : 0,
  "count" : 1,
  "total" : 1,
  "results" : [ {
    "id" : "eb8991df-2dcd-4e24-83fe-5df46ec04422",
    "version" : 3,
    "name" : "DHL",
    "description" : "Standard delivery",
    "taxCategory" : {
      "typeId" : "tax-category",
      "id" : "5a21f15b-34f8-4b7f-9407-d1eb82a73eba"
    },
    "zoneRates" : [ {
      "zone" : {
        "typeId" : "zone",
        "id" : "5cb532be-c680-43ab-ba14-b664bb03dc35"
      },
      "shippingRates" : [ {
        "price" : {
          "type" : "centPrecision",
          "fractionDigits" : 2,
          "currencyCode" : "EUR",
          "centAmount" : 570
        },
        "tiers" : [ ]
      } ]
    }, {
      "zone" : {
        "typeId" : "zone",
        "id" : "ebe01381-82be-4e63-9993-d1eb8f8e588b"
      },
      "shippingRates" : [ {
        "price" : {
          "type" : "centPrecision",
          "fractionDigits" : 2,
          "currencyCode" : "USD",
          "centAmount" : 990
        },
        "tiers" : [ ]
      } ]
    } ],
    "isDefault" : false,
    "createdAt" : "2015-01-21T09:22:04.320Z",
    "lastModifiedAt" : "2016-02-24T13:36:56.748Z"
  } ]
}
Clipboard icon

Get ShippingMethods for an OrderEdit

GET
https://api.{region}.commercetools.com/{projectKey}/shipping-methods/matching-orderedit

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

If the OrderEdit preview cannot be generated, an EditPreviewFailed error is returned.

OAuth 2.0 Scopes:
view_orders:{projectKey}, view_shipping_methods:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

Query parameters:
orderEditId
​
String
​

The ID of the OrderEdit.

country
​
String
​

A two-digit country code as per ISO 3166-1 alpha-2External link icon.

state
​
String
​

Name of the state, for example, Colorado.

Response:
200ShippingMethodPagedQueryResponse
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/shipping-methods/matching-orderedit?orderEditId={orderEditId}&country={country} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: ShippingMethodPagedQueryResponsejson
{
  "limit" : 20,
  "offset" : 0,
  "count" : 1,
  "total" : 1,
  "results" : [ {
    "id" : "eb8991df-2dcd-4e24-83fe-5df46ec04422",
    "version" : 3,
    "name" : "DHL",
    "description" : "Standard delivery",
    "taxCategory" : {
      "typeId" : "tax-category",
      "id" : "5a21f15b-34f8-4b7f-9407-d1eb82a73eba"
    },
    "zoneRates" : [ {
      "zone" : {
        "typeId" : "zone",
        "id" : "5cb532be-c680-43ab-ba14-b664bb03dc35"
      },
      "shippingRates" : [ {
        "price" : {
          "type" : "centPrecision",
          "fractionDigits" : 2,
          "currencyCode" : "EUR",
          "centAmount" : 570
        },
        "tiers" : [ ]
      } ]
    }, {
      "zone" : {
        "typeId" : "zone",
        "id" : "ebe01381-82be-4e63-9993-d1eb8f8e588b"
      },
      "shippingRates" : [ {
        "price" : {
          "type" : "centPrecision",
          "fractionDigits" : 2,
          "currencyCode" : "USD",
          "centAmount" : 990
        },
        "tiers" : [ ]
      } ]
    } ],
    "isDefault" : false,
    "createdAt" : "2015-01-21T09:22:04.320Z",
    "lastModifiedAt" : "2016-02-24T13:36:56.748Z"
  } ]
}
Clipboard icon

Create ShippingMethod

POST
https://api.{region}.commercetools.com/{projectKey}/shipping-methods
OAuth 2.0 Scopes:
manage_orders:{projectKey}, manage_shipping_methods:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Request Body:ShippingMethodDraftasapplication/json
Response:
201ShippingMethodasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/shipping-methods -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "name" : "DHL",
  "description" : "Standard delivery",
  "taxCategory" : {
    "typeId" : "tax-category",
    "id" : "5a21f15b-34f8-4b7f-9407-d1eb82a73eba"
  },
  "zoneRates" : [ {
    "zone" : {
      "typeId" : "zone",
      "id" : "5cb532be-c680-43ab-ba14-b664bb03dc35"
    },
    "shippingRates" : [ {
      "price" : {
        "currencyCode" : "EUR",
        "centAmount" : 570
      }
    } ]
  }, {
    "zone" : {
      "typeId" : "zone",
      "id" : "ebe01381-82be-4e63-9993-d1eb8f8e588b"
    },
    "shippingRates" : [ {
      "price" : {
        "currencyCode" : "USD",
        "centAmount" : 990
      }
    } ]
  } ],
  "isDefault" : false
}
DATA
Clipboard icon
201 Response Example: ShippingMethodjson
{
  "id" : "eb8991df-2dcd-4e24-83fe-5df46ec04422",
  "version" : 3,
  "name" : "DHL",
  "description" : "Standard delivery",
  "taxCategory" : {
    "typeId" : "tax-category",
    "id" : "5a21f15b-34f8-4b7f-9407-d1eb82a73eba"
  },
  "zoneRates" : [ {
    "zone" : {
      "typeId" : "zone",
      "id" : "5cb532be-c680-43ab-ba14-b664bb03dc35"
    },
    "shippingRates" : [ {
      "price" : {
        "type" : "centPrecision",
        "fractionDigits" : 2,
        "currencyCode" : "EUR",
        "centAmount" : 570
      },
      "tiers" : [ ]
    } ]
  }, {
    "zone" : {
      "typeId" : "zone",
      "id" : "ebe01381-82be-4e63-9993-d1eb8f8e588b"
    },
    "shippingRates" : [ {
      "price" : {
        "type" : "centPrecision",
        "fractionDigits" : 2,
        "currencyCode" : "USD",
        "centAmount" : 990
      },
      "tiers" : [ ]
    } ]
  } ],
  "isDefault" : false,
  "createdAt" : "2015-01-21T09:22:04.320Z",
  "lastModifiedAt" : "2016-02-24T13:36:56.748Z"
}
Clipboard icon

Update ShippingMethod

Update ShippingMethod by ID

POST
https://api.{region}.commercetools.com/{projectKey}/shipping-methods/{id}
OAuth 2.0 Scopes:
manage_orders:{projectKey}, manage_shipping_methods:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

id
​
String
​

id of the ShippingMethod.

Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Request Body:
application/json
version​
Int​

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 ShippingMethodUpdateAction​

Update actions to be performed on the ShippingMethod.

Response:
200ShippingMethodasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/shipping-methods/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 1,
  "actions" : [ {
    "action" : "changeName",
    "name" : "New Name"
  } ]
}
DATA
Clipboard icon
200 Response Example: ShippingMethodjson
{
  "id" : "eb8991df-2dcd-4e24-83fe-5df46ec04422",
  "version" : 3,
  "name" : "DHL",
  "description" : "Standard delivery",
  "taxCategory" : {
    "typeId" : "tax-category",
    "id" : "5a21f15b-34f8-4b7f-9407-d1eb82a73eba"
  },
  "zoneRates" : [ {
    "zone" : {
      "typeId" : "zone",
      "id" : "5cb532be-c680-43ab-ba14-b664bb03dc35"
    },
    "shippingRates" : [ {
      "price" : {
        "type" : "centPrecision",
        "fractionDigits" : 2,
        "currencyCode" : "EUR",
        "centAmount" : 570
      },
      "tiers" : [ ]
    } ]
  }, {
    "zone" : {
      "typeId" : "zone",
      "id" : "ebe01381-82be-4e63-9993-d1eb8f8e588b"
    },
    "shippingRates" : [ {
      "price" : {
        "type" : "centPrecision",
        "fractionDigits" : 2,
        "currencyCode" : "USD",
        "centAmount" : 990
      },
      "tiers" : [ ]
    } ]
  } ],
  "isDefault" : false,
  "createdAt" : "2015-01-21T09:22:04.320Z",
  "lastModifiedAt" : "2016-02-24T13:36:56.748Z"
}
Clipboard icon

Update ShippingMethod by Key

POST
https://api.{region}.commercetools.com/{projectKey}/shipping-methods/key={key}
OAuth 2.0 Scopes:
manage_orders:{projectKey}, manage_shipping_methods:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

key
​
String
​

key of the ShippingMethod.

Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Request Body:
application/json
version​
Int​

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 ShippingMethodUpdateAction​

Update actions to be performed on the ShippingMethod.

Response:
200ShippingMethodasapplication/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/shipping-methods/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 1,
  "actions" : [ {
    "action" : "changeName",
    "name" : "New Name"
  } ]
}
DATA
Clipboard icon
200 Response Example: ShippingMethodjson
{
  "id" : "eb8991df-2dcd-4e24-83fe-5df46ec04422",
  "version" : 3,
  "name" : "DHL",
  "description" : "Standard delivery",
  "taxCategory" : {
    "typeId" : "tax-category",
    "id" : "5a21f15b-34f8-4b7f-9407-d1eb82a73eba"
  },
  "zoneRates" : [ {
    "zone" : {
      "typeId" : "zone",
      "id" : "5cb532be-c680-43ab-ba14-b664bb03dc35"
    },
    "shippingRates" : [ {
      "price" : {
        "type" : "centPrecision",
        "fractionDigits" : 2,
        "currencyCode" : "EUR",
        "centAmount" : 570
      },
      "tiers" : [ ]
    } ]
  }, {
    "zone" : {
      "typeId" : "zone",
      "id" : "ebe01381-82be-4e63-9993-d1eb8f8e588b"
    },
    "shippingRates" : [ {
      "price" : {
        "type" : "centPrecision",
        "fractionDigits" : 2,
        "currencyCode" : "USD",
        "centAmount" : 990
      },
      "tiers" : [ ]
    } ]
  } ],
  "isDefault" : false,
  "createdAt" : "2015-01-21T09:22:04.320Z",
  "lastModifiedAt" : "2016-02-24T13:36:56.748Z"
}
Clipboard icon

Update actions

Set Key

action​
String​
"setKey"
key​
String​

If key is absent or null, the existing key, if any, will be removed.

MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
Example: json
{
  "action" : "setKey",
  "key" : "keyString"
}
Clipboard icon

Change Name

action​
String​
"changeName"
name​
String​

Value to set. Must not be empty.

Example: json
{
  "action" : "changeName",
  "name" : "nameString"
}
Clipboard icon

Set Localized Name

action​
String​
"setLocalizedName"
localizedName​
LocalizedString​

Value to set. If empty, any existing value will be removed.

Example: json
{
  "action" : "setLocalizedName",
  "localizedName" : {
    "en" : "localizedNameString"
  }
}
Clipboard icon

Set Localized Description

action​
String​
"setLocalizedDescription"
localizedDescription​
LocalizedString​

Value to set. If empty, any existing value will be removed.

Example: json
{
  "action" : "setLocalizedDescription",
  "localizedDescription" : {
    "en" : "localizedDescriptionString"
  }
}
Clipboard icon

Change TaxCategory

action​
String​
"changeTaxCategory"
taxCategory​
TaxCategoryResourceIdentifier​

Value to set.

Example: json
{
  "action" : "changeTaxCategory",
  "taxCategory" : {
    "id" : "{{tax-category-id}}",
    "typeId" : "tax-category"
  }
}
Clipboard icon

Change isDefault

action​
String​
"changeIsDefault"
isDefault​
Boolean​

Value to set. Only one ShippingMethod can be default in a Project.

Example: json
{
  "action" : "changeIsDefault",
  "isDefault" : false
}
Clipboard icon

Add ShippingRate

action​
String​
"addShippingRate"
zone​
ZoneResourceIdentifier​

Zone to which the ShippingRate should be added.

shippingRate​
ShippingRateDraft​

Value to add to shippingRates.

Example: json
{
  "action" : "addShippingRate",
  "zone" : {
    "typeId" : "zone",
    "id" : "{{zone-id}}"
  },
  "shippingRate" : {
    "price" : {
      "currencyCode" : "EUR",
      "centAmount" : 4000
    }
  }
}
Clipboard icon

Remove ShippingRate

action​
String​
"removeShippingRate"
zone​
ZoneResourceIdentifier​

Zone from which the ShippingRate should be removed.

shippingRate​
ShippingRateDraft​

Value to remove from shippingRates.

Example: json
{
  "action" : "removeShippingRate",
  "zone" : {
    "typeId" : "zone",
    "id" : "{{zone-id}}"
  },
  "shippingRate" : {
    "price" : {
      "currencyCode" : "EUR",
      "centAmount" : 4000
    }
  }
}
Clipboard icon

Add Zone

action​
String​
"addZone"
zone​
ZoneResourceIdentifier​

Value to add to zoneRates.

Example: json
{
  "action" : "addZone",
  "zone" : {
    "typeId" : "zone",
    "id" : "{{zone-id}}"
  }
}
Clipboard icon

Remove Zone

action​
String​
"removeZone"
zone​
ZoneResourceIdentifier​

Value to remove from zoneRates.

Example: json
{
  "action" : "removeZone",
  "zone" : {
    "typeId" : "zone",
    "id" : "{{zone-id}}"
  }
}
Clipboard icon

Set Predicate

action​
String​
"setPredicate"
predicate​
String​

A valid Cart predicate. If predicate is absent or null, it is removed if it exists.

Example: json
{
  "action" : "setPredicate",
  "predicate" : "1=1"
}
Clipboard icon

Set CustomType

action​
String​
"setCustomType"
type​
TypeResourceIdentifier​

Defines the Type that extends the ShippingMethod with Custom Fields. If absent, any existing Type and Custom Fields are removed from the ShippingMethod.

fields​
FieldContainer​

Sets the Custom Fields fields for the ShippingMethod.

Example: json
{
  "action" : "setCustomType",
  "type" : {
    "id" : "{{type-id}}",
    "typeId" : "type"
  },
  "fields" : {
    "exampleStringTypeField" : "TextString"
  }
}
Clipboard icon

Set CustomField

This action sets, overwrites, or removes any existing Custom Field for an existing ShippingMethod.

action​
String​
"setCustomField"
name​
String​

Name of the Custom Field.

value​
CustomFieldValue​

If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.

Example: json
{
  "action" : "setCustomField",
  "name" : "ExampleStringTypeField",
  "value" : "TextString"
}
Clipboard icon

Delete ShippingMethod

Warning icon

It is not possible to delete a ShippingMethod while it is referenced by at least one Order or Cart.

Delete ShippingMethod by ID

DELETE
https://api.{region}.commercetools.com/{projectKey}/shipping-methods/{id}
OAuth 2.0 Scopes:
manage_orders:{projectKey}, manage_shipping_methods:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

id
​
String
​

id of the ShippingMethod.

Query parameters:
version
​
Int
​

Last seen version of the resource.

expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200ShippingMethod
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/shipping-methods/{id}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: ShippingMethodjson
{
  "id" : "eb8991df-2dcd-4e24-83fe-5df46ec04422",
  "version" : 3,
  "name" : "DHL",
  "description" : "Standard delivery",
  "taxCategory" : {
    "typeId" : "tax-category",
    "id" : "5a21f15b-34f8-4b7f-9407-d1eb82a73eba"
  },
  "zoneRates" : [ {
    "zone" : {
      "typeId" : "zone",
      "id" : "5cb532be-c680-43ab-ba14-b664bb03dc35"
    },
    "shippingRates" : [ {
      "price" : {
        "type" : "centPrecision",
        "fractionDigits" : 2,
        "currencyCode" : "EUR",
        "centAmount" : 570
      },
      "tiers" : [ ]
    } ]
  }, {
    "zone" : {
      "typeId" : "zone",
      "id" : "ebe01381-82be-4e63-9993-d1eb8f8e588b"
    },
    "shippingRates" : [ {
      "price" : {
        "type" : "centPrecision",
        "fractionDigits" : 2,
        "currencyCode" : "USD",
        "centAmount" : 990
      },
      "tiers" : [ ]
    } ]
  } ],
  "isDefault" : false,
  "createdAt" : "2015-01-21T09:22:04.320Z",
  "lastModifiedAt" : "2016-02-24T13:36:56.748Z"
}
Clipboard icon

Delete ShippingMethod by Key

DELETE
https://api.{region}.commercetools.com/{projectKey}/shipping-methods/key={key}
OAuth 2.0 Scopes:
manage_orders:{projectKey}, manage_shipping_methods:{projectKey}
Path parameters:
region
​
String
​

Region in which the Project is hosted.

projectKey
​
String
​

key of the Project.

key
​
String
​

key of the ShippingMethod.

Query parameters:
version
​
Int
​

Last seen version of the resource.

expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200ShippingMethod
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/shipping-methods/key={key}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: ShippingMethodjson
{
  "id" : "eb8991df-2dcd-4e24-83fe-5df46ec04422",
  "version" : 3,
  "name" : "DHL",
  "description" : "Standard delivery",
  "taxCategory" : {
    "typeId" : "tax-category",
    "id" : "5a21f15b-34f8-4b7f-9407-d1eb82a73eba"
  },
  "zoneRates" : [ {
    "zone" : {
      "typeId" : "zone",
      "id" : "5cb532be-c680-43ab-ba14-b664bb03dc35"
    },
    "shippingRates" : [ {
      "price" : {
        "type" : "centPrecision",
        "fractionDigits" : 2,
        "currencyCode" : "EUR",
        "centAmount" : 570
      },
      "tiers" : [ ]
    } ]
  }, {
    "zone" : {
      "typeId" : "zone",
      "id" : "ebe01381-82be-4e63-9993-d1eb8f8e588b"
    },
    "shippingRates" : [ {
      "price" : {
        "type" : "centPrecision",
        "fractionDigits" : 2,
        "currencyCode" : "USD",
        "centAmount" : 990
      },
      "tiers" : [ ]
    } ]
  } ],
  "isDefault" : false,
  "createdAt" : "2015-01-21T09:22:04.320Z",
  "lastModifiedAt" : "2016-02-24T13:36:56.748Z"
}
Clipboard icon