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

ZoneDraft

ZonePagedQueryResponse

ZoneReference

ZoneResourceIdentifier

Location

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	Present on resources created after 1 February 2019 except for events not tracked.
`lastModifiedAt` DateTime	Date and time (UTC) the Zone was last updated.
`lastModifiedBy`BETA LastModifiedBy	Present on resources created after 1 February 2019 except for events not tracked.

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.
`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 `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` String	`"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.

`id` String	Unique identifier of the referenced Zone. Either `id` or `key` is required.
`key` String	User-defined unique identifier of the referenced Zone. Either `id` or `key` is required.
`typeId` String	`"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:

200Zone

Request Example:cURL

curl -X 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:

200Zone

Request Example:cURL

curl -X 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.
`/^var[.][a-zA-Z0-9]+$/` Any string parameter matching this regular expression	Predicate parameter values. 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.
`offset` Int	Number of elements skipped.
`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.

Response:

200ZonePagedQueryResponse

Request Example:cURL

curl -X 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"
  } ]
}

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:ZoneDraft

Response:

201Zone

Request Example:cURL

curl -X POST 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:

`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 409 Conflict will be returned.
`actions` Array of ZoneUpdateAction	Update actions to be performed on the Zone.

Response:

200Zone

Request Example:cURL

curl -X POST 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:

`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 409 Conflict will be returned.
`actions` Array of ZoneUpdateAction	Update actions to be performed on the Zone.

Response:

200Zone

Request Example:cURL

curl -X POST 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:

200Zone

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:

200Zone

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"
}

Zones

Representations.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}.css-e0dnmk{cursor:pointer;}

Zone.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

ZoneDraft.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

ZonePagedQueryResponse.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

ZoneReference.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

ZoneResourceIdentifier.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Location.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Get Zone.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Get Zone by ID.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Get Zone by Key.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Query Zones.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Create Zone.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Update Zone.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Update Zone by ID.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Update Zone by Key.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Update actions.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Set Key.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Change Name.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Set Description.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Add Location.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Remove Location.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Delete Zone.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Delete Zone by ID.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Delete Zone by Key.css-18fwu9s{display:inline-block;cursor:not-allowed;}.css-18fwu9s >:disabled{pointer-events:none;}

Representations

Zone

ZoneDraft

ZonePagedQueryResponse

ZoneReference

ZoneResourceIdentifier

Location

Get Zone

Get Zone by ID

Get Zone by Key

Query Zones

Create Zone

Update Zone

Update Zone by ID

Update Zone by Key

Update actions

Set Key

Change Name

Set Description

Add Location

Remove Location

Delete Zone

Delete Zone by ID

Delete Zone by Key