BigCommerce
Management API
Shipping Method

Shipping V2

Get All Shipping Methods in a Zone

GET /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
  • Accept in header with default of application/json - string - required

    The MIME type of the response body.

  • 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 /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

    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.

    Ezample 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
    }
    

    Authentication

    • X-Auth-Token in header - required

    Parameters

    • store_hash in path - string
    • zone_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
    • name
      string

      Display name for shipping method.

      Example: Flat Rate

    • type
      string

      Allowed: perorder | peritem | weight | total | auspost | canadapost | endicia | usps | fedex | royalmail | upsready | freeshipping

      Example: perorder

    • settings
      object

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

    • enabled
      boolean

      Whether or not this shipping zone method is enabled.

      Example: true

    • handling_fees
      object

      One of:
      • fixed_surcharge
        number

        Flat-rate handling fee applied to shipping cost.

        Example: 0

    • is_fallback
      boolean

      Whether or not this shipping zone is the fallback if all others are not valid for the order.

      Example: false

    example

    Response

    Body

    application/json
    • id
      integer

      Shipping method ID. Read-only.

      Example: 1

    • name
      string

      Display name for shipping method.

      Example: Flat Rate

    • type
      string

      Allowed: perorder | peritem | weight | total | auspost | canadapost | endicia | usps | fedex | royalmail | upsready | freeshipping

      Example: perorder

    • settings
      object

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

    • enabled
      boolean

      Whether or not this shipping zone method is enabled.

      Example: true

    • handling_fees
      object

      One of:
      • fixed_surcharge
        number

        Flat-rate handling fee applied to shipping cost.

        Example: 0

    • is_fallback
      boolean

      Whether or not this shipping zone is the fallback if all others are not valid for the order.

      Example: false

      Example 1

      Example 2

      Get a Shipping Method

      GET /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.

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

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

      NameTypeDescription
      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.

      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.

      NameTypeDescription
      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.

      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.

      NameTypeDescription
      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.

      JSON Example

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

      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.

      • 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
      • id
        integer

        Shipping method ID. Read-only.

        Example: 1

      • name
        string

        Display name for shipping method.

        Example: Flat Rate

      • type
        string

        Allowed: perorder | peritem | weight | total | auspost | canadapost | endicia | usps | fedex | royalmail | upsready | freeshipping

        Example: perorder

      • settings
        object

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

      • enabled
        boolean

        Whether or not this shipping zone method is enabled.

        Example: true

      • handling_fees
        object

        One of:
        • fixed_surcharge
          number

          Flat-rate handling fee applied to shipping cost.

          Example: 0

      • is_fallback
        boolean

        Whether or not this shipping zone is the fallback if all others are not valid for the order.

        Example: false

      Example 1

      Example 2

      Update a Shipping Method

      PUT /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

      • id

      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 response:

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

      peritem Object – Properties

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

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

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

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

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

      • Content-Type in header with default of application/json - string - required

        The MIME type of the request body.

      Body

      object | application/json
      • name
        string

        Display name for shipping method.

        Example: Flat Rate

      • type
        string

        Allowed: perorder | peritem | weight | total | auspost | canadapost | endicia | usps | fedex | royalmail | upsready | freeshipping

        Example: perorder

      • settings
        object

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

      • enabled
        boolean

        Whether or not this shipping zone method is enabled.

        Example: true

      • handling_fees
        object

        One of:
        • fixed_surcharge
          number

          Flat-rate handling fee applied to shipping cost.

          Example: 0

      • is_fallback
        boolean

        Whether or not this shipping zone is the fallback if all others are not valid for the order.

        Example: false

      example

      Response

      Body

      application/json
      • id
        integer

        Shipping method ID. Read-only.

        Example: 1

      • name
        string

        Display name for shipping method.

        Example: Flat Rate

      • type
        string

        Allowed: perorder | peritem | weight | total | auspost | canadapost | endicia | usps | fedex | royalmail | upsready | freeshipping

        Example: perorder

      • settings
        object

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

      • enabled
        boolean

        Whether or not this shipping zone method is enabled.

        Example: true

      • handling_fees
        object

        One of:
        • fixed_surcharge
          number

          Flat-rate handling fee applied to shipping cost.

          Example: 0

      • is_fallback
        boolean

        Whether or not this shipping zone is the fallback if all others are not valid for the order.

        Example: false

        Example 1

        Example 2

        Delete a Shipping Method

        DELETE /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
        • Accept in header with default of application/json - string - required

          The MIME type of the response body.

        • 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?