Shipping Zones | BigCommerce Dev Center

Get All Shipping Zones

GET https://api.bigcommerce.com/stores/{store_hash}/v2/shipping/zones

Request

Returns a list of all Shipping Zones.

Authentication

X-Auth-Token in header - required

Parameters

store_hash in path - string
Accept in header with default of application/json - string - required
The MIME type of the response body.

example

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v2/shipping/zones' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Body

array | application/json

idinteger
Zone ID
Example: 1
namestring
Zone name. Required for PUT requests.
Example: United States
typestring
Allowed: zip | country | state | global
locationsarray[object]
Array of zone locations.
free_shippingobject
handling_feesobject
One of:
- fixed_surchargestring
  Flat-rate handling fee applied to shipping cost.
  Example: 0
- display_separatelyboolean
  Indicates whether store displays handling fee separately at checkout.
  Example: true
enabledboolean
Whether this shipping zone is enabled.
Example: true

Example 1: Zones are Country Zones

[
  {
    "id": 1,
    "name": "United States",
    "type": "country",
    "locations": [
      {
        "id": 5,
        "country_iso2": "US"
      }
    ],
    "free_shipping": {
      "enabled": false,
      "minimum_sub_total": "0.0000",
      "exclude_fixed_shipping_products": false
    },
    "enabled": true
  },
  {
    "id": 2,
    "name": "Australia",
    "type": "country",
    "locations": [
      {
        "id": 6,
        "country_iso2": "AU"
      }
    ],
    "free_shipping": {
      "enabled": false,
      "minimum_sub_total": "0.0000",
      "exclude_fixed_shipping_products": false
    },
    "enabled": true
  }
]

Example 2: Zone is Selection of States in a Country

[
  {
    "id": 2,
    "name": "States in the U.S.",
    "type": "state",
    "locations": [
      {
        "id": 3,
        "country_iso2": "US",
        "state_iso2": "TX"
      },
      {
        "id": 4,
        "country_iso2": "US",
        "state_iso2": "TX"
      }
    ],
    "free_shipping": {
      "enabled": false,
      "minimum_sub_total": "0",
      "exclude_fixed_shipping_products": true
    },
    "handling_fees": {
      "display_separately": false,
      "fixed_surcharge": 0
    },
    "enabled": false
  }
]

Create a Shipping Zone

POST https://api.bigcommerce.com/stores/{store_hash}/v2/shipping/zones

Request

Creates a Shipping Zone.

Authentication

X-Auth-Token in header - required

Parameters

store_hash in path - string
Content-Type in header with default of application/json - string - required
The MIME type of the request body.

Body

object | application/json

namestring
required
Zone name. Required for PUT requests.
Example: United States
typestring
required
Allowed: zip | country | state | global
locationsarray[object]
Array of zone locations.
free_shippingobject
handling_feesobject
One of:
- fixed_surchargestring
  Flat-rate handling fee applied to shipping cost.
  Example: 0
- display_separatelyboolean
  Indicates whether store displays handling fee separately at checkout.
  Example: true
enabledboolean
Whether this shipping zone is enabled.
Example: true

Type: ZIP

{
  "name": "United States",
  "type": "zip",
  "locations": [
    {
      "zip": "11103",
      "country_iso2": "US"
    }
  ]
}

Type: Country

{
  "name": "Mexico",
  "type": "country",
  "locations": [
    {
      "country_iso2": "MX"
    }
  ]
}

Type: State

{
  "name": "South Carolina",
  "type": "state",
  "locations": [
    {
      "country_iso2": "US",
      "state_iso2": "SC"
    }
  ]
}

Type: Global

{
  "name": "Global",
  "type": "global"
}

Response

Body

object | application/json

idinteger
Zone ID.
Example: 1
namestring
Zone name.
Example: United States
typestring
Allowed: zip | country | state | global
locationsarray[object]
Array of zone locations.
free_shippingobject
handling_feesobject
One of:
- fixed_surchargestring
  Flat-rate handling fee applied to shipping cost.
  Example: 0
- display_separatelyboolean
  Indicates whether store displays handling fee separately at checkout.
  Example: true
enabledboolean
Whether this shipping zone is enabled.
Example: true

Get a Shipping Zones

GET https://api.bigcommerce.com/stores/{store_hash}/v2/shipping/zones/{id}

Request

Returns a single Shipping Zone.

Authentication

X-Auth-Token in header - required

Parameters

store_hash in path - string
Accept in header with default of application/json - string - required
The MIME type of the response body.
id in path - integer - required
ID of the shipping zone.

example

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v2/shipping/zones/[id]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Body

object | application/json

idinteger
Zone ID
Example: 1
namestring
Zone name.
Example: United States
typestring
Allowed: zip | country | state | global
locationsarray[object]
Array of zone locations.
free_shippingobject
handling_feesobject
One of:
- fixed_surchargestring
  Flat-rate handling fee applied to shipping cost.
  Example: 0
