[go: up one dir, main page]

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.

MinLength2MaxLength256Pattern^[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.

createdByBETA

IDs and references that created the Zone.

lastModifiedAt

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

lastModifiedByBETA

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.

MinLength2MaxLength256Pattern^[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
Default20Minimum0Maximum500
offset
Int
Number of elements skipped.
Default0Maximum10000
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

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

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}
Retrieves a Zone with the provided 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
The parameter can be passed multiple times.
Response:
200

Zone

as
application/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}
Retrieves a Zone with the provided 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
The parameter can be passed multiple times.
Response:
200

Zone

as
application/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

Retrieves all Zones in the Project.

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
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
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
The parameter can be passed multiple times.
Response:
200

ZonePagedQueryResponse

as
application/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 with the provided id. Returns a 200 OK status if the Zone exists or a Not Found error 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 with the provided key. Returns a 200 OK status if the Zone exists or a Not Found error 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 one or more Zones exist for the provided query predicate. Returns a 200 OK status if any Zones match the query predicate, or a Not Found error 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
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

Creates a Zone in the Project.

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
The parameter can be passed multiple times.
Request Body:ZoneDraftasapplication/json
Response:
201

Zone

as
application/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
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:
200

Zone

as
application/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}
Updates a Zone in the Project using one or more update actions.
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
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:
200

Zone

as
application/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.
MinLength2MaxLength256Pattern^[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 to be added to the Zone.

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

Remove Location

action
String
"removeLocation"
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}

Deletes a Zone in the Project.

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
The parameter can be passed multiple times.
Response:
200

Zone

as
application/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}

Deletes a Zone in the Project.

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
The parameter can be passed multiple times.
Response:
200

Zone

as
application/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"
}