[go: up one dir, main page]
Documentation

Shipping Methods

With Shipping Methods you can specify which shipping services (like DHL, DHL Express, and UPS) you want to provide to your customers for deliveries to different areas of the world at rates you can define. Furthermore, you can extend this resource according to your needs to store custom content, metadata, or to model your workflow.

A maximum number of 100 Shipping Methods can be created per Project. Learn more about this limit.
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: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
name​
String​
Unique name of the ShippingMethod within a Project.
localizedName​
LocalizedString​

Localized name of the ShippingMethod.

localizedDescription​
LocalizedString​

Localized description of the ShippingMethod.

taxCategory​
TaxCategoryReference​
TaxCategory of all ZoneRates of the ShippingMethod.
zoneRates​
Array of ZoneRate​
Defines ShippingRates (prices) for specific Zones.
active​
Boolean​

Indicates if the ShippingMethod is active.

If true, the ShippingMethod can be used during the creation or update of a Cart or Order.
Default: true​
isDefault​
Boolean​
If true, this ShippingMethod is the Project's default ShippingMethod. When retrieving matching Shipping Methods, it is returned as the first item in the array. This flag does not automatically apply the Shipping Method to Carts.
predicate​
String​
Valid Cart predicate to select a ShippingMethod for a Cart.
custom​
CustomFields​

Custom Fields of the ShippingMethod.

createdAt​
DateTime​

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

createdBy​BETA
CreatedBy​

IDs and references that created the ShippingMethod.

lastModifiedAt​
DateTime​

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

lastModifiedBy​BETA
LastModifiedBy​

IDs and references that last modified the ShippingMethod.

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": []
        }
      ]
    }
  ],
  "active": true,
  "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: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
name​
String​
Unique name for the ShippingMethod within a Project.
localizedName​
LocalizedString​

Localized name of the ShippingMethod.

localizedDescription​
LocalizedString​

Localized description of the ShippingMethod.

taxCategory​
TaxCategoryResourceIdentifier​
TaxCategory for all ZoneRates of the ShippingMethod.
zoneRates​
Array of ZoneRateDraft​
Defines ShippingRates (prices) for specific zones.
active​
Boolean​
If set to true, the ShippingMethod can be used during the creation or update of a Cart or Order.
Default: true​
isDefault​
Boolean​
If set to true, the ShippingMethod will be the Project's default ShippingMethod. When retrieving matching Shipping Methods, it is returned as the first item in the array. This flag does not automatically apply the Shipping Method to Carts.
predicate​
String​
Valid Cart predicate to select a ShippingMethod for a Cart.
custom​
CustomFieldsDraft​

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​
Number of results requested.
Default: 20​Minimum: 0​Maximum: 500​
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.
Default: 0​Maximum: 10000​
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": []
            }
          ]
        }
      ],
      "active": true,
      "isDefault": false,
      "createdAt": "2015-01-21T09:22:04.320Z",
      "lastModifiedAt": "2016-02-24T13:36:56.748Z"
    }
  ]
}

ShippingMethodReference

Reference to a ShippingMethod.
id​
String​
Unique identifier of the referenced ShippingMethod.
typeId​
ReferenceTypeId​
shipping-method

Type of referenced resource.

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

ShippingMethodKeyReference

Used by the Import API to identify a ShippingMethod.
key​
String​

User-defined unique identifier of the referenced ShippingMethod.

typeId​
ReferenceType​
shipping-method

Type of referenced resource.

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​
ReferenceTypeId​
shipping-method
Type of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource.

ZoneRate

Defines shipping rates in different currencies for a specific Zone.
zone​
ZoneReference​
Zone for which the shipping rates are valid.
shippingRates​
Array of ShippingRate​

Shipping rates defined per currency.

ZoneRateDraft

zone​
ZoneResourceIdentifier​
Sets the Zone for which the shippng rates are valid.
shippingRates​
Array of ShippingRateDraft​
Shipping rates for the currencies configured in the Project. The array must not contain two ShippingRates with the same CurrencyCode.

ShippingRate

price​
CentPrecisionMoney​

Currency amount of the ShippingRate.

freeAbove​
CentPrecisionMoney​
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​
Array of ShippingRatePriceTier​

Price tiers for the ShippingRate.

ShippingRateDraft

price​
Money​

Money value of the ShippingRate.

freeAbove​
Money​
Free shipping is applied if the sum of the (Custom) Line Item Prices reaches the specified value.
tiers​
Array of ShippingRatePriceTier​

Price tiers for the ShippingRate.

ShippingRatePriceTier

