Custom Shipping Methods API

The Custom Shipping Methods API lets you manage an account's manually-defined shipping options through your secret API key. A shipping method is a named shipping option (for example "Standard" or "Express") with a list of rates[] that can be tiered by order weight and/or order total, and optionally restricted to specific countries/states and to addresses matching a postal-code regular expression. These are the same shipping methods you can configure in the dashboard under Shipping.

Requests are authenticated with your secret API key, sent as the HTTP Basic username with an empty password. With curl: -u {API_KEY}:. See Authentication for details. The base URL is always https://app.snipcart.com/api.

⚠️ Important: Weight values on rate conditions are expressed in grams.

⚠️ Important: Creating a shipping method enables shipping on the account if it was disabled.

Table of contents

GET /shipping_methods

Returns every custom shipping method defined on the account for the current mode (Live or Test, determined by the secret key used).

Resource URL

GET https://app.snipcart.com/api/shipping_methods

Headers

Name Value Required Description
Accept application/json Yes Response is JSON.

Example request 

curl https://app.snipcart.com/api/shipping_methods \
  -u {API_KEY}: \
  -H "Accept: application/json"

Example response 

[
  {
    "guaranteedEstimatedDelivery": {
      "minimumDaysForDelivery": 2,
      "maximumDaysForDelivery": 5
    },
    "rates": [
      {
        "cost": 10.00,
        "weight": {
          "from": 0,
          "to": 1000
        }
      },
      {
        "cost": 18.00,
        "weight": {
          "from": 1000,
          "to": 5000
        }
      }
    ],
    "postalCodeRegex": "G1K.*",
    "countryCondition": [
      {
        "countryCode": "CA",
        "provinceCode": "QC"
      }
    ],
    "name": "Standard",
    "localizationId": "standard-shipping",
    "onOrderTotalAbove": null,
    "Id": "5f1d3b2a-9c4e-4a1b-8d6f-2e7a1c0b9d34",
    "shippingZoneId": "north-america"
  }
]

GET /shipping_methods/{id}

Returns a single shipping method by its GUID. Returns 404 Not Found if no method with that id is owned by the authenticated account in the current mode.

Resource URL

GET https://app.snipcart.com/api/shipping_methods/{id}

Headers

Name Value Required Description
Accept application/json Yes Response is JSON.

Path Parameters

Name Required Type Description
id Yes guid The unique identifier of the shipping method.

Example request 

curl https://app.snipcart.com/api/shipping_methods/5f1d3b2a-9c4e-4a1b-8d6f-2e7a1c0b9d34 \
  -u {API_KEY}: \
  -H "Accept: application/json"

Example response 

{
  "guaranteedEstimatedDelivery": {
    "minimumDaysForDelivery": 2,
    "maximumDaysForDelivery": 5
  },
  "rates": [
    {
      "cost": 10.00,
      "weight": {
        "from": 0,
        "to": 1000
      }
    }
  ],
  "postalCodeRegex": "G1K.*",
  "countryCondition": [
    {
      "countryCode": "CA",
      "provinceCode": "QC"
    }
  ],
  "name": "Standard",
  "localizationId": "standard-shipping",
  "onOrderTotalAbove": null,
  "Id": "5f1d3b2a-9c4e-4a1b-8d6f-2e7a1c0b9d34",
  "shippingZoneId": "north-america"
}

POST /shipping_methods

Creates a new custom shipping method on the account. The created method is returned, including its generated Id.

⚠️ Important: Creating a shipping method enables shipping on the account if it was previously disabled.

Resource URL

POST https://app.snipcart.com/api/shipping_methods

Headers

Name Value Required Description
Accept application/json Yes Response is JSON.
Content-Type application/json Yes Request body is JSON.

Body Parameters

Name Required Type Description
name Yes string Display name of the shipping method.
localizationId No string Identifier used to localize the method's display name.
rates Yes array One or more rate tiers. See the rate object below.
onOrderTotalAbove No decimal If set, the method only applies when the order total is above this amount.
guaranteedEstimatedDelivery No object { "minimumDaysForDelivery": int, "maximumDaysForDelivery": int }. Estimated delivery window.
postalCodeRegex No string If set, the method only applies to shipping addresses whose postal code matches this regular expression.
countryCondition No array Restricts the method to specific countries/states. Each entry is { "countryCode": string, "provinceCode": string }. Omit or leave empty to allow all countries. See country condition.
shippingZoneId No string Optional identifier grouping this method into a shipping zone.

Rate object

Each entry of rates[] describes a cost and the conditions under which it applies. When multiple rates apply, the cheapest matching rate is used.

