Shipping Zones

A shipping zone contains regions and countries that you ship to. Each shipping zone has its own shipping rates.

Retrieve a list of shipping zones

Retrieve a list of shipping zones.

Request
Security:
query Parameters
limit
integer [ 0 .. 1000 ]

The collection items limit.

offset
integer >= 0

The collection items offset.

filter
string

The collection items filter requires a special format. Use "," for multiple allowed values. Use ";" for multiple fields. See the filter guide for more options and examples about this format.

sort
Array of strings

The collection items sort field and order (prefix with "-" for descending sort).

q
string

The partial search of the text fields.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
200A list of shipping zones was retrieved successfully.
Response Headers
Pagination-Total
integer

Total items count.

Pagination-Limit
integer

Items per page limit.

Pagination-Offset
integer

Pagination offset.

Response Schema: application/json
Array
id
string <= 50 characters

The shipping zone identifier string.

name
required
string <= 255 characters

The shipping zone name.

countries
Array of strings

Countries covered by the shipping zone. A country can only belong to one shipping zone (no overlapping). This property can be empty or null to create a default shipping zone for countries that were not specified in other zones.

Array of objects

Price-based shipping rate instructions.

isDefault
any

Is this Shipping Zone default.

createdTime
string <date-time>

The shipping zone created time.

updatedTime
string <date-time>

The shipping zone updated time.

Array of objects (schemas) non-empty

The links related to resource.

401Unauthorized access, invalid credentials was used.
403Access forbidden.
get/shipping-zones
Request samples
// all parameters are optional
const firstCollection = await api.shippingZones.getAll();

// alternatively you can specify one or more of them
const params = {limit: 20, offset: 100, sort: '-createdTime'}; 
const secondCollection = await api.shippingZones.getAll(params);

// access the collection items, each item is a Member
secondCollection.items.forEach(shippingZone => console.log(shippingZone.fields.name));
Response samples
application/json
[
  • {
    }
]

Create a Shipping Zone

Create a Shipping Zone.

Request
Security:
header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Request Body schema: application/json

Shipping Zone resource.

name
required
string <= 255 characters

The shipping zone name.

countries
Array of strings

Countries covered by the shipping zone. A country can only belong to one shipping zone (no overlapping). This property can be empty or null to create a default shipping zone for countries that were not specified in other zones.

Array of objects

Price-based shipping rate instructions.

Responses
201Shipping Zone was created.
Response Schema: application/json
id
string <= 50 characters

The shipping zone identifier string.

name
required
string <= 255 characters

The shipping zone name.

countries
Array of strings

Countries covered by the shipping zone. A country can only belong to one shipping zone (no overlapping). This property can be empty or null to create a default shipping zone for countries that were not specified in other zones.

Array of objects

Price-based shipping rate instructions.

isDefault
any

Is this Shipping Zone default.

createdTime
string <date-time>

The shipping zone created time.

updatedTime
string <date-time>

The shipping zone updated time.

Array of objects (schemas) non-empty

The links related to resource.

401Unauthorized access, invalid credentials was used.
403Access forbidden.
422Invalid data was sent.
post/shipping-zones
Request samples
application/json
{
  • "name": "string",
  • "countries": [
    ],
  • "rates": [
    ]
}
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "name": "string",
  • "countries": [
    ],
  • "rates": [
    ],
  • "isDefault": null,
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ]
}

Retrieve a shipping zone

Retrieve a shipping zone with specified identifier string.

Request
Security:
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
200Shipping zone was retrieved successfully.
Response Schema: application/json
id
string <= 50 characters

The shipping zone identifier string.

name
required
string <= 255 characters

The shipping zone name.

countries
Array of strings

Countries covered by the shipping zone. A country can only belong to one shipping zone (no overlapping). This property can be empty or null to create a default shipping zone for countries that were not specified in other zones.

Array of objects

Price-based shipping rate instructions.

isDefault
any

Is this Shipping Zone default.

createdTime
string <date-time>

The shipping zone created time.

updatedTime
string <date-time>

The shipping zone updated time.

Array of objects (schemas) non-empty

The links related to resource.

401Unauthorized access, invalid credentials was used.
403Access forbidden.
404Resource was not found.
get/shipping-zones/{id}
Request samples
const shippingZone = await api.shippingZones.get({id: 'foobar-001'});
console.log(shippingZone.fields.name);
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "name": "string",
  • "countries": [
    ],
  • "rates": [
    ],
  • "isDefault": null,
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ]
}

Create a shipping zone with predefined ID

Create a shipping zone with predefined identifier string.

Request
Security:
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Request Body schema: application/json

Shipping zone resource.

name
required
string <= 255 characters

The shipping zone name.

countries
Array of strings

Countries covered by the shipping zone. A country can only belong to one shipping zone (no overlapping). This property can be empty or null to create a default shipping zone for countries that were not specified in other zones.

Array of objects

Price-based shipping rate instructions.

Responses
200Shipping zone was updated.
Response Schema: application/json
id
string <= 50 characters

The shipping zone identifier string.

name
required
string <= 255 characters

The shipping zone name.

countries
Array of strings

Countries covered by the shipping zone. A country can only belong to one shipping zone (no overlapping). This property can be empty or null to create a default shipping zone for countries that were not specified in other zones.

Array of objects

Price-based shipping rate instructions.

isDefault
any

Is this Shipping Zone default.

createdTime
string <date-time>

The shipping zone created time.

updatedTime
string <date-time>

The shipping zone updated time.

Array of objects (schemas) non-empty

The links related to resource.

201Shipping zone was created.
Response Schema: application/json
id
string <= 50 characters

The shipping zone identifier string.

name
required
string <= 255 characters

The shipping zone name.

countries
Array of strings

Countries covered by the shipping zone. A country can only belong to one shipping zone (no overlapping). This property can be empty or null to create a default shipping zone for countries that were not specified in other zones.

Array of objects

Price-based shipping rate instructions.

isDefault
any

Is this Shipping Zone default.

createdTime
string <date-time>

The shipping zone created time.

updatedTime
string <date-time>

The shipping zone updated time.

Array of objects (schemas) non-empty

The links related to resource.

401Unauthorized access, invalid credentials was used.
403Access forbidden.
422Invalid data was sent.
put/shipping-zones/{id}
Request samples
application/json
{
  • "name": "string",
  • "countries": [
    ],
  • "rates": [
    ]
}
Response samples
application/json
{
  • "id": "4f6cf35x-2c4y-483z-a0a9-158621f77a21",
  • "name": "string",
  • "countries": [
    ],
  • "rates": [
    ],
  • "isDefault": null,
  • "createdTime": "2019-08-24T14:15:22Z",
  • "updatedTime": "2019-08-24T14:15:22Z",
  • "_links": [
    ]
}

Delete a shipping zone

Delete a shipping zone with predefined identifier string.

Request
Security:
path Parameters
id
required
string <= 50 characters ^[@~\-\.\w]+$

The resource identifier string.

header Parameters
Organization-Id
string (ResourceId) <= 50 characters

Organization identifier in scope of which need to perform request (if not specified, the default organization will be used).

Example: 4f6cf35x-2c4y-483z-a0a9-158621f77a21
Responses
204Shipping zone was deleted.
401Unauthorized access, invalid credentials was used.
403Access forbidden.
404Resource was not found.
delete/shipping-zones/{id}
Request samples
const request = await api.shippingZones.delete({id: 'my-second-key'});

// the request does not return any fields but
// you can confirm the success using the status code
console.log(request.response.status); // 204
Response samples
application/json
{
  • "status": 400,
  • "title": "string",
  • "detail": "string",
  • "error": "string"
}