A price tier is selected instead of the default price when a certain threshold or specific Cart value is reached. If no tiered price is suitable for the Cart, the base price of the ShippingRate is used.

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

The API supports three different types of ShippingRatePriceTiers:

CartValue
CartValueTier based on the total value of the cart.
CartClassification
CartClassificationTier based on classifications assigned to the cart.
CartScore
CartScoreTier based on a scoring system applied to the cart.
To learn more, see Tiered shipping rates.

CartValueTier

This type is equivalent to ShippingRateCartValuePriceTier in the GraphQL API.
The ShippingRate maps to the value of the Cart and is used to select a tier. The value of the Cart is the sum of all Line Item totals and Custom Line Item totals (via the totalPrice field) after any Product Discounts and Cart Discounts have been applied. 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​
ShippingRateTierType​
CartValue
minimumCentAmount​
Int​

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

price​
Money​

Fixed shipping rate Price for a CartValue.

isMatching​
Boolean​
Appears in response to Get ShippingMethods for a Cart if the shipping rate matches the search query.
Example: json
{
  "type": "CartValue",
  "minimumCentAmount": 5000,
  "price": {
    "currencyCode": "EUR",
    "centAmount": 300
  }
}

CartClassificationTier

This type is equivalent to ShippingRateCartClassificationPriceTier in the GraphQL API.
The ShippingRate maps to an abstract Cart categorization expressed by strings (for example, Light, Medium, or Heavy).
type​
ShippingRateTierType​
CartClassification
value​
String​
key selected from the values of the CartClassificationType configured in the Project.
price​
Money​

Fixed shipping rate for the selected classification.

isMatching​
Boolean​
Appears in response to Get ShippingMethods for a Cart if the shipping rate matches the search query.
Example: json
{
  "type": "CartClassification",
  "value": "Heavy",
  "price": {
    "currencyCode": "EUR",
    "centAmount": 5000
  }
}

CartScoreTier

This type is equivalent to ShippingRateCartScorePriceTier in the GraphQL API.
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​
ShippingRateTierType​
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​
Money​
Defines a fixed price for the score.
priceFunction​
PriceFunction​

Dynamically calculates a Price for a range of scores.

isMatching​
Boolean​
Appears in response to Get ShippingMethods for a Cart if the shipping rate matches the search query.
Example: pricejson
{
  "type": "CartScore",
  "score": 5,
  "price": {
    "currencyCode": "USD",
    "centAmount": 750
  }
}
Example: priceFunctionjson
{
  "type": "CartScore",
  "score": 15,
  "priceFunction": {
    "currencyCode": "USD",
    "function": "(50 * x) + 750"
  }
}

PriceFunction

currencyCode​
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}
Retrieves a ShippingMethod with the provided id.
OAuth 2.0 Scopes:
view_orders:{projectKey}view_shipping_methods:{projectKey}manage_my_orders:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
id
​
String
​
id of the ShippingMethod.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200

ShippingMethod

as
application/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": []
        }
      ]
    }
  ],
  "active": true,
  "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}
Retrieves a ShippingMethod with the provided key.
OAuth 2.0 Scopes:
view_orders:{projectKey}view_shipping_methods:{projectKey}manage_my_orders:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
key
​
String
​
key of the ShippingMethod.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200

ShippingMethod

as
application/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": []
        }
      ]
    }
  ],
  "active": true,
  "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 the active ShippingMethods that can ship to the shipping address of the provided 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.
If a matching ShippingMethod has isDefault set to true, it is returned as the first item in the array.
OAuth 2.0 Scopes:
view_orders:{projectKey}view_shipping_methods:{projectKey}manage_my_orders:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
cartId
​
String
​

ID of the Cart with a shipping address set.

Response:
200

ShippingMethodPagedQueryResponse

as
application/json
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": []
            }
          ]
        }
      ],
      "active": true,
      "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 the active ShippingMethods that can ship to the provided Location.

The following applies:

  • ShippingMethods that have a predicate defined are automatically disqualified.
  • If the currency parameter is provided, 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 provided, exactly one ShippingRate will contain it.
  • If a matching ShippingMethod has isDefault set to true, it is returned as the first item in the array.
OAuth 2.0 Scopes:
view_orders:{projectKey}view_shipping_methods:{projectKey}manage_my_orders:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Query parameters:
sort
​
Sort
​
The parameter can be passed multiple times.
expand
​
Expansion
​
The parameter can be passed multiple times.
country
​
CountryCode
​
A two-digit country code as per ISO 3166-1 alpha-2.
Pattern: ^[A-Z]{2}$​
state
​
String
​

