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.

Learn more about Shipping Methods in our self-paced Shipping methods module.

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: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
name
String

Unique name of the ShippingMethod within a Project.

localizedName

Localized name of the ShippingMethod.

localizedDescription

Localized description of the ShippingMethod.

taxCategory

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

Custom Fields of the ShippingMethod.

createdAt

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

createdByBETA

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

lastModifiedAt

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

lastModifiedByBETA

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",
"localizedDescription": {
"en": "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"
}

ShippingMethodDraft

key
String

User-defined unique identifier for the ShippingMethod.

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

Unique name for the ShippingMethod within a Project.

localizedName

Localized name of the ShippingMethod.

localizedDescription

Localized description of the ShippingMethod.

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

Custom Fields for the ShippingMethod.

Example: json
{
"name": "DHL",
"localizedDescription": {
"en": "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
}

ShippingMethodPagedQueryResponse

PagedQueryResult with results containing an array of ShippingMethod.

limit
Int
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",
"localizedDescription": {
"en": "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"
}
]
}

ShippingMethodReference

id
String

Unique identifier of the referenced ShippingMethod.

typeId
String
"shipping-method"

References a ShippingMethod.

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

ShippingMethodResourceIdentifier

ResourceIdentifier to a ShippingMethod. Either id or key is required. If both are set, an InvalidJsonInput error is returned.

id
String

Unique identifier of the referenced ShippingMethod. Required if key is absent.

key
String

User-defined unique identifier of the referenced ShippingMethod. Required if id is absent.

typeId
String
"shipping-method"

References a ShippingMethod.

ZoneRate

Defines shipping rates in different currencies for a specific Zone.

zone

Zone for which the shipping rates are valid.

shippingRates
Array of ShippingRate

Shipping rates defined per currency.

ZoneRateDraft

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

Currency amount of the ShippingRate.

freeAbove

Free shipping is applied 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

Price tiers for the ShippingRate.

ShippingRateDraft

price

Money value of the ShippingRate.

freeAbove

Free shipping is applied if the sum of the (Custom) Line Item Prices reaches the specified value.

tiers

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.

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.

To learn more, see 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

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

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

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

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 Tiered shipping rates for details and examples.

price

Defines a fixed price for the score.

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
}
}
Example: priceFunctionjson
{
"type": "CartScore",
"score": 15,
"priceFunction": {
"currencyCode": "USD",
"function": "(50 * x) + 750"
}
}

PriceFunction

currencyCode

