Skip to navigation
RESTAdminManagementShippingV2Shipping Method

Create Shipping Method

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

PropertyTypeValues
delivery_servicesarrayPriorityExpress, PriorityMailExpressInternational, FirstClassPackageInternationalService, Priority, PriorityMailInternational, First, ParcelSelect, MediaMail
packaging_typearrayFlatRateLegalEnvelope, FlatRatePaddedEnvelope, Parcel, SmallFlatRateBox, MediumFlatRateBox, LargeFlatRateBox, FlatRateEnvelope, RegionalRateBoxA, RegionalRateBoxB
show_transit_timebooleantrue, 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

PropertyTypeValues
delivery_servicesarrayPRIORITY_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_typestringREGULAR_PICKUP, REQUEST_COURIER, DROP_BOX, BUSINESS_SERVICE_CENTER, STATION
packaging_typestringFEDEX_ENVELOPE, FEDEX_PAK, FEDEX_BOX, FEDEX_TUBE, FEDEX_10KG_BOX, FEDEX_25KG_BOX, YOUR_PACKAGING
packing_methodstringSEPARATE, COMBINED
rate_typestringNONE, LIST
include_package_valuebooleantrue, false
destination_typestringresidential, 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

PropertyTypeValues
delivery_servicesarray2nd_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_typestringresidential, business
packing_methodstringseparate, combined
packaging_typestring (only codes allowed)See the following table
include_package_valuebooleantrue, false
show_transit_timebooleantrue, false

UPS packaging_type values include:

CodeDescription
21UPS® Express Box
24UPS® 25 KG Box
25UPS® 10 KG Box
30Pallet
01UPS® Letter
02Customer Supplied Package
03Tube
04PAK
2aSmall Express Box
2bMedium Express Box
2cLarge 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

PropertyTypeValues
delivery_servicesarrayDOM.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

PropertyTypeValues
delivery_servicesarrayAUS_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

PropertyTypeValues
delivery_servicesarraySpecialDelivery1pm, 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

PropertyTypeValues
delivery_servicesarray3_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.

PropertyTypeDescription
ratenumberFlat 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.

NameTypeDescription
ratenumberFlat rate per item.

Example request body:

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

weight Object – Properties

Object model for shipping quotes by weight.

PropertyTypeDescription
default_costnumber | nullDefault 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_typestringHow the default shipping cost is calculated; either percentage_of_total or fixed_amount.
rangenumberArray 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.

PropertyTypeDescription
default_costnumber | nullDefault 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_typestringHow the default shipping cost is calculated; either percentage_of_total or fixed_amount.
rangenumberArray 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.

PropertyTypeDescription
lower_limitnumberLower limit for order total.
upper_limitnumberUpper limit for order total.
shipping_costnumberShipping cost for orders whose total falls between the lower and upper limits.

Example request body:

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

Channels

Example request body:

{
  "name": "Method associated to channels 1, 3",
  "type": "peritem",
  "settings": {
    "rate": 5
  },
  "channel_ids": [1, 3]
}
PropertyTypeDescription
channel_idsarrayChannels associated with the method as an array of integers.

Authentication

X-Auth-Tokenstring

OAuth scopes

UI NamePermissionParameter
Information & Settingsmodifystore_v2_information
Information & Settingsread-onlystore_v2_information_read_only

Authentication header

HeaderArgumentDescription
X-Auth-Tokenaccess_tokenFor more about API accounts that generate access_tokens, see our Guide to API Accounts.

Further reading

For example requests and more information about authenticating BigCommerce APIs, see Authentication and Example Requests.

For more about BigCommerce OAuth scopes, see our Guide to API Accounts.

For a list of API status codes, see API Status Codes.

Path parameters

zone_idintegerRequired
ID of the shipping zone.
store_hashstringRequired
Permanent ID of the BigCommerce store.

Headers

AcceptstringRequiredDefaults to application/json

The MIME type of the response body.

Request

This endpoint expects an object.
namestringOptional
Display name for shipping method.
typeenumOptional
settingsobjectOptional

Depends on the shipping method type. See the supported settings object.

enabledbooleanOptional
Whether or not this shipping zone method is enabled.
handling_feesobjectOptional
is_fallbackbooleanOptional
Whether or not this shipping method is a fallback method used when advanced shipping rules are unavailable.
channel_idslist of integersOptional

List of channels associated to a method. When creating a new method, all available channels are associated by default. (Optional)

Response

OK
channel_idslist of integersOptional

List of channels associated to a method. When creating a new method, all available channels are associated by default. (Optional)

enabledbooleanOptional
Whether or not this shipping zone method is enabled.
handling_feesobjectOptional
idintegerOptionalRead-only

Shipping method ID. Read-only.

is_fallbackbooleanOptional
Whether or not this shipping method is a fallback method used when advanced shipping rules are unavailable.
namestringOptional
Display name for shipping method.
settingsobjectOptional

Depends on the shipping method type. See the supported settings object.

typeenumOptional