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
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 | Date and time (UTC) the Zone was initially created. |
createdBy BETA | IDs and references that created the Zone. |
lastModifiedAt | 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. |
offset Int | Number of elements skipped. |
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" References a Zone. |
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.
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
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. |
/^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 requested. |
offset Int | Number of elements skipped. |
withTotal Boolean | Controls the calculation of the total number of query results. Set to Default: true |
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
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 String |
|
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 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 to be added to the Zone. |
{"action": "addLocation","location": {"country": "AT"}}
Remove Location
action String | "removeLocation" |
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"}