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:
  • countryCode
    An ISO 3166 alpha-2 country code. For example GB representing United Kingdom.
  • regionCodes
    An optional array of Region codes associated with the countryCode. We try to maintain region codes as closely to ISO 3166-2 as possible, but this may not always be possible for all countries. Region codes consist of two parts, separated by a hyphen: the first part is the ISO 3166 alpha-2 code; and the second part is a string of up to three alphanumeric characters. For example, GB-LND represents London, United Kingdom. A front-end API is available listing all country and region data in Evance at /utils/countries.json

    When no regionCodes are supplied for a countryCode, all regions are implied for the country.

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 title property. The title must match the correct spelling (case-insensitive) - does not permit partial matches.


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.
  • limit - the number of results to return per page
  • page - the current page number
  • total - the total number of available results
  • totalPages - the total number of available pages of results
links
An object containing links to traverse available search results.
  • self - the URL for the current search.
  • previous - a URL for the previous results page, or null if there isn't one.
  • next - a URL for the next results page, or null if there isn't one


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:

  • name - The property name that encountered an error.
  • message - A human readable error message.
  • ref - An error reference string (e.g. error.not-unique if the alias supplied is already in use).


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
  • 400 may indicate that the ID was not provided.
  • 403 may be returned when a Geozone is protected and cannot be updated.
  • 404 means the Geozone could not be found by the IDs provided.
  • 422 means the Geozone could not be updated due to errors in the data.
context
  • parameters means the error is with the required id URL parameter.
  • data indicates an error within the Geozone object data.
errors

Contains an array of error objects, each will have the following properties:

  • name - The property name that encountered an error.
  • message - A human readable error message.
  • ref - An error reference string.


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
  • 400 may indicate that the ID was not provided, or the object could not be deleted for an unknown reason.
  • 403 indicatse that the Geozone is protected and may not be deleted.
  • 404 indicates that the ID was provided, but the object could not be found.