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.

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

ShippingRatePriceTier-CartValueTier-CartClassificationTier-CartScoreTier-PriceFunction

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_-]+$
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.

name
String

Name of the ShippingMethod.

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.

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

ShippingMethodDraft

key
String

User-defined unique identifier for the ShippingMethod.

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

Name of the ShippingMethod.

localizedName

Localized name of the ShippingMethod.

localizedDescription

Localized description of the ShippingMethod.

taxCategory

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

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

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

zone

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

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

Price tiers for the ShippingRate.

ShippingRateDraft

price

Money value of the ShippingRate.

freeAbove

Shipping is free 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 shippingRateInput field on the Cart.

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

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

200ShippingMethod

Request Example:cURL
curl -X GET https://api.{region}.commercetools.com/{projectKey}/shipping-methods/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Response 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"
}

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:

200ShippingMethod

Request Example:cURL
curl -X GET https://api.{region}.commercetools.com/{projectKey}/shipping-methods/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Response 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"
}

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:

200ShippingMethodPagedQueryResponse

Request Example:cURL
curl -X GET https://api.{region}.commercetools.com/{projectKey}/shipping-methods -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Response 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"
} ]
}

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

ID of the Cart with a shipping address set.

Response:

200ShippingMethodPagedQueryResponse

Request Example:cURL
curl -X GET https://api.{region}.commercetools.com/{projectKey}/shipping-methods/matching-cart?cartId={cartId} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Response 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"
} ]
}

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

ID of the Cart with a shipping address set.

Response:

200ShippingMethodPagedQueryResponse

Request Example:cURL
curl -X GET https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/shipping-methods/matching-cart?cartId={cartId} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Response 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"
} ]
}

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. 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
String
state
String

Name of the state, for example, Colorado.

currency
String
Response:

200ShippingMethodPagedQueryResponse

Request Example:cURL
curl -X GET https://api.{region}.commercetools.com/{projectKey}/shipping-methods/matching-location?country={country} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Response 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"
} ]
}

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. In case the OrderEdit preview cannot be created an EditPreviewFailed error is raised.

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

Name of the state, for example, Colorado.

Response:

200ShippingMethodPagedQueryResponse

Request Example:cURL
curl -X GET https://api.{region}.commercetools.com/{projectKey}/shipping-methods/matching-orderedit?orderEditId={orderEditId}&country={country} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Response 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"
} ]
}

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:ShippingMethodDraft
Response:

201ShippingMethod

Request Example:cURL
curl -X POST 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
Response 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"
}

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

200ShippingMethod

Request Example:cURL
curl -X POST 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
Response 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"
}

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

200ShippingMethod

Request Example:cURL
curl -X POST 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
Response 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"
}

Update actions

Set Key

key
String

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

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

Change Name

action
String
"changeName"
name
String

Value to set. 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 Description

action
String
"setDescription"
description
String

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

Example: json
{
"action" : "setDescription",
"description" : "descriptionString"
}

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

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

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

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

Value to add to zoneRates.

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

Remove Zone

action
String
"removeZone"
zone

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 CustomType

action
String
"setCustomType"
type

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" : {
"examplaryStringTypeField" : "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. Trying to remove a field that does not exist will fail with an InvalidOperation error. If value is provided, it is set for the field defined by name.

Example: json
{
"action" : "setCustomField",
"name" : "ExamplaryStringTypeField",
"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:
expand
The parameter can be passed multiple times.
version
Int

Last seen version of the resource.

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

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

Last seen version of the resource.

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