Shipping Method

Get All Shipping Methods in a Zone

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

Request

Returns a list of Shipping Methods in a zone. Default sorting is by shipping method ID, from lowest to highest.

Authentication

X-Auth-Token in header
required

Parameters

store_hash in path - string
zone_id in path - integer
required
ID of the shipping zone.

example

Response

Body

array | application/json

Example 1

Example 2

Create a Shipping Method

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

Request

Creates a Shipping Method within a shipping zone. Real Time Carrier Connections are also supported by this endpoint.

Carrier Configurations – Current

This section provides a sample request and a carrier-specific object/property model, for each supported carrier.

USPS by Endicia

Example request body:

{
    "name": "USPS by Endicia",
    "type": "endicia",
    "settings": {
        "carrier_options": {
            "delivery_services" : ["PriorityExpress","Priority", "PriorityMailExpressInternational"],
            "packaging_type" : "LargeFlatRateBox",
            "show_transit_time" : true
        }
    },
    "enabled": true
}

USPS by Endicia Object Properties

Property	Type	Values
delivery_services	array	PriorityExpress, PriorityMailExpressInternational, FirstClassPackageInternationalService, Priority, PriorityMailInternational, First, ParcelSelect, MediaMail
packaging_type	array	FlatRateLegalEnvelope, FlatRatePaddedEnvelope, Parcel, SmallFlatRateBox, MediumFlatRateBox, LargeFlatRateBox, FlatRateEnvelope, RegionalRateBoxA, RegionalRateBoxB
show_transit_time	boolean	true, false

FedEx

Example request body:

{
    "name": "FEDEX",
    "type": "fedex",
    "settings": {
        "carrier_options": {
            "delivery_services": [
                "PRIORITY_OVERNIGHT",
                "FEDEX_2_DAY"
            ],
            "dropoff_type": "REGULAR_PICKUP",
            "packaging_type": "FEDEX_ENVELOPE",
            "packing_method": "SEPARATE",
            "rate_type": "NONE",
            "include_package_value": true,
            "destination_type": "residential"
        }
    },
    "enabled": true
}

FedEx Object Properties

Property	Type	Values
delivery_services	array	PRIORITY_OVERNIGHT, STANDARD_OVERNIGHT, FIRST_OVERNIGHT, FEDEX_2_DAY, FEDEX_EXPRESS_SAVER, INTERNATIONAL_PRIORITY, INTERNATIONAL_ECONOMY, INTERNATIONAL_FIRST, FEDEX_1_DAY_FREIGHT, FEDEX_2_DAY_FREIGHT, FEDEX_3_DAY_FREIGHT, FEDEX_GROUND, GROUND_HOME_DELIVERY, INTERNATIONAL_PRIORITY_FREIGHT, INTERNATIONAL_ECONOMY_FREIGHT, EUROPE_FIRST_INTERNATIONAL_PRIORITY
dropoff_type	string	REGULAR_PICKUP, REQUEST_COURIER, DROP_BOX, BUSINESS_SERVICE_CENTER, STATION
packaging_type	string	FEDEX_ENVELOPE, FEDEX_PAK, FEDEX_BOX, FEDEX_TUBE, FEDEX_10KG_BOX, FEDEX_25KG_BOX, YOUR_PACKAGING
packing_method	string	SEPARATE, COMBINED
rate_type	string	NONE, LIST
include_package_value	boolean	true, false
destination_type	string	residential, business

UPS Ready

Example request body:

{
    "name": "UPS ready",
    "type": "upsready",
    "settings": {
        "carrier_options": {
            "delivery_services": [
                "2nd_Day_Air","Standard"
            ],
            "packaging_type": "21",
            "packing_method": "separate",
            "include_package_value": true,
            "destination_type": "residential",
            "show_transit_time" : true
        }
    },
    "enabled": true
}

UPS Ready Object Properties

Property	Type	Values
delivery_services	array	2nd_Day_Air, 2nd_Day_Air_AM, 3_Day_Select, Expedited, Express, Express_Plus, Express_Saver, Express_Early_AM, Ground, Next_Day_Air, Next_Day_Air_Early_AM, Next_Day_Air_Saver, Saver, Standard, Today_Dedicated_Courier, Today_Express, Today_Express_Saver, Today_Intercity, Today_Standard, Worldwide_Expedited, Worldwide_Express, Worldwide_Express_Plus, Worldwide_Express_Saver, Worldwide_Saver
destination_type	string	residential, business
packing_method	string	separate, combined
packaging_type	string (only codes allowed)	See the following table
include_package_value	boolean	true, false
show_transit_time	boolean	true, false