Name Required Type Description
cost Yes decimal The shipping cost for this rate.
weight No object Weight condition { "from": int, "to": int } in grams. Either bound may be omitted. The rate applies when the order's total weight falls in the range.
location No object Per-rate location condition { "country": string, "province": string }. (Most restrictions are better expressed at the method level via countryCondition.)

Country condition object

Name Required Type Description
countryCode Yes string ISO country code (e.g. US, CA).
provinceCode No string State/province code (e.g. QC, NY).

⚠️ Important: A legacy location field ({ "country": ..., "province": ... }) is still accepted at the top level of the body as an alias for countryCondition; it is obsolete and only kept for backward compatibility. Use countryCondition for new integrations.

Example request 

curl https://app.snipcart.com/api/shipping_methods \
  -u {API_KEY}: \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Standard",
    "localizationId": "standard-shipping",
    "rates": [
      { "cost": 10.00, "weight": { "from": 0, "to": 1000 } },
      { "cost": 18.00, "weight": { "from": 1000, "to": 5000 } }
    ],
    "guaranteedEstimatedDelivery": {
      "minimumDaysForDelivery": 2,
      "maximumDaysForDelivery": 5
    },
    "postalCodeRegex": "G1K.*",
    "countryCondition": [
      { "countryCode": "CA", "provinceCode": "QC" }
    ],
    "shippingZoneId": "north-america"
  }'

Example response 

{
  "guaranteedEstimatedDelivery": {
    "minimumDaysForDelivery": 2,
    "maximumDaysForDelivery": 5
  },
  "rates": [
    {
      "cost": 10.00,
      "weight": {
        "from": 0,
        "to": 1000
      }
    },
    {
      "cost": 18.00,
      "weight": {
        "from": 1000,
        "to": 5000
      }
    }
  ],
  "postalCodeRegex": "G1K.*",
  "countryCondition": [
    {
      "countryCode": "CA",
      "provinceCode": "QC"
    }
  ],
  "name": "Standard",
  "localizationId": "standard-shipping",
  "onOrderTotalAbove": null,
  "Id": "5f1d3b2a-9c4e-4a1b-8d6f-2e7a1c0b9d34",
  "shippingZoneId": "north-america"
}

PUT /shipping_methods/{id}

Updates an existing shipping method. The full method is replaced with the supplied body, so send the complete representation (name, rates, conditions, etc.). Returns the updated method, or 404 Not Found if the id is not found.

Resource URL

PUT https://app.snipcart.com/api/shipping_methods/{id}

Headers

Name Value Required Description
Accept application/json Yes Response is JSON.
Content-Type application/json Yes Request body is JSON.

Path Parameters

Name Required Type Description
id Yes guid The unique identifier of the shipping method to update.

Body Parameters

Same body shape as POST /shipping_methods: name, localizationId, rates, onOrderTotalAbove, guaranteedEstimatedDelivery, postalCodeRegex, countryCondition, shippingZoneId. (The legacy location alias is also accepted here.)

Example request 

curl -X PUT https://app.snipcart.com/api/shipping_methods/5f1d3b2a-9c4e-4a1b-8d6f-2e7a1c0b9d34 \
  -u {API_KEY}: \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Standard (updated)",
    "rates": [
      { "cost": 12.00, "weight": { "from": 0, "to": 2000 } }
    ],
    "countryCondition": [
      { "countryCode": "CA", "provinceCode": "QC" }
    ]
  }'

Example response 

{
  "guaranteedEstimatedDelivery": {
    "minimumDaysForDelivery": null,
    "maximumDaysForDelivery": null
  },
  "rates": [
    {
      "cost": 12.00,
      "weight": {
        "from": 0,
        "to": 2000
      }
    }
  ],
  "countryCondition": [
    {
      "countryCode": "CA",
      "provinceCode": "QC"
    }
  ],
  "name": "Standard (updated)",
  "localizationId": null,
  "onOrderTotalAbove": null,
  "Id": "5f1d3b2a-9c4e-4a1b-8d6f-2e7a1c0b9d34"
}

DELETE /shipping_methods/{id}

Permanently deletes a shipping method by its GUID. Returns an empty 204 No Content response on success, or 404 Not Found if the id is not found.

Resource URL

DELETE https://app.snipcart.com/api/shipping_methods/{id}

Headers

Name Value Required Description
Accept application/json Yes Response is JSON.

Path Parameters

Name Required Type Description
id Yes guid The unique identifier of the shipping method to delete.

Example request 

curl -X DELETE https://app.snipcart.com/api/shipping_methods/5f1d3b2a-9c4e-4a1b-8d6f-2e7a1c0b9d34 \
  -u {API_KEY}: \
  -H "Accept: application/json"

Was this article helpful?