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: 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 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",
"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: 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 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
}
Clipboard icon

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

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

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

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

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.

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

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

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

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

PriceFunction

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

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

ID of the Cart with a shipping address set.

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

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

ID of the Cart with a shipping address set.

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

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.

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
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
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
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
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
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: 2MaxLength: 256Pattern: ^[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

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

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"

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

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

Add Zone

action
String
"addZone"

Value to add to zoneRates.

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

Remove Zone

action
String
"removeZone"

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"

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

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