UPS packaging_type values include:

Code	Description
21	UPS® Express Box
24	UPS® 25 KG Box
25	UPS® 10 KG Box
30	Pallet
01	UPS® Letter
02	Customer Supplied Package
03	Tube
04	PAK
2a	Small Express Box
2b	Medium Express Box
2c	Large Express Box

Canada Post

Example request body:

{
    "name": "Canada Post",
    "type": "canadapost",
    "settings": {
        "carrier_options": {
            "delivery_services": [
                "DOM.RP","DOM.EP"
            ]
        }
    },
    "enabled": true
}

Canada Post Object Properties

Property	Type	Values
delivery_services	array	DOM.RP, DOM.EP, DOM.XP, DOM.XP.CERT, DOM.PC DOM.LIB, USA.EP, USA.PW.ENV, USA.PW.PAK, USA.PW.PARCEL, USA.SP.AIR, USA.TP, USA.TP.LVM, USA.XP, INT.XP, INT.IP.AIR, INT.IP.SURF, INT.PW.ENV, INT.PW.PAK, INT.PW.PARCEL, INT.SP.AIR, INT.SP.SURF, INT.TP

Australia Post

Example request body:

{
    "name": "Australia Post",
    "type": "auspost",
    "settings": {
        "carrier_options": {
            "delivery_services": [
                "AUS_PARCEL_REGULAR",
        "AUS_PARCEL_EXPRESS"
            ]
        }
    },
    "enabled": true
}

Australia Post Object Properties

Property	Type	Values
delivery_services	array	AUS_LETTER_REGULAR_SMALL, AUS_LETTER_REGULAR_Large, AUS_LETTER_EXPRESS_SMALL, AUS_LETTER_EXPRESS_MEDIUM, AUS_LETTER_EXPRESS_LARGE, AUS_PARCEL_REGULAR, AUS_PARCEL_REGULAR_SATCHEL_500G, AUS_PARCEL_REGULAR_SATCHEL_3KG, AUS_PARCEL_REGULAR_SATCHEL_5KG, AUS_PARCEL_EXPRESS, AUS_PARCEL_EXPRESS_SATCHEL_500G, AUS_PARCEL_EXPRESS_SATCHEL_3KG, AUS_PARCEL_EXPRESS_SATCHEL_5KG, AUS_PARCEL_COURIER, AUS_PARCEL_COURIER_SATCHEL_MEDIUM, INT_PARCEL_COR_OWN_PACKAGING, INT_PARCEL_EXP_OWN_PACKAGING, INT_PARCEL_STD_OWN_PACKAGING, INT_PARCEL_AIR_OWN_PACKAGING, INT_PARCEL_SEA_OWN_PACKAGING

Royal Mail

Example request body:

{
    "name": "Royal Mail",
    "type": "royalmail",
    "settings": {
        "carrier_options": {
            "delivery_services": [
                "StandardFirstClass",
                "StandardSecondClass"
            ]
        }
    },
    "enabled": true
}

Royal Mail Object Properties

Property	Type	Values
delivery_services	array	SpecialDelivery1pm, SpecialDelivery9am, SpecialDelivery1pmSaturday, SpecialDelivery9amSaturday, SignedForFirstClass, SignedForSecondClass, Express9, Express10, ExpressAM, Express24, Express48, StandardFirstClass, StandardSecondClass, InternationalStandard, InternationalTracked, InternationalEconomy

Zoom2U

Example request body:

{
    "name": "Zoom2U",
    "type": "zoom2u",
    "settings": {
        "carrier_options": {
            "delivery_services": [
                "3_hour",
        "Same_day",
        "VIP"
            ]
        }
    },
    "enabled": true
}

Zoom2U Object Properties

Property	Type	Values
delivery_services	array	3_hour, Same_day, VIP

Settings Objects

A shipping methodʼs type and settings properties can match one of the following models:

perorder Object – Properties

Object model for flat-rate shipping quotes per order.

Property	Type	Description
rate	number	Flat rate per order.

Example request body:

{
  "name": "Flat Rate per Order",
  "type": "perorder",
  "settings": {
    "rate": 7
  }
}

peritem Object – Properties

Object model for flat-rate shipping quotes per item ordered.

Name	Type	Description
rate	number	Flat rate per item.

Ezample request body:

{
  "name": "Flat Rate per Item",
  "type": "peritem",
  "settings": {
    "rate": 8
  }
}

weight Object – Properties

Object model for shipping quotes by weight.

