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

ShippingMethodDraft

ShippingMethodPagedQueryResponse

ShippingMethodReference

ShippingMethodResourceIdentifier

ShippingRatePriceTier -CartValueTier -CartClassificationTier -CartScoreTier -PriceFunction

ShippingMethod

`id` String	Unique identifier of the ShippingMethod.
`version` Int	Current version of the ShippingMethod.
`key` String	User-defined unique identifier of the ShippingMethod. MinLength: `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.
`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.
`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.
`count` Int	Actual number of results returned.
`total` Int	Total number of results matching the query. This number is an estimation that is not strongly consistent. This field is returned by default. For improved performance, calculating this field can be deactivated by using the query parameter `withTotal=false`. When the results are filtered with a Query Predicate, `total` is subject to a limit.
`offset` Int	Number of elements skipped.
`results` Array of ShippingMethod	Shipping Methods matching the query.

Example: json

{
  "limit": 20,
  "offset": 0,
  "count": 1,
  "total": 1,
  "results": [
    {
      "id": "eb8991df-2dcd-4e24-83fe-5df46ec04422",
      "version": 3,
      "name": "DHL",
      "localizedDescription": {
        "en": "Standard delivery"
      },
      "taxCategory": {
        "typeId": "tax-category",
        "id": "5a21f15b-34f8-4b7f-9407-d1eb82a73eba"
      },
      "zoneRates": [
        {
          "zone": {
            "typeId": "zone",
            "id": "5cb532be-c680-43ab-ba14-b664bb03dc35"
          },
          "shippingRates": [
            {
              "price": {
                "type": "centPrecision",
                "fractionDigits": 2,
                "currencyCode": "EUR",
                "centAmount": 570
              },
              "tiers": []
            }
          ]
        },
        {
          "zone": {
            "typeId": "zone",
            "id": "ebe01381-82be-4e63-9993-d1eb8f8e588b"
          },
          "shippingRates": [
            {
              "price": {
                "type": "centPrecision",
                "fractionDigits": 2,
                "currencyCode": "USD",
                "centAmount": 990
              },
              "tiers": []
            }
          ]
        }
      ],
      "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"` References a ShippingMethod.
`obj` ShippingMethod	Contains the representation of the expanded ShippingMethod. Only present in responses to requests with Reference Expansion for ShippingMethods.

ShippingMethodResourceIdentifier

ResourceIdentifier to a ShippingMethod. 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"` References a ShippingMethod.

ZoneRate

Defines shipping rates in different currencies for a specific Zone.

`zone` ZoneReference	Zone for which the shipping rates are valid.
`shippingRates` Array of ShippingRate	Shipping rates defined per currency.

ZoneRateDraft

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

ShippingRate

`price` 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 kinds of ShippingRatePriceTiers: CartValueTier, CartClassificationTier, and CartScoreTier.

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

by ID

by Key

GET

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

OAuth 2.0 Scopes:

view_orders:{projectKey}view_shipping_methods:{projectKey}manage_my_orders:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`id` String	`id` of the ShippingMethod.

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Response:

200ShippingMethodasapplication/json

Request Example:cURL

curl --get https://api.{region}.commercetools.com/{projectKey}/shipping-methods/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

200 Response Example: ShippingMethodjson

{
  "id": "eb8991df-2dcd-4e24-83fe-5df46ec04422",
  "version": 3,
  "name": "DHL",
  "localizedDescription": {
    "en": "Standard delivery"
  },
  "taxCategory": {
    "typeId": "tax-category",
    "id": "5a21f15b-34f8-4b7f-9407-d1eb82a73eba"
  },
  "zoneRates": [
    {
      "zone": {
        "typeId": "zone",
        "id": "5cb532be-c680-43ab-ba14-b664bb03dc35"
      },
      "shippingRates": [
        {
          "price": {
            "type": "centPrecision",
            "fractionDigits": 2,
            "currencyCode": "EUR",
            "centAmount": 570
          },
          "tiers": []
        }
      ]
    },
    {
      "zone": {
        "typeId": "zone",
        "id": "ebe01381-82be-4e63-9993-d1eb8f8e588b"
      },
      "shippingRates": [
        {
          "price": {
            "type": "centPrecision",
            "fractionDigits": 2,
            "currencyCode": "USD",
            "centAmount": 990
          },
          "tiers": []
        }
      ]
    }
  ],
  "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

for a Location

for a Cart and Location

for an OrderEdit

GET

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

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

OAuth 2.0 Scopes:

view_orders:{projectKey}view_shipping_methods:{projectKey}manage_my_orders:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.

Query parameters:

`expand` Expansion	The parameter can be passed multiple times.
`cartId` String	ID of the Cart with a shipping address set.

Response:

200ShippingMethodPagedQueryResponseasapplication/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"
    }
  ]
}

Get matching Shipping Methods in Store

for a Cart

GET

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

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

OAuth 2.0 Scopes:

