Configuring shipping zones by using APIs

A shipping zone, or a zone, is a collection of geographical areas that are defined by origin and destination postal codes. These zones share similar transit durations and transit rates. Carriers use shipping zones to determine the transit duration and rate that is applied to all shipments within those areas. You can configure shipping zones by using APIs.

Configuring a zone and transit time

To configure a zone and transit components, see Upload shipping zone components API.

// Upload zone components with transit duration:
zone,origin_country,destination_country,origin_postal_code_begin,origin_postal_code_end,destination_postal_code_begin,destination_postal_code_end,transit_duration
ZONE_US_001,US,US,19533,19533,40000,41899,P3DT0H
ZONE_GB_001,GB,GB,E16 0AA,E16 0AA,AB1 0,AB1 9,P2DT0H

Upload zone definitions for a carrier service

Consider the following use cases in which you might want to introduce new zones:
  • You are opening a new store, and you want to introduce a zone with the new store's postal code.
  • You are shipping to new destination postal codes.

To introduce new zones for an existing carrier service, ensure that the new zones do not overlap with the previously uploaded zones. To specify the zones in which the carrier services operate, use the Upload zone definitions API.

To change the zone definitions for the existing postal codes for a carrier service, first delete all existing zones for the carrier service by using the Delete carrier zones for a carrier service API.

Create or update a specific zone component or route

To create or update the transit durations for a specific zone component or route within a zone for a carrier service, use the following command:
POST /cas/{tenantId}/v1/configuration/carrierServices/{carrierServiceId}/zones/_bulkUpsert API

Delete shipping zone components

Consider the following use cases in which you might want to delete shipping zone components:

  • You are creating new zones or rearranging postal codes for a specific store.
  • You are shutting down a store or the store is no longer eligible for shipping to a specific location.
  • You uploaded a batch of components by mistake and want to undo the action.
  • You want to move zone components from one shipping zone to another. In this case, you must delete existing zone components and re-upload them with reference to the new shipping zone.
For any of the previous use cases, to delete all shipping zone components that are configured for specific carrier service, use the Delete shipping zone components API.
Note: If the API is used to re-create components with different parameters, such as postal code ranges or shipping zones, you must delete the existing components to prevent an overlap.

Ensure to create new shopping zone components before deleting the conflicting ones. When the new shipping zone components are created for the specific carrier service, deleting conflicting components overcomes overlap or gaps in zone coverage.

The following scenarios are available to create zones and specify transit durations and rates:
  • Create zones to handle your in-country shipping scenario.
  • Create zones to handle your international shipping scenario.
  • Specifying transit durations for each zone.
  • Specifying transit rates for each zone.

For more information, see Carrier zones.

Transit duration and transit delay

As you configure the shipping zones, you can also configure the transit duration and transit delay by using any of the following APIs: For more information, see Configuring transit duration by using APIs.

Surcharges

You can configure surcharges as you configure the shipping components or you can configure the surcharges separately. For more information, see Configuring zone component surcharges by using APIs.