Property	Type	Description
default_cost	number \| null	Default shipping cost, applied either as a percentage of the orderʼs total value or as a fixed amount. If default cost is not required, you can supply a value of null.
default_cost_type	string	How the default shipping cost is calculated; either `percentage_of_total` or `fixed_amount`.
range	number	Array of range objects. The units for these ranges' `lower_limit` and `upper_limit` properties depend on the default units set in the storeʼs control panel.

Example request body:

{
  "name": "Rate per Weight",
  "type": "weight",
  "settings": {
    "default_cost": 12,
    "default_cost_type": "fixed_amount",
    "range": [
      {
        "lower_limit": 0,
        "upper_limit": 20,
        "shipping_cost": 8
      },
      {
        "lower_limit": 20,
        "upper_limit": 40,
        "shipping_cost": 12
      }
    ]
  }
}

total Object – Properties

Object model for shipping quotes by orderʼs total value.

Property	Type	Description
default_cost	number \| null	Default shipping cost, applied either as a percentage of the orderʼs total value or as a fixed amount. If default cost is not required, you can supply a value of null.
default_cost_type	string	How the default shipping cost is calculated; either `percentage_of_total` or `fixed_amount`.
range	number	Array of range objects. The units for these ranges' `lower_limit` and `upper_limit` properties are values in the storeʼs currency.

Example request body:

This example sets free shipping above a certain order total:

{
  "name": "Per Total or Free",
  "type": "total",
  "settings": {
    "default_cost": 12,
    "default_cost_type": "fixed_amount",
    "range": [
      {
        "lower_limit": 0,
        "upper_limit": 5,
        "shipping_cost": 5
      },
      {
        "lower_limit": 5,
        "upper_limit": 10,
        "shipping_cost": 8
      },
      {
        "lower_limit": 10,
        "upper_limit": 20,
        "shipping_cost": 10
      },
      {
        "lower_limit": 20,
        "upper_limit": 49.99,
        "shipping_cost": 15
      },
      {
        "lower_limit": 50,
        "upper_limit": 100000,
        "shipping_cost": 0
      }       
    ]
  }
}

Range Object – Properties

Object model to define ranges for shipping quotes. Units are defined in the parent object.

Property	Type	Description
lower_limit	number	Lower limit for order total.
upper_limit	number	Upper limit for order total.
shipping_cost	number	Shipping cost for orders whose total falls between the lower and upper limits.

Example request body:

{
  "lower_limit": 0,
  "upper_limit": 20,
  "shipping_cost": 8
}

Authentication

X-Auth-Token in header
required

Parameters

store_hash in path - string
zone_id in path - integer
required
ID of the shipping zone.

Body

object | application/json

namestring
Display name for shipping method.
Example: Flat Rate
typestring
Allowed: perorder | peritem | weight | total | auspost | canadapost | endicia | usps | fedex | royalmail | upsready | freeshipping
Example: perorder
settingsobject
Depends on the shipping method type. See the supported settings object.
enabledboolean
Whether or not this shipping zone method is enabled.
Example: true
handling_fees
Any of:
- fixed_surchargenumber
  Flat-rate handling fee applied to shipping cost.
is_fallbackboolean
Whether or not this shipping zone is the fallback if all others are not valid for the order.

example

Response

Body

application/json

Example 1

Example 2

Get a Shipping Method

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

Request

Returns a single Shipping Method in a zone. Real Time Carrier Connections are also supported by this endpoint.

Settings Objects

A shipping methodʼs type and settings properties can match one of the following models:

perorder Object – Properties

Object model for flat-rate shipping quotes per order.

Name	Type	Description
rate	number	Flat rate per order.

JSON Example