Currency code compliant to ISO 4217.

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
The parameter can be passed multiple times.
Response:
200ShippingMethodasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/shipping-methods/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: ShippingMethodjson
{
"id": "eb8991df-2dcd-4e24-83fe-5df46ec04422",
"version": 3,
"name": "DHL",
"localizedDescription": {
"en": "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"
}

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
The parameter can be passed multiple times.
Response:
200ShippingMethodasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/shipping-methods/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: ShippingMethodjson
{
"id": "eb8991df-2dcd-4e24-83fe-5df46ec04422",
"version": 3,
"name": "DHL",
"localizedDescription": {
"en": "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"
}

Get matching Shipping Methods

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
The parameter can be passed multiple times.
cartId
String

ID of the Cart with a shipping address set.

Response:
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/shipping-methods/matching-cart?cartId={cartId} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: ShippingMethodPagedQueryResponsejson
{
"limit": 20,
"offset": 0,
"count": 1,
"total": 1,
"results": [
{
"id": "eb8991df-2dcd-4e24-83fe-5df46ec04422",
"version": 3,
"name": "DHL",
"localizedDescription": {
"en": "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"
}
]
}

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
The parameter can be passed multiple times.
expand
The parameter can be passed multiple times.
country

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

state
String

Name of the state, for example, Colorado.

currency
String

The currency code compliant to ISO 4217.

Response:
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/shipping-methods/matching-location?country={country} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: ShippingMethodPagedQueryResponsejson
{
"limit": 20,
"offset": 0,
"count": 1,
"total": 1,
"results": [
{
"id": "eb8991df-2dcd-4e24-83fe-5df46ec04422",
"version": 3,
"name": "DHL",
"localizedDescription": {
"en": "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"
}
]
}

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
The parameter can be passed multiple times.
country

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

state
String

Name of the state, for example, Colorado.

cartId
String

ID of the Cart.

Response:
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}'
200 Response Example: ShippingMethodPagedQueryResponsejson
{
"limit": 20,
"offset": 0,
"count": 1,
"total": 1,
"results": [
{
"id": "eb8991df-2dcd-4e24-83fe-5df46ec04422",
"version": 3,
"name": "DHL",
"localizedDescription": {
"en": "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"
}
]
}

for a Cart in Store

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
The parameter can be passed multiple times.
cartId
String

ID of the Cart with a shipping address set.

Response:
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}'
200 Response Example: ShippingMethodPagedQueryResponsejson
{
"limit": 20,
"offset": 0,
"count": 1,
"total": 1,
"results": [
{
"id": "eb8991df-2dcd-4e24-83fe-5df46ec04422",
"version": 3,
"name": "DHL",
"localizedDescription": {
"en": "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"
}
]
}

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

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

state
String

Name of the state, for example, Colorado.

Response:
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}'
200 Response Example: ShippingMethodPagedQueryResponsejson
{
"limit": 20,
"offset": 0,
"count": 1,
"total": 1,
"results": [
{
"id": "eb8991df-2dcd-4e24-83fe-5df46ec04422",
"version": 3,
"name": "DHL",
"localizedDescription": {
"en": "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"
}
]
}

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
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
The parameter can be passed multiple times.
expand
The parameter can be passed multiple times.
limit
Int
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:
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/shipping-methods -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: ShippingMethodPagedQueryResponsejson
{
"limit": 20,
"offset": 0,
"count": 1,
"total": 1,
"results": [
{
"id": "eb8991df-2dcd-4e24-83fe-5df46ec04422",
"version": 3,
"name": "DHL",
"localizedDescription": {
"en": "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"
}
]
}

Check if ShippingMethod exists

Check if ShippingMethod exists by ID

HEAD
https://api.{region}.commercetools.com/{projectKey}/shipping-methods/{id}

Checks if a ShippingMethod exists for a given id. Returns a 200 OK status if the ShippingMethod exists or a 404 Not Found otherwise.

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.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/shipping-methods/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if ShippingMethod exists by Key

HEAD
https://api.{region}.commercetools.com/{projectKey}/shipping-methods/key={key}

Checks if a ShippingMethod exists for a given key. Returns a 200 OK status if the ShippingMethod exists or a 404 Not Found otherwise.

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.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/shipping-methods/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if ShippingMethod exists by Query Predicate

HEAD
https://api.{region}.commercetools.com/{projectKey}/shipping-methods

Checks if a ShippingMethod exists for a given Query Predicate. Returns a 200 OK status if any ShippingMethods match the Query Predicate or a 404 Not Found otherwise.

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
The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/shipping-methods -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Check if matching ShippingMethod exists

for a Cart

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

Checks if a ShippingMethod exists for the given Cart. Returns a 200 OK status if the ShippingMethod exists or a 404 Not Found otherwise.

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:
cartId
String

ID of the Cart with a shipping address set.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/shipping-methods/matching-cart?cartId={cartId} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

for a Location

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

Checks if a ShippingMethod that can ship to the given Location exists. Returns a 200 OK status if the ShippingMethod exists or a 404 Not Found otherwise.

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:
country

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

state
String

Name of the state, for example, Colorado.

currency
String

The currency code compliant to ISO 4217.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/shipping-methods/matching-location?country={country} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

for a Cart and Location

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

Checks if a ShippingMethod that can ship to the given Location exists for the given Cart. Returns a 200 OK status if the ShippingMethod exists or a 404 Not Found otherwise.

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:
country

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

state
String

Name of the state, for example, Colorado.

cartId
String

ID of the Cart.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/shipping-methods/matching-cart-location?country={country}&cartId={cartId} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

for a Cart in Store

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

Checks if a ShippingMethod that can ship to the shipping address of the given Cart exists in the given Store. Returns a 200 OK status if the ShippingMethod exists or a 404 Not Found otherwise.

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:
cartId
String

ID of the Cart with a shipping address set.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/shipping-methods/matching-cart?cartId={cartId} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

for an OrderEdit

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

Checks if a ShippingMethod that can ship to the given Location exists for the given OrderEdit. Returns a 200 OK status if the ShippingMethod exists or a 404 Not Found otherwise.

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

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

state
String

Name of the state, for example, Colorado.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/shipping-methods/matching-orderedit?orderEditId={orderEditId}&country={country} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

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
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",
"localizedDescription" : {
"en" : "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
201 Response Example: ShippingMethodjson
{
"id": "eb8991df-2dcd-4e24-83fe-5df46ec04422",
"version": 3,
"name": "DHL",
"localizedDescription": {
"en": "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"
}

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

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
200 Response Example: ShippingMethodjson
{
"id": "eb8991df-2dcd-4e24-83fe-5df46ec04422",
"version": 3,
"name": "DHL",
"localizedDescription": {
"en": "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"
}

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

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
200 Response Example: ShippingMethodjson
{
"id": "eb8991df-2dcd-4e24-83fe-5df46ec04422",
"version": 3,
"name": "DHL",
"localizedDescription": {
"en": "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"
}

Update actions

Set Key

action
String
"setKey"
key
String

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

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

Change Name

action
String
"changeName"
name
String

Unique value to set within a Project. Must not be empty.

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

Set Localized Name

action
String
"setLocalizedName"
localizedName

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

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

Set Localized Description

action
String
"setLocalizedDescription"
localizedDescription

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

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

Change TaxCategory

action
String
"changeTaxCategory"

Value to set.

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

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
}

Add ShippingRate

action
String
"addShippingRate"

Zone to which the ShippingRate should be added.

shippingRate

Value to add to shippingRates.

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

Remove ShippingRate

action
String
"removeShippingRate"

Zone from which the ShippingRate should be removed.

shippingRate

Value to remove from shippingRates.

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

Add Zone

action
String
"addZone"

Value to add to zoneRates.

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

Remove Zone

action
String
"removeZone"

Value to remove from zoneRates.

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

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

Set Custom Type

action
String
"setCustomType"

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

fields

Sets the Custom Fields fields for the ShippingMethod.

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

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

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

Delete ShippingMethod

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
The parameter can be passed multiple times.
Response:
200ShippingMethodasapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/shipping-methods/{id}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: ShippingMethodjson
{
"id": "eb8991df-2dcd-4e24-83fe-5df46ec04422",
"version": 3,
"name": "DHL",
"localizedDescription": {
"en": "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"
}

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
The parameter can be passed multiple times.
Response:
200ShippingMethodasapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/shipping-methods/key={key}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
200 Response Example: ShippingMethodjson
{
"id": "eb8991df-2dcd-4e24-83fe-5df46ec04422",
"version": 3,
"name": "DHL",
"localizedDescription": {
"en": "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"
}