Skip to main content
POST
/
v1
/
shipping_zones
Create
curl --request POST \
  --url https://{defaultHost}/v1/shipping_zones \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "shipping_zone": {
    "name": "Canada",
    "shipping_profile_id": "8586016c-0a07-4daf-8e54-8d6a32d962e7",
    "territories": [
      {
        "country": "US",
        "states": [
          "AK"
        ]
      }
    ]
  }
}
'
{
  "id": "87f79c8c-ea4f-4e8b-8fce-f418eff3d107",
  "object": "shipping_zone",
  "name": "Canada",
  "territories": [
    {
      "country": "US",
      "states": [
        "AK"
      ]
    }
  ],
  "postal_codes": [],
  "shipping_profile": "8586016c-0a07-4daf-8e54-8d6a32d962e7",
  "created_at": 1767909773,
  "updated_at": 1767909773
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
shipping_zone
object

Response

200 - application/json

Success

​
id
string | null

The UUID of the specific object.

​
object
string

A string describing the object type returned.

​
name
string

A name for this shipping zone that will be visible to customers.

​
postal_codes
string[]

Optional array of postal code patterns to further filter addresses within the specified territories. Postal code filtering is applied in addition to territory filtering - an address must match both a territory and a postal code pattern (if provided) to be included in this shipping zone. Supports three matching modes:

  1. Exact match: Provide the complete postal code as a string (e.g., "90210", "SW1A 1AA").
  2. Range match: Use three dots ("...") to specify a numeric range (e.g., "90210...99000" matches all postal codes from 90210 to 99000). Only numeric postal codes are supported for ranges.
  3. Wildcard match: Use asterisk ("") for prefix matching (e.g., "902" matches "90210", "90211", "902AB", etc.). All postal codes are normalized (uppercased and trimmed) before matching. If the array is empty, no postal code filtering is applied and all addresses within the territories will match.
​
territories
object[]

The specific territories that this shipping zone covers.

​
metadata
object

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

​
created_at
integer | null

Time at which the object was created. Measured in seconds since the Unix epoch.

​
updated_at
integer | null

Time at which the object was last updated. Measured in seconds since the Unix epoch.

​
shipping_profile

Expandable – The associated shipping profile ID.

​
shipping_rates

Expandable – Property not returned unless expanded.