{
    "name": "Flat Rate per Order",
    "type": "perorder",
    "settings": {
        "rate": 7
},

peritem Object – Properties

Object model for flat-rate shipping quotes per item ordered.

Name	Type	Description
rate	number	Flat rate per item.

JSON Example

{
    "name": "Flat Rate per Item",
    "type": "peritem",
    "settings": {
        "rate": 8
},

weight Object – Properties

Object model for shipping quotes by weight.

Name	Type	Description
default_cost	number \| null	Default shipping cost, applied either as a percentage of the orderʼs total value or as a fixed amount. If default cost is not required, you can supply a value of null.
default_cost_type	string	How the default shipping cost is calculated; either `percentage_of_total` or `fixed_amount`.
range	number	Array of range objects. The units for these ranges' `lower_limit` and `upper_limit` properties depend on the default units set in the storeʼs control panel.

JSON Example

{
    "name": "Rate per Weight",
    "type": "weight",
    "settings": {
        "default_cost": 12,
        "default_cost_type": "fixed_amount",
        "range": [
            {
                "lower_limit": 0,
                "upper_limit": 20,
                "shipping_cost": 8
            },
            {
                "lower_limit": 20,
                "upper_limit": 40,
                "shipping_cost": 12
            }
        ]
    }
}

total Object – Properties

Object model for shipping quotes by orderʼs total value.

Name	Type	Description
default_cost	number \| null	Default shipping cost, applied either as a percentage of the orderʼs total value or as a fixed amount. If default cost is not required, you can supply a value of null.
default_cost_type	string	How the default shipping cost is calculated; either `percentage_of_total` or `fixed_amount`.
range	number	Array of range objects. The units for these ranges' `lower_limit` and `upper_limit` properties are values in the storeʼs currency.

JSON Example

This example sets free shipping above a certain order total:

{
    "name": "Per Total or Free",
    "type": "total",
    "settings": {
        "default_cost": 12,
        "default_cost_type": "fixed_amount",
        "range": [
            {
                "lower_limit": 0,
                "upper_limit": 5,
                "shipping_cost": 5
            },
            {
                "lower_limit": 5,
                "upper_limit": 10,
                "shipping_cost": 8
            },
            {
                "lower_limit": 10,
                "upper_limit": 20,
                "shipping_cost": 10
            },
            {
                "lower_limit": 20,
                "upper_limit": 49.99,
                "shipping_cost": 15
            },
            {
                "lower_limit": 50,
                "upper_limit": 100000,
                "shipping_cost": 0
            }
        ]
    }
}

Range Object – Properties

Object model to define ranges for shipping quotes. Units are defined in the parent object.

Name	Type	Description
lower_limit	number	Lower limit for order total.
upper_limit	number	Upper limit for order total.
shipping_cost	number	Shipping cost for orders whose total falls between the lower and upper limits.

JSON Example

{
    "lower_limit": 0,
    "upper_limit": 20,
    "shipping_cost": 8
}

Authentication

X-Auth-Token in header
required

Parameters

store_hash in path - string
zone_id in path - integer
required
ID of the shipping zone.
method_id in path - integer
required
ID of the shipping method within the shipping zone.

example

Response

Body

object | application/json

idinteger
read-only
Shipping method ID. Read-only.
Example: 1
namestring
Display name for shipping method.
Example: Flat Rate
typestring
Allowed: perorder | peritem | weight | total | auspost | canadapost | endicia | usps | fedex | royalmail | upsready | freeshipping
Example: perorder
settingsobject
Depends on the shipping method type. See the supported settings object.
enabledboolean
Whether or not this shipping zone method is enabled.
Example: true
handling_fees
Any of:
- fixed_surchargenumber
  Flat-rate handling fee applied to shipping cost.
is_fallbackboolean
Whether or not this shipping zone is the fallback if all others are not valid for the order.

Example 1

Example 2

Update a Shipping Method

PUT https://api.bigcommerce.com/stores/{store_hash}/v2/shipping/zones/{zone_id}/methods/{method_id}

Request

Updates a Shipping Method in a zone. Real Time Carrier Connections are also supported by this endpoint.

Read Only Fields

Settings Objects

A shipping methodʼs type and settings properties can match one of the following models:

perorder Object – Properties

Object model for flat-rate shipping quotes per order.

Property	Type	Description
rate	number	Flat rate per order.

Example response:

{
  "name": "Flat Rate per Order",
  "type": "perorder",
  "settings": {
    "rate": 7
  }
},

peritem Object – Properties

Object model for flat-rate shipping quotes per item ordered.

Property	Type	Description
rate	number	Flat rate per item.

Example response:

{
  "name": "Flat Rate per Item",
  "type": "peritem",
  "settings": {
    "rate": 8
  }
},

weight Object – Properties

Object model for shipping quotes by weight.

Property	Type	Description
default_cost	number \| null	Default shipping cost, applied either as a percentage of the orderʼs total value or as a fixed amount. If default cost is not required, you can supply a value of null.
default_cost_type	string	How the default shipping cost is calculated; either `percentage_of_total` or `fixed_amount`.
range	number	Array of range objects. The units for these ranges' `lower_limit` and `upper_limit` properties depend on the default units set in the storeʼs control panel.

Example response:

{
  "name": "Rate per Weight",
  "type": "weight",
  "settings": {
    "default_cost": 12,
    "default_cost_type": "fixed_amount",
    "range": [
      {
        "lower_limit": 0,
        "upper_limit": 20,
        "shipping_cost": 8
      },
      {
        "lower_limit": 20,
        "upper_limit": 40,
        "shipping_cost": 12
      }
    ]
  }
}

total Object – Properties

Object model for shipping quotes by orderʼs total value.

Property	Type	Description
default_cost	number \| null	Default shipping cost, applied either as a percentage of the orderʼs total value or as a fixed amount. If default cost is not required, you can supply a value of null.
default_cost_type	string	How the default shipping cost is calculated; either `percentage_of_total` or `fixed_amount`.
range	number	Array of range objects. The units for these ranges' `lower_limit` and `upper_limit` properties are values in the storeʼs currency.

Example response:

This example sets free shipping above a certain order total:

{
  "name": "Per Total or Free",
  "type": "total",
  "settings": {
    "default_cost": 12,
    "default_cost_type": "fixed_amount",
    "range": [
      {
        "lower_limit": 0,
        "upper_limit": 5,
        "shipping_cost": 5
      },
      {
        "lower_limit": 5,
        "upper_limit": 10,
        "shipping_cost": 8
      },
      {
        "lower_limit": 10,
        "upper_limit": 20,
        "shipping_cost": 10
      },
      {
        "lower_limit": 20,
        "upper_limit": 49.99,
        "shipping_cost": 15
      },
      {
        "lower_limit": 50,
        "upper_limit": 100000,
        "shipping_cost": 0
      }       
    ]
  }
}

Range Object – Properties

Object model to define ranges for shipping quotes. Units are defined in the parent object.

Property	Type	Description
lower_limit	number	Lower limit for order total.
upper_limit	number	Upper limit for order total.
shipping_cost	number	Shipping cost for orders whose total falls between the lower and upper limits.

Example response:

{
  "lower_limit": 0,
  "upper_limit": 20,
  "shipping_cost": 8
}

Authentication

X-Auth-Token in header
required

Parameters

store_hash in path - string
zone_id in path - integer
required
ID of the shipping zone.
method_id in path - integer
required
ID of the shipping method within the shipping zone.

Body

object | application/json

namestring
Display name for shipping method.
Example: Flat Rate
typestring
Allowed: perorder | peritem | weight | total | auspost | canadapost | endicia | usps | fedex | royalmail | upsready | freeshipping
Example: perorder
settingsobject
Depends on the shipping method type. See the supported settings object.
enabledboolean
Whether or not this shipping zone method is enabled.
Example: true
handling_fees
Any of:
- fixed_surchargenumber
  Flat-rate handling fee applied to shipping cost.
is_fallbackboolean
Whether or not this shipping zone is the fallback if all others are not valid for the order.

example

Response

Body

application/json

Example 1

Example 2

Delete a Shipping Method

DELETE https://api.bigcommerce.com/stores/{store_hash}/v2/shipping/zones/{zone_id}/methods/{method_id}

Request

Deletes an Shipping Method. Real Time Carrier Connections can also be deleted.

Authentication

X-Auth-Token in header
required

Parameters

store_hash in path - string
zone_id in path - integer
required
ID of the shipping zone.
method_id in path - integer
required
ID of the shipping method within the shipping zone.

example

Response

Did you find what you were looking for?

Delete a Carrier Connection Get All Shipping Methods in a Zone

Shipping Method

Get All Shipping Methods in a Zone

Request

Authentication

Parameters

example

Response

Body

Example 1

Example 2

Create a Shipping Method

Request

Carrier Configurations – Current

USPS by Endicia

USPS by Endicia Object Properties

FedEx

FedEx Object Properties

UPS Ready

UPS Ready Object Properties

Canada Post

Canada Post Object Properties

Australia Post

Australia Post Object Properties

Royal Mail

Royal Mail Object Properties

Zoom2U

Zoom2U Object Properties

Settings Objects

perorder Object – Properties

peritem Object – Properties

weight Object – Properties

total Object – Properties

Range Object – Properties

Authentication

Parameters

Body

namestring

typestring

settingsobject

enabledboolean

handling_fees

fixed_surchargenumber

is_fallbackboolean

example

Response

Body

Example 1

Example 2

Get a Shipping Method

Request

Settings Objects

perorder Object – Properties

JSON Example

peritem Object – Properties

JSON Example

weight Object – Properties

JSON Example

total Object – Properties

JSON Example

Range Object – Properties

JSON Example

Authentication

Parameters

example

Response

Body

idintegerread-only

namestring

typestring

settingsobject

enabledboolean

handling_fees

fixed_surchargenumber

is_fallbackboolean

Example 1

Example 2

Update a Shipping Method

Request

Settings Objects

perorder Object – Properties

idinteger
read-only