Zones

Zones allow defining ShippingRates for specific Locations.

Representations

Zone

Groups locations to a zone. A location can only be assigned to exactly one zone. A zone is used to define a ShippingRate for a set of locations.

  • id - String
    The unique ID of the zone.
  • version - Number
    The current version of the zone.
  • key - String - Optional
    User-specific unique identifier for a zone. Must be unique across a project. The field can be reset using the Set Key UpdateAction.
  • createdAt - DateTime
  • lastModifiedAt - DateTime
  • name - String
  • description - String - Optional
  • locations - Array of Location

ZoneDraft

ZoneDrafts are used as payloads given with Create Zone requests.

  • key - String - Optional
    User-specific unique identifier for a zone. Must be unique across a project. The field can be reset using the Set Key UpdateAction.
  • name - String - Required
  • description - String - Optional
  • locations - Array of Location - Optional

Location

A geographical location representing a country with an optional state.

Get Zone

Get Zone by ID

Endpoint: /{projectKey}/zones/{id}
Method: GET
OAuth2 Scopes: view_orders:{projectKey}
Response Representation: Zone

Get Zone by Key

Endpoint: /{projectKey}/zones/key={key}
Method: GET
OAuth2 Scopes: view_orders:{projectKey}
Response Representation: Zone

Query Zones

Endpoint: /{projectKey}/zones
Method: GET
OAuth2 Scopes: view_orders:{projectKey}
Response Representation: PagedQueryResult with the results array of Zone
Query Parameters:

Create Zone

Endpoint: /{projectKey}/zones
Method: POST
OAuth2 Scopes: manage_orders:{projectKey}
Request Representation: ZoneDraft
Response Representation: Zone

Update Zone

Update Zone by ID

Endpoint: /{projectKey}/zones/{id}
Method: POST
OAuth2 Scopes: manage_orders:{projectKey}
Response Representation: Zone
Fields:

  • version - Number - Required
    The 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 UpdateAction - Required
    The list of update actions to be performed on the zone.

Update Zone by Key

Endpoint: /{projectKey}/zones/key={key}
Method: POST
OAuth2 Scopes: manage_orders:{projectKey}
Response Representation: Zone
Fields:

  • version - Number - Required
    The 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 UpdateAction - Required
    The list of update actions to be performed on the zone.

Update Actions
Please find below the individual update actions provided on this endpoint.


Set Key

Sets a key for the zone that is defined by you. The key must be unique across the project.

  • action - String - "setKey"
  • key - String - Optional
    If key is absent or null, this field will be removed if it exists.

Change Name

  • action - String - "changeName"
  • name - String - Required

Set Description

  • action - String - "setDescription"
  • description - String - Optional

Add Location

  • action - String - "addLocation"
  • location - Location - Required

Remove Location

  • action - String - "removeLocation"
  • location - Location - Required

Delete Zone

Delete Zone by ID

Endpoint: /{projectKey}/zones/{id}
Method: DELETE
OAuth2 Scopes: manage_orders:{projectKey}
Query Parameters:

  • version - Number - Required

Delete Zone by Key

Endpoint: /{projectKey}/zones/key={key}
Method: DELETE
OAuth2 Scopes: manage_orders:{projectKey}
Query Parameters:

  • version - Number - Required