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
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
PagedQueryResult with results
containing an array of Zone.
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 |
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
ResourceIdentifier to a Zone. Either 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 ​String​ | User-defined unique identifier of the referenced Zone. Required if |
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 ​ |
|
id String ​ |
|
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 String ​ |
|
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 ​ |
|
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 ​ |
offset Int ​ | Number of elements skipped. Default: 0 ​ |
withTotal Boolean ​ | Controls the calculation of the total number of query results. Set to 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
Checks if a Zone exists for a given 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 ​ |
|
id String ​ |
|
curl --head https://api.{region}.commercetools.com/{projectKey}/zones/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Check if Zone exists by Key
Checks if a Zone exists for a given 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 String ​ |
|
curl --head https://api.{region}.commercetools.com/{projectKey}/zones/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Check if Zone exists by Query Predicate
Checks if a Zone exists for a given Query Predicate. Returns a 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 ​ |
|
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 ​ |
|
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 ​ |
|
id String ​ |
|
expand | The parameter can be passed multiple times. |
application/json
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 String ​ |
|
expand | The parameter can be passed multiple times. |
application/json
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 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 ​ |
|
id String ​ |
|
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 String ​ |
|
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"
}