Geozones API v2
Geozones define country and region settings for use in shipping calculations, regional pricing and taxation.
The Geozones API resource allows you to list built-in and manage custom Geozones configured for your account.
Scopes
Access to the Geozones API requires that the client have the following scopes granted:
geozones- Permits write access to add, update or remove geozones.geozones.readonly- Read only access to search or get geozone data.
The Geozone object
A Geozone represents a named grouping of one or more countries with zero or more respective regions.
countries
An array of objects with the following properties:
|
createdOn
read-only
The date and time the Geozone was created. |
description
An optional short description describing the Geozone up to 200 characters long. |
id
read-only
An unsigned 64-bit integer, which is unique across all Geozones and all Evance Accounts. |
modifiedOn
read-only
The date and time the Geozone was last modified. |
title
A title up to 80 characters long for the Geozone is used for your reference and internal use only. The title is not displayed on websites. |
Example JSON response
{
"data": {
"id": 53245,
"title": "East Anglia - UK",
"description": "All counties in East Anglia in the United Kingdom",
"countries": [
{
"countryCode": "GB",
"regionCodes": ["GB-SFK", "GB-NFK", "GB-CAM"]
}
]
}
}
List/search Geozones
GET
/api/v2/geozones.json
Get or search for one or more Geozones.
Requires either the geozones or geozones.readonly OAuth scope.
Query parameters
id:in
Return Geozones by a comma-separated list of IDs. |
title
Used to find a single Geozone by its |
JSON response
Evance will return a JSON object containing the following properties:
success
A successful search request containing zero or more results will always return a true value.
|
status
An integer matching the HTTP response code. A successful request will have a status of 200.
|
data
An array containing zero or more Geozone data objects. |
pagination
Search results include a pagination object contain information about the current page, total pages, the limit per page and the total number of results available.
|
links
An object containing links to traverse available search results.
|
Example JSON response
{
"success": true,
"status": 200,
"data": [
{
"id": 48646,
"title": "East Anglia - UK",
"description": "All counties in East Anglia, United Kingdom",
"createdOn": "2022-05-21T15:54:05+00:00"
"modifiedOn": "2022-05-21T15:54:05+00:00",
"countries": [
{
"countryCode": "GB",
"regionCodes": ["GB-SFK", "GB-NFK", "GB-CAM"]
}
]
}, {
"id": 52367,
"title": "Northern America",
"description": "Countries in Northern America",
"createdOn": "2022-05-21T15:54:05+00:00"
"modifiedOn": "2022-05-21T15:54:05+00:00",
"countries": [
{
"countryCode": "CA",
"regionCodes": []
},
{
"countryCode": "MX",
"regionCodes": []
},
{
"countryCode": "US",
"regionCodes": []
}
]
}
],
"pagination": {
"page": 1,
"limit": 100,
"total": 1,
"totalPages": 1
},
"links": {
"self": "https://examples.evance.me/api/v2/geozones.json",
"previous": null,
"next": null
}
}
Get a Geozone
GET
/api/v2/geozones/{id}.json
Retrieve a single Geozone using its ID.
Requires either the geozones or geozones.readonly OAuth scope.
URL parameters
id
required
The ID of the Geozone is supplied as a path parameter. |
Response
Returns an object with the following properties:
success
A boolean where a value of true represents a successful request.
|
status
The HTTP status code e.g. 200 for a successful request.
|
data
Contains the Geozone object. |
Example JSON response
{
"success": true,
"status": 200,
"data": {
"id": 48646,
"title": "EU Shipping Zone 1",
"description": "Shipping zone for our main European customer base",
"createdOn": "2022-05-21T15:54:05+00:00",
"modifiedOn": "2022-05-21T15:54:05+00:00",
"countries": [
{
"countryCode": "ES",
"regionCodes": []
},
{
"countryCode": "DE",
"regionCodes": []
},
{
"countryCode": "FR",
"regionCodes": []
}
]
}
}
Add a Geozone
POST
/api/v2/geozones.json
Add a Geozone.
Requires the geozones OAuth scope.
Request body
Your request body must contain an object including:
data
required
Containing a Geozone object. |
Example request
The minimum requirement for a Geozone is a title value, however ideally you should also
supply
countries associated with your zone.
{
"data": {
"title": "Europe - Zone 1",
"description": "Countries we ship to the most in Europe",
"countries": [
{
"countryCode": "DE"
},
{
"countryCode": "ES"
},
{
"countryCode": "FR"
}
]
}
}
In the example above we're only importing countryCode values. regionCodes are
optional and only applicable to zones used with address data (such as shipping calculations) and should not be used in
zones used for pricing.
In the example below we explore adding regionCodes for a zone used for local shipping calculations.
Such granular regional settings will typically mean the zone is limited to a single country.
{
"data": {
"title": "East Anglia",
"description": "Local shipping zone",
"countries": [
{
"countryCode": "GB",
"regionaCodes": ["GB-SFK", "GB-NFK", "GB-CAM"]
}
]
}
}
Success response
If the Geozone was created successfully you should receive a response with a 201 status
code:
success
A boolean where a value of true means the object was created successfully.
|
status
The HTTP status code e.g. 201 means the object was created successfully. |
data
Contains the Geozone object you created including its new id.
|
Error responses
If the Geozone could not be created you will encounter a response with a 422 status code:
success
A boolean where a value of false means the object could not be created.
|
status
A response code of 422 means the object could not be created and you should
check the errors property for further information. |
context
The context property indicates where the error occurred. For a 422 error this
will typically contain a value of data, indicating that there was an error
with the data object supplied. |
errors
Contains an array of error objects, each will have the following properties:
|
Update a Geozone
PUT
/api/v2/geozones/{id}.json
Update an existing Geozones by its ID.
Requires the geozones OAuth scope.
URL parameters
id
required
The ID of your Geozone object |
Request body
Your request body must contain an object including:
data
required
Containing updates to your Geozone object. |
Example JSON request
To update a Geozone you must PUT JSON to this resource within a data object. You do
not need to supply all properties and may choose to only supply properties that require modifying.
If you supply
countries you MUST supply all country settings to avoid losing existing countries
associated with your Geozone.
{
"data": {
"title": "Example zone"
}
}
Success response
If the Geozone was updated successfully you should receive a response with a 200 status
code:
success
A boolean where a value of true means the object was saved successfully.
|
status
The HTTP status code e.g. 200 means the object was updated successfully. |
data
Contains the Geozone object you updated. |
Error responses
If the Geozone could not be updated you will encounter a response with either a
400,
403,
404 or
422status code:
success
A boolean where a value of false means the object could not be updated.
|
status
|
context
|
errors
Contains an array of error objects, each will have the following properties:
|
Delete a Geozone
DELETE
/api/v2/geozones/{id}.json
Delete a Geozone by its ID.
Requires the geozones OAuth scope.
URL parameters
id
required
The ID of your Geozone object |
Request body
Does not require a payload
Success response
If the Geozone was deleted successfully you should receive a response with a 204 status
code and no body.
Error responses
If the Geozone could not be deleted you may encounter a response with a
400,
403, or
404 status code:
success
A boolean where a value of false means the object could not be deleted.
|
status
|