Zones

A Zone is used to define a ShippingRate for a set of locations.

A maximum number of 100 Zones can be created per Project. Learn more about this limit.

Representations

Zone

Zone

id
String

Unique ID of the Zone.

version
Int

Current version of the Zone.

key
String

User-defined unique identifier for the Zone.

createdAt

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

createdByBETA

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

lastModifiedAt

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

lastModifiedByBETA

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

name
String

Name of the Zone.

description
String

Description of the Zone.

locations
Array of Location

List of locations that belong to the Zone.

ZoneDraft

key
String

User-defined unique identifier for the Zone.

name
String

Name of the Zone.

description
String

Description of the Zone.

locations
Array of Location

List of locations that belong to the Zone.

ZonePagedQueryResponse

PagedQueryResult with results containing an array of Zone.

limit
Int

Number of results requested in the query request.

offset
Int

Offset supplied by the client or the server default. It is the number of elements skipped, not a page number.

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.

results
Array of Zone

Zones matching the query.

ZoneReference

id
String

Unique ID of the referenced Zone.

typeId
String
"zone"
obj
Zone

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

ZoneResourceIdentifier

id
String

Unique ID of the referenced Zone. Either id or key is required.

key
String

Unique key of the referenced Zone. Either id or key is required.

typeId
String
"zone"

Location

A geographical location representing a country and optionally a state within this country. A location can only be assigned to one Zone.

country

Country code of the geographic location.

Pattern: ^[A-Z]{2}$
state
String

State within the country.

Get Zone

Get Zone by ID

GET
https://api.{region}.commercetools.com/{projectKey}/zones/{id}
OAuth 2.0 Scopes:
view_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Zone.

Query parameters:
expand
The parameter can be passed multiple times.
Response:

200Zone

Request Example:cURL
curl -X GET https://api.{region}.commercetools.com/{projectKey}/zones/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Get Zone by Key

GET
https://api.{region}.commercetools.com/{projectKey}/zones/key={key}
OAuth 2.0 Scopes:
view_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the Zone.

Query parameters:
expand
The parameter can be passed multiple times.
Response:

200Zone

Request Example:cURL
curl -X GET https://api.{region}.commercetools.com/{projectKey}/zones/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Query Zones

GET
https://api.{region}.commercetools.com/{projectKey}/zones
OAuth 2.0 Scopes:
view_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Query parameters:
where
The parameter can be passed multiple times.
/^var[.][a-zA-Z0-9]+$/
Any string parameter matching this regular expression

Predicate parameter values.

The parameter can be passed multiple times.
sort
The parameter can be passed multiple times.
expand
The parameter can be passed multiple times.
limit
Int

Number of results returned.

offset
Int

Number of results skipped.

withTotal
Boolean

Calculate total number of results.

Request Example:cURL
curl -X GET https://api.{region}.commercetools.com/{projectKey}/zones -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

Create Zone

POST
https://api.{region}.commercetools.com/{projectKey}/zones
OAuth 2.0 Scopes:
manage_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:ZoneDraft
Response:

201Zone

Request Example:cURL
curl -X POST https://api.{region}.commercetools.com/{projectKey}/zones -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}' \
--header 'Content-Type: application/json' \
--data-binary @- << DATA
{
"name" : "US",
"locations" : [ {
"country" : "US"
} ]
}
DATA

Update Zone

Update Zone by ID

POST
https://api.{region}.commercetools.com/{projectKey}/zones/{id}
OAuth 2.0 Scopes:
manage_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Zone.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:
version
Int

Expected version of the Zone 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 ZoneUpdateAction

Update actions to be performed on the Zone.

Response:

200Zone

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

Update Zone by Key

POST
https://api.{region}.commercetools.com/{projectKey}/zones/key={key}
OAuth 2.0 Scopes:
manage_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the Zone.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:
version
Int

Expected version of the Zone 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 ZoneUpdateAction

Update actions to be performed on the Zone.

Response:

200Zone

Request Example:cURL
curl -X POST https://api.{region}.commercetools.com/{projectKey}/zones/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

Update actions

Set Key

key
String

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

action
String
"setKey"
Example: json
{
"action" : "setKey",
"key" : "keyString"
}

Change Name

action
String
"changeName"
name
String

New name of the Zone.

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

Set Description

action
String
"setDescription"
description
String

Description of the Zone.

Example: json
{
"action" : "setDescription",
"description" : "new ZoneDescription"
}

Add Location

action
String
"addLocation"
location

Location to be added to the Zone.

Example: json
{
"action" : "addLocation",
"location" : {
"country" : "AT"
}
}

Remove Location

action
String
"removeLocation"
location

Location to be removed from the Zone.

Example: json
{
"action" : "removeLocation",
"location" : {
"country" : "AT"
}
}

Delete Zone

Delete Zone by ID

DELETE
https://api.{region}.commercetools.com/{projectKey}/zones/{id}
OAuth 2.0 Scopes:
manage_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

id
String

id of the Zone.

Query parameters:
expand
The parameter can be passed multiple times.
version
Int

Last seen version of the resource.

Response:

200Zone

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

Delete Zone by Key

DELETE
https://api.{region}.commercetools.com/{projectKey}/zones/key={key}
OAuth 2.0 Scopes:
manage_orders:{projectKey}
Path parameters:
region
String

Region in which the Project is hosted.

projectKey
String

key of the Project.

key
String

key of the Zone.

Query parameters:
expand
The parameter can be passed multiple times.
version
Int

Last seen version of the resource.

Response:

200Zone

Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/zones/key={key}?version={version} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Developer Center
HTTP APIGraphQL APIPlatform Release NotesCustom ApplicationsBETASDKs & Client LibrariesImport & ExportSUNRISE Starter FrontendsTutorialsFAQ
Copyright © 2022 commercetools