Documentation

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​
DateTime​

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

createdBy​BETA
CreatedBy​

IDs and references that created the Zone.

lastModifiedAt​
DateTime​

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

lastModifiedBy​BETA
LastModifiedBy​

IDs and references that last modified the Zone.

Example: json
{
  "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.

Example: json
{
  "name": "US",
  "locations": [
    {
      "country": "US"
    }
  ]
}

ZonePagedQueryResponse

PagedQueryResult with results containing an array of Zone.

limit​
Int​

Number of results requested.

Default: 20​Maximum: 500​
offset​
Int​

Number of elements skipped.

Default: 0​Maximum: 10 000​
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.

Example: json
{
  "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

Reference to a Zone.

id​
String​

Unique identifier of the referenced Zone.

typeId​
ReferenceTypeId​
"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.

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​
ReferenceTypeId​
"zone"

References a 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​
CountryCode​

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
​
Expansion
​
The parameter can be passed multiple times.
Response:
200Zoneasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/zones/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Zonejson
{
  "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

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
​
Expansion
​
The parameter can be passed multiple times.
Response:
200Zoneasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/zones/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Zonejson
{
  "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

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
​
QueryPredicate
​
The parameter can be passed multiple times.
sort
​
Sort
​
The parameter can be passed multiple times.
expand
​
Expansion
​
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 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.
Response:
200ZonePagedQueryResponseasapplication/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/zones -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: ZonePagedQueryResponsejson
{
  "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

HEAD
https://api.{region}.commercetools.com/{projectKey}/zones/{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.

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.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/zones/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if Zone exists by Key

HEAD
https://api.{region}.commercetools.com/{projectKey}/zones/key={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.

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.

Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/zones/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if Zone exists by Query Predicate

HEAD
https://api.{region}.commercetools.com/{projectKey}/zones

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.

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
​
QueryPredicate
​
The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head 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
​
Expansion
​
The parameter can be passed multiple times.
Request Body:ZoneDraftasapplication/json
Response:
201Zoneasapplication/json
Request Example:cURL
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
201 Response Example: Zonejson
{
  "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

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
​
Expansion
​
The parameter can be passed multiple times.
Request Body:
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.

Response:
200Zoneasapplication/json
Request Example:cURL
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
200 Response Example: Zonejson
{
  "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

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
​
Expansion
​
The parameter can be passed multiple times.
Request Body:
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.

Response:
200Zoneasapplication/json
Request Example:cURL
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
200 Response Example: Zonejson
{
  "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 key is absent or null, the existing key, if any, will be removed.

MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
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​

Location to be added to the Zone.

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

Remove Location

action​
String​
"removeLocation"
location​
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:
version
​
Int
​

Last seen version of the resource.

expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200Zoneasapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/zones/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Zonejson
{
  "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

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:
version
​
Int
​

Last seen version of the resource.

expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200Zoneasapplication/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/zones/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Zonejson
{
  "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"
}