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 ​ | zone Type 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 ​ | zone Type 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
view_orders:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
id String ​ | id of the Zone. |
expand | The parameter can be passed multiple times. |
application/json
curl --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
view_orders:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
key String ​ | key of the Zone. |
expand | The parameter can be passed multiple times. |
application/json
curl --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
view_orders:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | 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. |
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. |
application/json
curl --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 404 Not Found
otherwise.view_orders:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
id String ​ | 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 404 Not Found
otherwise.view_orders:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
key String ​ | 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 404 Not Found
otherwise.view_orders:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | 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
manage_orders:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
expand | The parameter can be passed multiple times. |
application/json
application/json
curl 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}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
id String ​ | id of the Zone. |
expand | The parameter can be passed multiple times. |
application/json
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 ConcurrentModification error will be returned. |
actions ​Array of ZoneUpdateAction​ | Update actions to be performed on the Zone. |
application/json
curl 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}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
key String ​ | key of the Zone. |
expand | The parameter can be passed multiple times. |
application/json
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 ConcurrentModification error will be returned. |
actions ​Array of ZoneUpdateAction​ | Update actions to be performed on the Zone. |
application/json
curl 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
manage_orders:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
id String ​ | id of the Zone. |
version Int ​ | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
application/json
curl -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
manage_orders:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
key String ​ | key of the Zone. |
version Int ​ | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
application/json
curl -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"
}