Name of the state, for example, Colorado.

currency
​
String
​
The currency code compliant to ISO 4217.
Response:
200

ShippingMethodPagedQueryResponse

as
application/json
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": []
            }
          ]
        }
      ],
      "active": true,
      "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 the active ShippingMethods that can ship to the provided Location with a predicate that matches the provided 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.
If a matching ShippingMethod has isDefault set to true, it is returned as the first item in the array.
OAuth 2.0 Scopes:
view_orders:{projectKey}view_shipping_methods:{projectKey}manage_my_orders:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
country
​
CountryCode
​
A two-digit country code as per ISO 3166-1 alpha-2.
Pattern: ^[A-Z]{2}$​
state
​
String
​

Name of the state, for example, Colorado.

cartId
​
String
​

ID of the Cart.

Response:
200

ShippingMethodPagedQueryResponse

as
application/json
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": []
            }
          ]
        }
      ],
      "active": true,
      "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 the active ShippingMethods that can ship to the shipping address of the provided Cart in a 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.
If a matching ShippingMethod has isDefault set to true, it is returned as the first item in the array.
OAuth 2.0 Scopes:
view_orders:{projectKey}view_orders:{projectKey}:{storeKey}manage_customers:{projectKey}:{storeKey}view_shipping_methods:{projectKey}manage_my_orders:{projectKey}manage_my_orders:{projectKey}:{storeKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
storeKey
​
String
​
key of the Store.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
cartId
​
String
​

ID of the Cart with a shipping address set.

Response:
200

ShippingMethodPagedQueryResponse

as
application/json
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": []
            }
          ]
        }
      ],
      "active": true,
      "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 the active ShippingMethods that can ship to the provided Location for an OrderEdit.
If a matching ShippingMethod has isDefault set to true, it is returned as the first item in the array.
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
​
CountryCode
​
A two-digit country code as per ISO 3166-1 alpha-2.
Pattern: ^[A-Z]{2}$​
state
​
String
​

Name of the state, for example, Colorado.

Response:
200

ShippingMethodPagedQueryResponse

as
application/json
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": []
            }
          ]
        }
      ],
      "active": true,
      "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

Retrieves all ShippingMethods in the Project.

OAuth 2.0 Scopes:
view_orders:{projectKey}view_shipping_methods:{projectKey}manage_my_orders:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Query parameters:
where
​
QueryPredicate
​
The parameter can be passed multiple times.
sort
​
Sort
​
The parameter can be passed multiple times.
expand
​
Expansion
​
The parameter can be passed multiple times.
limit
​
Int
​
Number of results requested.
Default: 20​
Minimum: 0​
Maximum: 500​
offset
​
Int
​
Number of elements skipped.
Default: 0​
Maximum: 10000​
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.
Default: true​
var.<varName>
​
String
​
Predicate parameter values.
The parameter can be passed multiple times.
Response:
200

ShippingMethodPagedQueryResponse

as
application/json
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": []
            }
          ]
        }
      ],
      "active": true,
      "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 with the provided id. Returns a 200 OK status if the ShippingMethod exists or a Not Found error 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 with the provided key. Returns a 200 OK status if the ShippingMethod exists or a Not Found error 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 one or more ShippingMethods exist for the provided query predicate. Returns a 200 OK status if any ShippingMethods match the query predicate or a Not Found error 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
​
QueryPredicate
​
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 an active ShippingMethod exists for the provided Cart. Returns a 200 OK status if the ShippingMethod exists or a Not Found error 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 an active ShippingMethod that can ship to the provided Location exists. Returns a 200 OK status if the ShippingMethod exists or a Not Found error 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
​
CountryCode
​
A two-digit country code as per ISO 3166-1 alpha-2.
Pattern: ^[A-Z]{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 an active ShippingMethod that can ship to the provided Location exists for the provided Cart. Returns a 200 OK status if the ShippingMethod exists or a Not Found error 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
​
CountryCode
​
A two-digit country code as per ISO 3166-1 alpha-2.
Pattern: ^[A-Z]{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 an active ShippingMethod that can ship to the shipping address of the provided Cart exists in a Store. Returns a 200 OK status if the ShippingMethod exists or a Not Found error 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 an active ShippingMethod that can ship to the provided Location exists for the provided OrderEdit. Returns a 200 OK status if the ShippingMethod exists or a Not Found error 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
​
CountryCode
​
A two-digit country code as per ISO 3166-1 alpha-2.
Pattern: ^[A-Z]{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

Creates a ShippingMethod in the Project.

OAuth 2.0 Scopes:
manage_orders:{projectKey}manage_shipping_methods:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Request Body:ShippingMethodDraftasapplication/json
Response:
201

ShippingMethod

as
application/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": []
        }
      ]
    }
  ],
  "active": true,
  "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}