view_orders:{projectKey}view_orders:{projectKey}:{storeKey}manage_customers:{projectKey}:{storeKey}view_shipping_methods:{projectKey}manage_my_orders:{projectKey}manage_my_orders:{projectKey}:{storeKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`storeKey` String	`key` of the Store.

Query parameters:

`expand` Expansion	The parameter can be passed multiple times.
`cartId` String	ID of the Cart with a shipping address set.

Response:

200ShippingMethodPagedQueryResponseasapplication/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"
    }
  ]
}

Query ShippingMethods

GET

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

OAuth 2.0 Scopes:

view_orders:{projectKey}view_shipping_methods:{projectKey}manage_my_orders:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.

Query parameters:

`where` QueryPredicate	The parameter can be passed multiple times.
`/^var[.][a-zA-Z0-9]+$/` Any string parameter matching this regular expression	Predicate parameter values. The parameter can be passed multiple times.
`sort` Sort	The parameter can be passed multiple times.
`expand` Expansion	The parameter can be passed multiple times.
`limit` Int	Number of results requested.
`offset` Int	Number of elements skipped.
`withTotal` Boolean	Controls the calculation of the total number of query results. Set to `false` to improve query performance when the `total` is not needed. Default: `true`

Response:

200ShippingMethodPagedQueryResponseasapplication/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

by ID

by Key

by Query Predicate

HEAD

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

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

OAuth 2.0 Scopes:

view_orders:{projectKey}view_shipping_methods:{projectKey}manage_my_orders:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`id` String	`id` of the ShippingMethod.

Response:

200

Request Example:cURL

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

Check if matching ShippingMethod exists

for a Cart

for a Location

for a Cart and Location

for an OrderEdit

HEAD

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

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

OAuth 2.0 Scopes:

view_orders:{projectKey}view_shipping_methods:{projectKey}manage_my_orders:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.

Query parameters:

cartId

String

ID of the Cart with a shipping address set.

Response:

200

Request Example:cURL

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

Check if matching ShippingMethod exists in Store

for a Cart

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 given Cart exists in the given Store. Returns a 200 OK status if the ShippingMethod exists or a 404 Not Found otherwise.

OAuth 2.0 Scopes:

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

Create ShippingMethod

POST

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

OAuth 2.0 Scopes:

manage_orders:{projectKey}manage_shipping_methods:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Request Body:ShippingMethodDraftasapplication/json

Response:

201ShippingMethodasapplication/json

Request Example:cURL

curl https://api.{region}.commercetools.com/{projectKey}/shipping-methods -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "name" : "DHL",
  "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

by ID

by Key

POST

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

OAuth 2.0 Scopes:

manage_orders:{projectKey}manage_shipping_methods:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`id` String	`id` of the ShippingMethod.

Query parameters:

expand

Expansion

The parameter can be passed multiple times.

Request Body:

application/json

`version` Int	Expected version of the ShippingMethod on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.
`actions` Array of ShippingMethodUpdateAction	Update actions to be performed on the ShippingMethod.

Response:

200ShippingMethodasapplication/json

Request Example:cURL

curl https://api.{region}.commercetools.com/{projectKey}/shipping-methods/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 1,
  "actions" : [ {
    "action" : "changeName",
    "name" : "New Name"
  } ]
}
DATA

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

Change Name

Set Localized Name

Set Localized Description

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": {
    "exampleStringTypeField": "TextString"
  }
}

Set CustomField

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

`action` String	`"setCustomField"`
`name` String	Name of the Custom Field.
`value` CustomFieldValue	If `value` is absent or `null`, this field will be removed if it exists. Removing a field that does not exist returns an InvalidOperation error. If `value` is provided, it is set for the field defined by `name`.

Example: json

{
  "action": "setCustomField",
  "name": "ExampleStringTypeField",
  "value": "TextString"
}

Delete ShippingMethod

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

by ID

by Key

DELETE

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

OAuth 2.0 Scopes:

manage_orders:{projectKey}manage_shipping_methods:{projectKey}

Path parameters:

`region` String	Region in which the Project is hosted.
`projectKey` String	`key` of the Project.
`id` String	`id` of the ShippingMethod.

Query parameters:

`version` Int	Last seen version of the resource.
`expand` Expansion	The parameter can be passed multiple times.

Response:

200ShippingMethodasapplication/json

Request Example:cURL

curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/shipping-methods/{id}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

200 Response Example: ShippingMethodjson

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

`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.
`state` String	Name of the state, for example, Colorado.
`currency` String	The currency code compliant to ISO 4217.

`expand` Expansion	The parameter can be passed multiple times.
`country` CountryCode	A two-digit country code as per ISO 3166-1 alpha-2.
`state` String	Name of the state, for example, Colorado.
`cartId` String	ID of the Cart.

`orderEditId` String	The ID of the OrderEdit.
`country` CountryCode	A two-digit country code as per ISO 3166-1 alpha-2.
`state` String	Name of the state, for example, Colorado.

`country` CountryCode	A two-digit country code as per ISO 3166-1 alpha-2.
`state` String	Name of the state, for example, Colorado.
`currency` String	The currency code compliant to ISO 4217.

`country` CountryCode	A two-digit country code as per ISO 3166-1 alpha-2.
`state` String	Name of the state, for example, Colorado.
`cartId` String	ID of the Cart.