- display_separatelyboolean
  Indicates whether store displays handling fee separately at checkout.
  Example: true
enabledboolean
Whether this shipping zone is enabled.
Example: true

example

{
  "id": 1,
  "name": "United States",
  "type": "zip",
  "locations": [
    {
      "id": 3,
      "zip": "12345",
      "country_iso2": "US",
      "state_iso2": "TX"
    }
  ],
  "free_shipping": {
    "enabled": true,
    "minimum_sub_total": "0.0000",
    "exclude_fixed_shipping_products": true
  },
  "handling_fees": {
    "fixed_surcharge": "0",
    "display_separately": true
  },
  "enabled": true
}

Update a Shipping Zone

PUT https://api.bigcommerce.com/stores/{store_hash}/v2/shipping/zones/{id}

Request

Updates a Shipping Zone.

Required Fields

name

Read Only Fields

Authentication

X-Auth-Token in header - required

Parameters

store_hash in path - string
id in path - integer - required
ID of the shipping zone.
Content-Type in header with default of application/json - string - required
The MIME type of the request body.

Body

object | application/json

idinteger
Zone ID. Read-only.
Example: 1
namestring
required
Zone name. Required for PUT requests.
Example: United States
typestring
Allowed: zip | country | state | global
locationsarray[object]
Array of zone locations.
free_shippingobject
handling_feesobject
One of:
- fixed_surchargestring
  Flat-rate handling fee applied to shipping cost.
  Example: 0
- display_separatelyboolean
  Indicates whether store displays handling fee separately at checkout.
  Example: true
enabledboolean
Whether this shipping zone is enabled.
Example: true

example

{
  "name": "United States",
  "type": "zip",
  "locations": [
    {
      "id": 3,
      "zip": "12345",
      "country_iso2": "US",
      "state_iso2": "TX"
    }
  ],
  "free_shipping": {
    "enabled": true,
    "minimum_sub_total": "0.0000",
    "exclude_fixed_shipping_products": true
  },
  "handling_fees": {
    "fixed_surcharge": "0",
    "display_separately": true
  },
  "enabled": true
}

Response

Body

object | application/json

idinteger
Zone ID. Read-only.
Example: 1
namestring
required
Zone name. Required for PUT requests.
Example: United States
typestring
Allowed: zip | country | state | global
locationsarray[object]
Array of zone locations.
free_shippingobject
handling_feesobject
One of:
- fixed_surchargestring
  Flat-rate handling fee applied to shipping cost.
  Example: 0
- display_separatelyboolean
  Indicates whether store displays handling fee separately at checkout.
  Example: true
enabledboolean
Whether this shipping zone is enabled.
Example: true

example

{
  "name": "United States",
  "type": "zip",
  "locations": [
    {
      "id": 3,
      "zip": "12345",
      "country_iso2": "US",
      "state_iso2": "TX"
    }
  ],
  "free_shipping": {
    "enabled": true,
    "minimum_sub_total": "0.0000",
    "exclude_fixed_shipping_products": true
  },
  "handling_fees": {
    "fixed_surcharge": "0",
    "display_separately": true
  },
  "enabled": true
}

Delete a Shipping Zone

DELETE https://api.bigcommerce.com/stores/{store_hash}/v2/shipping/zones/{id}

Request

Deletes a Shipping Zone.

Authentication

X-Auth-Token in header - required

Parameters

store_hash in path - string
Accept in header with default of application/json - string - required
The MIME type of the response body.
id in path - integer - required
ID of the shipping zone.

example

curl --request DELETE \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v2/shipping/zones/[id]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Get All Shipping Zones

Request

Authentication

Parameters

example

Response

Body

idinteger

namestring

typestring

locationsarray[object]

free_shippingobject

handling_feesobject

fixed_surchargestring

display_separatelyboolean

enabledboolean

Example 1: Zones are Country Zones

Example 2: Zone is Selection of States in a Country

Create a Shipping Zone

Request

Authentication

Parameters

Body

namestringrequired

typestringrequired

locationsarray[object]

free_shippingobject

handling_feesobject

fixed_surchargestring

display_separatelyboolean

enabledboolean

Type: ZIP

Type: Country

Type: State

Type: Global

Response

Body

idinteger

namestring

typestring

locationsarray[object]

free_shippingobject

handling_feesobject

fixed_surchargestring

display_separatelyboolean

enabledboolean

Get a Shipping Zones

Request

Authentication

Parameters

example

Response

Body

idinteger

namestring

typestring

locationsarray[object]

free_shippingobject

handling_feesobject

fixed_surchargestring

display_separatelyboolean

enabledboolean

example

Update a Shipping Zone

Request

Authentication

Parameters

Body

idinteger

namestringrequired

typestring

locationsarray[object]

free_shippingobject

handling_feesobject

fixed_surchargestring

display_separatelyboolean

enabledboolean

example

Response

Body

namestring
required

typestring
required

namestring
required

namestring
required