Updates a ShippingMethod in the Project using one or more update actions.
OAuth 2.0 Scopes:
manage_orders:{projectKey}manage_shipping_methods:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
id
​
String
​
id of the ShippingMethod.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Request Body:
application/json
version​
Int​

Expected version of the ShippingMethod on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.

actions​
Array of ShippingMethodUpdateAction​
Update actions to be performed on the ShippingMethod.
Response:
200

ShippingMethod

as
application/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": []
        }
      ]
    }
  ],
  "active": true,
  "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}
Updates a ShippingMethod in the Project using one or more update actions.
OAuth 2.0 Scopes:
manage_orders:{projectKey}manage_shipping_methods:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
key
​
String
​
key of the ShippingMethod.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Request Body:
application/json
version​
Int​

Expected version of the ShippingMethod on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.

actions​
Array of ShippingMethodUpdateAction​
Update actions to be performed on the ShippingMethod.
Response:
200

ShippingMethod

as
application/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": []
        }
      ]
    }
  ],
  "active": true,
  "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: 2​MaxLength: 256​Pattern: ^[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​
LocalizedString​

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

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

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

Change TaxCategory

action​
String​
"changeTaxCategory"
taxCategory​
TaxCategoryResourceIdentifier​

Value to set.

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

Change Active

action​
String​
"changeActive"
active​
Boolean​

Value to set.

If set to false, the ShippingMethod cannot be used during the creation or update of a Cart or Order.
Example: json
{
  "action": "changeActive",
  "active": false
}

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​
ZoneResourceIdentifier​
Zone to which the ShippingRate should be added.
shippingRate​
ShippingRateDraft​
Value to add to shippingRates.
Example: json
{
  "action": "addShippingRate",
  "zone": {
    "typeId": "zone",
    "id": "{{zone-id}}"
  },
  "shippingRate": {
    "price": {
      "currencyCode": "EUR",
      "centAmount": 4000
    }
  }
}

Remove ShippingRate

action​
String​
"removeShippingRate"
zone​
ZoneResourceIdentifier​
Zone from which the ShippingRate should be removed.
shippingRate​
ShippingRateDraft​
Value to remove from shippingRates.
Example: json
{
  "action": "removeShippingRate",
  "zone": {
    "typeId": "zone",
    "id": "{{zone-id}}"
  },
  "shippingRate": {
    "price": {
      "currencyCode": "EUR",
      "centAmount": 4000
    }
  }
}

Add Zone

action​
String​
"addZone"
zone​
ZoneResourceIdentifier​
Value to add to zoneRates.
Example: json
{
  "action": "addZone",
  "zone": {
    "typeId": "zone",
    "id": "{{zone-id}}"
  }
}

Remove Zone

action​
String​
"removeZone"
zone​
ZoneResourceIdentifier​
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"
type​
TypeResourceIdentifier​
Defines the Type that extends the ShippingMethod with Custom Fields. If absent, any existing Type and Custom Fields are removed from the ShippingMethod.
fields​
FieldContainer​
Sets the Custom Fields fields for the ShippingMethod.
Example: json
{
  "action": "setCustomType",
  "type": {
    "id": "{{type-id}}",
    "typeId": "type"
  },
  "fields": {
    "exampleStringField": "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​
CustomFieldValue​
If value is absent or null, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If value is provided, it is set for the field defined by name.
Example: json
{
  "action": "setCustomField",
  "name": "exampleStringField",
  "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}

Deletes a ShippingMethod in the Project.

OAuth 2.0 Scopes:
manage_orders:{projectKey}manage_shipping_methods:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
id
​
String
​
id of the ShippingMethod.
Query parameters:
version
​
Int
​

Last seen version of the resource.

expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200

ShippingMethod

as
application/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": []
        }
      ]
    }
  ],
  "active": true,
  "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}

Deletes a ShippingMethod in the Project.

OAuth 2.0 Scopes:
manage_orders:{projectKey}manage_shipping_methods:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
key
​
String
​
key of the ShippingMethod.
Query parameters:
version
​
Int
​

Last seen version of the resource.

expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200

ShippingMethod

as
application/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": []
        }
      ]
    }
  ],
  "active": true,
  "isDefault": false,
  "createdAt": "2015-01-21T09:22:04.320Z",
  "lastModifiedAt": "2016-02-24T13:36:56.748Z"
}