100 Zones can be created per Project. Learn more about this limit.Representations
Zone
id​String​ | Unique identifier of the Zone. |
version​Int​ | Current version of the Zone. |
key​String​ | User-defined unique identifier of the Zone. MinLength:Â2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​ |
name​String​ | Name of the Zone. |
description​String​ | Description of the Zone. |
locations​Array of Location​ | List of locations that belong to the Zone. |
createdAt​DateTime​ | Date and time (UTC) the Zone was initially created. |
createdBy​BETACreatedBy​ | IDs and references that created the Zone. |
lastModifiedAt​DateTime​ | Date and time (UTC) the Zone was last updated. |
lastModifiedBy​BETA | IDs and references that last modified the Zone. |
{
"id": "ebe01381-82be-4e63-9993-d1eb8f8e588b",
"version": 1,
"name": "US",
"key": "us-zone",
"locations": [
{
"country": "US"
}
],
"createdAt": "2015-01-21T09:22:04.275Z",
"lastModifiedAt": "2015-01-21T09:22:04.275Z"
}ZoneDraft
key​String​ | User-defined unique identifier for the Zone. MinLength:Â2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​ |
name​String​ | Name of the Zone. |
description​String​ | Description of the Zone. |
locations​Array of Location​ | List of locations that belong to the Zone. |
{
"name": "US",
"locations": [
{
"country": "US"
}
]
}ZonePagedQueryResponse
limit​Int​ | Number of results requested. Default: 20​Minimum: 0​Maximum: 500​ |
offset​Int​ | Number of elements skipped. Default: 0​Maximum: 10000​ |
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. |
{
"limit": 20,
"offset": 0,
"count": 3,
"total": 3,
"results": [
{
"id": "ebe01381-82be-4e63-9993-d1eb8f8e588b",
"version": 1,
"name": "US Mainland",
"locations": [
{
"country": "US"
}
],
"createdAt": "2015-01-21T09:22:04.275Z",
"lastModifiedAt": "2015-01-21T09:22:04.275Z"
},
{
"id": "ebe01381-82be-4e63-9993-d1eb8f8e5abc",
"version": 1,
"name": "US Hawaii and Alaska",
"locations": [
{
"country": "US",
"state": "Hawaii"
},
{
"country": "US",
"state": "Alaska"
}
],
"createdAt": "2015-01-21T09:22:05.275Z",
"lastModifiedAt": "2015-01-21T09:22:05.275Z"
},
{
"id": "5cb532be-c680-43ab-ba14-b664bb03dc35",
"version": 3,
"name": "Europe",
"locations": [
{
"country": "DE"
},
{
"country": "IT"
},
{
"country": "FR"
},
{
"country": "ES"
}
],
"createdAt": "2015-01-21T09:22:04.266Z",
"lastModifiedAt": "2016-01-26T10:56:32.504Z"
}
]
}ZoneReference
id​String​ | Unique identifier of the referenced Zone. |
typeId​ | zoneType of referenced resource. |
obj​Zone​ | Contains the representation of the expanded Zone. Only present in responses to requests with Reference Expansion for Zones. |
ZoneResourceIdentifier
id or key is required. If both are set, an InvalidJsonInput error is returned.id​String​ | Unique identifier of the referenced Zone. Required if key is absent. |
key​String​ | User-defined unique identifier of the referenced Zone. Required if id is absent. |
typeId​ | zoneType of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource. |
Location
A geographical location representing a country and optionally a state within this country. A location can only be assigned to one Zone.
country​CountryCode​ | Country code of the geographic location. Pattern:Â^[A-Z]{2}$​ |
state​String​ | State within the country. |
Get Zone
Get Zone by ID
id.view_orders:{projectKey}regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
idString ​ | id of the Zone. |
expand | The parameter can be passed multiple times. |
application/jsoncurl --get https://api.{region}.commercetools.com/{projectKey}/zones/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" {
"id": "ebe01381-82be-4e63-9993-d1eb8f8e588b",
"version": 1,
"name": "US",
"key": "us-zone",
"locations": [
{
"country": "US"
}
],
"createdAt": "2015-01-21T09:22:04.275Z",
"lastModifiedAt": "2015-01-21T09:22:04.275Z"
}Get Zone by Key
key.view_orders:{projectKey}regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
keyString ​ | key of the Zone. |
expand | The parameter can be passed multiple times. |
application/jsoncurl --get https://api.{region}.commercetools.com/{projectKey}/zones/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" {
"id": "ebe01381-82be-4e63-9993-d1eb8f8e588b",
"version": 1,
"name": "US",
"key": "us-zone",
"locations": [
{
"country": "US"
}
],
"createdAt": "2015-01-21T09:22:04.275Z",
"lastModifiedAt": "2015-01-21T09:22:04.275Z"
}Query Zones
Retrieves all Zones in the Project.
view_orders:{projectKey}regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
where | The parameter can be passed multiple times. |
sort | The parameter can be passed multiple times. |
expand | The parameter can be passed multiple times. |
limitInt ​ | Number of results requested. Default: 20​Minimum: 0​Maximum: 500​ |
offsetInt ​ | Number of elements skipped. Default: 0​Maximum: 10000​ |
withTotalBoolean ​ | 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. |
application/jsoncurl --get https://api.{region}.commercetools.com/{projectKey}/zones -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" {
"limit": 20,
"offset": 0,
"count": 3,
"total": 3,
"results": [
{
"id": "ebe01381-82be-4e63-9993-d1eb8f8e588b",
"version": 1,
"name": "US Mainland",
"locations": [
{
"country": "US"
}
],
"createdAt": "2015-01-21T09:22:04.275Z",
"lastModifiedAt": "2015-01-21T09:22:04.275Z"
},
{
"id": "ebe01381-82be-4e63-9993-d1eb8f8e5abc",
"version": 1,
"name": "US Hawaii and Alaska",
"locations": [
{
"country": "US",
"state": "Hawaii"
},
{
"country": "US",
"state": "Alaska"
}
],
"createdAt": "2015-01-21T09:22:05.275Z",
"lastModifiedAt": "2015-01-21T09:22:05.275Z"
},
{
"id": "5cb532be-c680-43ab-ba14-b664bb03dc35",
"version": 3,
"name": "Europe",
"locations": [
{
"country": "DE"
},
{
"country": "IT"
},
{
"country": "FR"
},
{
"country": "ES"
}
],
"createdAt": "2015-01-21T09:22:04.266Z",
"lastModifiedAt": "2016-01-26T10:56:32.504Z"
}
]
}Check if Zone exists
Check if Zone exists by ID
id. Returns a 200 OK status if the Zone exists or a Not Found error otherwise.view_orders:{projectKey}regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
idString ​ | id of the Zone. |
curl --head https://api.{region}.commercetools.com/{projectKey}/zones/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" Check if Zone exists by Key
key. Returns a 200 OK status if the Zone exists or a Not Found error otherwise.view_orders:{projectKey}regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
keyString ​ | key of the Zone. |
curl --head https://api.{region}.commercetools.com/{projectKey}/zones/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" Check if Zone exists by Query Predicate
200 OK status if any Zones match the query predicate, or a Not Found error otherwise.view_orders:{projectKey}regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
where | The parameter can be passed multiple times. |
curl --head https://api.{region}.commercetools.com/{projectKey}/zones -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" Create Zone
Creates a Zone in the Project.
manage_orders:{projectKey}regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
expand | The parameter can be passed multiple times. |
application/jsonapplication/jsoncurl 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{
"id": "ebe01381-82be-4e63-9993-d1eb8f8e588b",
"version": 1,
"name": "US",
"key": "us-zone",
"locations": [
{
"country": "US"
}
],
"createdAt": "2015-01-21T09:22:04.275Z",
"lastModifiedAt": "2015-01-21T09:22:04.275Z"
}Update Zone
Update Zone by ID
manage_orders:{projectKey}regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
idString ​ | id of the Zone. |
expand | The parameter can be passed multiple times. |
application/jsonversion​Int​ | Expected version of the Zone on which the changes should be applied.
If the expected version does not match the actual version, a ConcurrentModification error will be returned. |
actions​Array of ZoneUpdateAction​ | Update actions to be performed on the Zone. |
application/jsoncurl 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{
"id": "ebe01381-82be-4e63-9993-d1eb8f8e588b",
"version": 1,
"name": "US",
"key": "us-zone",
"locations": [
{
"country": "US"
}
],
"createdAt": "2015-01-21T09:22:04.275Z",
"lastModifiedAt": "2015-01-21T09:22:04.275Z"
}Update Zone by Key
manage_orders:{projectKey}regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
keyString ​ | key of the Zone. |
expand | The parameter can be passed multiple times. |
application/jsonversion​Int​ | Expected version of the Zone on which the changes should be applied.
If the expected version does not match the actual version, a ConcurrentModification error will be returned. |
actions​Array of ZoneUpdateAction​ | Update actions to be performed on the Zone. |
application/jsoncurl 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{
"id": "ebe01381-82be-4e63-9993-d1eb8f8e588b",
"version": 1,
"name": "US",
"key": "us-zone",
"locations": [
{
"country": "US"
}
],
"createdAt": "2015-01-21T09:22:04.275Z",
"lastModifiedAt": "2015-01-21T09:22:04.275Z"
}Update actions
Set Key
action​String​ | "setKey" |
key​String​ | If MinLength: key is absent or null, the existing key, if any, will be removed.2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​ |
{
"action": "setKey",
"key": "keyString"
}Change Name
action​String​ | "changeName" |
name​String​ | New name of the Zone. |
{
"action": "changeName",
"name": "changedName"
}Set Description
action​String​ | "setDescription" |
description​String​ | Description of the Zone. |
{
"action": "setDescription",
"description": "new ZoneDescription"
}Add Location
action​String​ | "addLocation" |
location​Location​ | Location to be added to the Zone. |
{
"action": "addLocation",
"location": {
"country": "AT"
}
}Remove Location
action​String​ | "removeLocation" |
location​Location​ | Location to be removed from the Zone. |
{
"action": "removeLocation",
"location": {
"country": "AT"
}
}Delete Zone
Delete Zone by ID
Deletes a Zone in the Project.
manage_orders:{projectKey}regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
idString ​ | id of the Zone. |
versionInt ​ | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
application/jsoncurl -X DELETE https://api.{region}.commercetools.com/{projectKey}/zones/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"{
"id": "ebe01381-82be-4e63-9993-d1eb8f8e588b",
"version": 1,
"name": "US",
"key": "us-zone",
"locations": [
{
"country": "US"
}
],
"createdAt": "2015-01-21T09:22:04.275Z",
"lastModifiedAt": "2015-01-21T09:22:04.275Z"
}Delete Zone by Key
Deletes a Zone in the Project.
manage_orders:{projectKey}regionString ​ | Region in which the Project is hosted. |
projectKeyString ​ | key of the Project. |
keyString ​ | key of the Zone. |
versionInt ​ | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
application/jsoncurl -X DELETE https://api.{region}.commercetools.com/{projectKey}/zones/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"{
"id": "ebe01381-82be-4e63-9993-d1eb8f8e588b",
"version": 1,
"name": "US",
"key": "us-zone",
"locations": [
{
"country": "US"
}
],
"createdAt": "2015-01-21T09:22:04.275Z",
"lastModifiedAt": "2015-01-21T09:22:04.275Z"
}