---
title: List Shipping Methods
slug: api-documentation/list-shipping-methods
createdAt: 2026-11-19T08:10:21.460Z
---

{
  "id": "iV7RbjCoLzRFJmzb5v6pM",
  "type": "api-oas-v2",
  "data": {
    "method": "GET",
    "url": "https://api.upstartcommerce.com/v1/shipping-methods",
    "servers": [
      {
        "url": "https://api.upstartcommerce.com/v1/shipping-methods"
      }
    ],
    "name": "List Shipping Methods",
    "description": "<p>This endpoint returns one page of the tenant's shipping methods, optionally narrowed by a text search.</p>\n<p>A caller sees the shipping methods on the sites they are allowed to read, plus the shipping methods assigned to no site.\nWhen <code>x-upstart-site</code> is sent, only that site is considered.</p>\n<p><code>q</code> is split on whitespace, and a shipping method matches when any one of the words matches. Every word but the last has to equal\na whole word of the id, name, tax code or a site id, ignoring case and punctuation. The last word only has to start one.</p>\n<p>Results are ordered by name, case-sensitively (upper case sorts before lower case), and then by id.</p>\n<p>With <code>sort=relevance</code> the best match comes first: a match on the id outranks a match on the name, which outranks the tax code. Equal matches are in name order,\nwhich is also the order when there is no <code>q</code>. <code>sortDir=asc</code> reverses the whole order.</p>\n<p>Authorized permissions:</p>\n<ul>\n<li><code>shipping.method.read</code></li>\n</ul>\n<p>Customer and anonymous tokens are not authorized.</p>",
    "contentType": "application/json",
    "request": {
      "pathParameters": [],
      "headerParameters": [
        {
          "name": "accept",
          "type": "string",
          "kind": "optional",
          "description": "Generated from available response content types",
          "enum": [
            "application/json"
          ],
          "default": "application/json"
        },
        {
          "kind": "required",
          "name": "x-upstart-tenant",
          "type": "string",
          "description": "Tenant identifier associated with the site this call is for."
        },
        {
          "kind": "optional",
          "name": "x-upstart-site",
          "type": "string",
          "description": "Unique identifier for the site."
        }
      ],
      "queryParameters": [
        {
          "kind": "optional",
          "name": "q",
          "type": "string",
          "description": "<p>Free text to search for. Leading and trailing whitespace is ignored, and a blank value means no search.</p>",
          "maxLength": 100
        },
        {
          "kind": "optional",
          "name": "sort",
          "type": "string",
          "description": "<p>The field to sort by, or <code>relevance</code> for the best match first. Defaults to <code>name</code>.</p>",
          "enum": [
            "name",
            "relevance"
          ]
        },
        {
          "kind": "optional",
          "name": "sortDir",
          "type": "string",
          "description": "<p>The direction to sort in. Defaults to <code>asc</code>, or to <code>desc</code> when sorting by relevance.</p>",
          "enum": [
            "asc",
            "desc"
          ]
        },
        {
          "kind": "optional",
          "name": "page",
          "type": "integer<int32>",
          "description": "<p>The zero-based page number.</p>",
          "default": 0,
          "format": "int32",
          "minimum": 0,
          "maximum": 1000
        },
        {
          "kind": "optional",
          "name": "pageSize",
          "type": "integer<int32>",
          "description": "The number of results per page.",
          "default": 25,
          "format": "int32",
          "minimum": 1,
          "maximum": 50
        }
      ],
      "bodyDataParameters": [],
      "formDataParameters": [],
      "oAuthParameters": [
        {
          "id": "NoChannelPortalAccess",
          "name": "NoChannelPortalAccess",
          "kind": "optional",
          "type": "http",
          "description": "<p>This authentication is required for clients to interact with any of the management APIs. Similar to 'LoggedIn', it indicates that the user has actually logged into the system, but in this case with a management role.</p>",
          "scheme": "bearer"
        }
      ],
      "cookieParameters": []
    },
    "responses": [
      {
        "statusCode": "200",
        "description": "<p>Success-one page of shipping methods returned.</p>",
        "jsonExample": "",
        "isExpanded": true,
        "schema": [
          {
            "kind": "optional",
            "type": "object",
            "description": "<p>One page of shipping methods, with the total number that matched.</p>",
            "customType": "ShippingMethodPage",
            "schema": [
              {
                "name": "items",
                "kind": "required",
                "type": "array",
                "description": "<p>The shipping methods on this page, in the requested order.</p>",
                "modelRef": "#/components/schemas/ShippingMethod",
                "customType": "ShippingMethod[]",
                "schema": [
                  {
                    "name": "calculator",
                    "kind": "required",
                    "type": "object",
                    "description": "",
                    "example": "",
                    "schema": []
                  },
                  {
                    "name": "dynamicProperties",
                    "kind": "optional",
                    "type": "object",
                    "description": "Dynamic properties on the shipping method.",
                    "example": "{\"propertyName\":\"This is a dynamic property\"}",
                    "schema": []
                  },
                  {
                    "name": "id",
                    "kind": "required",
                    "type": "string<uuid>",
                    "description": "Optional shipping method id.",
                    "example": "8A218593-40EB-4DD0-94BD-8ACA1D95BB14",
                    "format": "uuid"
                  },
                  {
                    "name": "limits",
                    "kind": "optional",
                    "type": "object",
                    "description": "Defines optional dimension and weight limits of the shipping method.",
                    "modelRef": "#/components/schemas/Limits",
                    "customType": "Limits",
                    "schema": [
                      {
                        "name": "dimensions",
                        "kind": "optional",
                        "type": "object",
                        "description": "Represents the dimensions of a shipping package.",
                        "modelRef": "#/components/schemas/Dimensions",
                        "customType": "Dimensions",
                        "schema": [
                          {
                            "name": "width",
                            "kind": "required",
                            "type": "number<double>",
                            "description": "The width of the package.",
                            "example": 10.5,
                            "format": "double"
                          },
                          {
                            "name": "length",
                            "kind": "required",
                            "type": "number<double>",
                            "description": "The length of the package.",
                            "example": 20,
                            "format": "double"
                          },
                          {
                            "name": "height",
                            "kind": "required",
                            "type": "number<double>",
                            "description": "The height of the package.",
                            "example": 15,
                            "format": "double"
                          },
                          {
                            "name": "unit",
                            "kind": "required",
                            "type": "string<cm | m | in | mm>",
                            "description": "The unit of measurement for dimensions.",
                            "example": "cm",
                            "enum": [
                              "cm",
                              "m",
                              "in",
                              "mm"
                            ]
                          }
                        ]
                      },
                      {
                        "name": "weight",
                        "kind": "optional",
                        "type": "object",
                        "description": "Represents the weight of a shipping package.",
                        "modelRef": "#/components/schemas/Weight",
                        "customType": "Weight",
                        "schema": [
                          {
                            "name": "value",
                            "kind": "required",
                            "type": "number<double>",
                            "description": "The weight value.",
                            "example": 2.5,
                            "format": "double"
                          },
                          {
                            "name": "unit",
                            "kind": "required",
                            "type": "string<g | kg | lb>",
                            "description": "The unit of measurement for the weight.",
                            "example": "kg",
                            "enum": [
                              "g",
                              "kg",
                              "lb"
                            ]
                          }
                        ]
                      }
                    ]
                  },
                  {
                    "name": "media",
                    "kind": "optional",
                    "type": "map",
                    "description": "",
                    "example": "",
                    "customType": "map<string, MediaValue>",
                    "schema": []
                  },
                  {
                    "name": "name",
                    "kind": "required",
                    "type": "string",
                    "description": "name of the shipping method",
                    "example": "Shipping Method One"
                  },
                  {
                    "name": "siteIds",
                    "kind": "required",
                    "type": "array",
                    "description": "This should be a list of ids indicating the allowed sites. The ids must reference a valid site.",
                    "example": "",
                    "itemType": "string",
                    "customType": "string[]",
                    "itemExample": "",
                    "itemDefault": ""
                  },
                  {
                    "name": "taxCode",
                    "kind": "optional",
                    "type": "string",
                    "description": "Optional tax code for a shipping method.",
                    "example": "12345"
                  }
                ]
              },
              {
                "name": "page",
                "kind": "required",
                "type": "integer<int32>",
                "description": "<p>The zero-based number of this page.</p>",
                "format": "int32"
              },
              {
                "name": "pageSize",
                "kind": "required",
                "type": "integer<int32>",
                "description": "The page size that was requested.",
                "format": "int32"
              },
              {
                "name": "total",
                "kind": "required",
                "type": "integer<int32>",
                "description": "<p>The number of shipping methods that matched, across all pages.</p>",
                "format": "int32"
              }
            ],
            "modelRef": "#/components/schemas/ShippingMethodPage",
            "isExpanded": true
          }
        ]
      },
      {
        "statusCode": "400",
        "description": "The request contained information that the server was unable to process. Appropriate errors are provided in the response body.",
        "jsonExample": "",
        "isExpanded": true,
        "schema": [
          {
            "kind": "optional",
            "type": "object",
            "description": "<p>Error payload returned when a request fails validation, identifying the offending input by name, code and detail.</p>",
            "customType": "ValidationErrorResponse",
            "schema": [
              {
                "name": "name",
                "kind": "required",
                "type": "string",
                "description": ""
              },
              {
                "name": "code",
                "kind": "required",
                "type": "string",
                "description": ""
              },
              {
                "name": "detail",
                "kind": "optional",
                "type": "string",
                "description": ""
              },
              {
                "name": "reason",
                "kind": "optional",
                "type": "string",
                "description": ""
              }
            ],
            "modelRef": "#/components/schemas/ValidationErrorResponse",
            "isExpanded": true
          }
        ]
      },
      {
        "statusCode": "401",
        "description": "The provided credentials were not valid for this endpoint. It may be that they are expired or that the user's roles are insufficient.",
        "jsonExample": "",
        "isExpanded": true,
        "schema": [
          {
            "kind": "optional",
            "type": "object",
            "description": "<p>Standard error payload identifying a failure by name, code and detail, with an optional machine-readable reason.</p>",
            "customType": "ErrorResponse",
            "schema": [
              {
                "name": "name",
                "kind": "required",
                "type": "string",
                "description": ""
              },
              {
                "name": "code",
                "kind": "required",
                "type": "string",
                "description": ""
              },
              {
                "name": "detail",
                "kind": "required",
                "type": "string",
                "description": ""
              },
              {
                "name": "reason",
                "kind": "optional",
                "type": "string",
                "description": ""
              }
            ],
            "modelRef": "#/components/schemas/ErrorResponse",
            "isExpanded": true
          }
        ]
      }
    ],
    "hasXCodeSamples": false,
    "examples": {
      "languages": [
        {
          "id": "example-0-curl",
          "language": "curl",
          "label": "cURL",
          "code": "curl --request GET \\\n     --url 'https://api.upstartcommerce.com/v1/shipping-methods?page=integer%3Cint32%3E&pageSize=25' \\\n     --header 'accept: application/json' \\\n     --header 'x-upstart-tenant: string'"
        },
        {
          "id": "example-1-javascript",
          "language": "javascript",
          "label": "javascript",
          "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\nmyHeaders.append(\"x-upstart-tenant\", \"string\");\n\nvar requestOptions = {\n   method: 'GET',\n   headers: myHeaders,\n   redirect: 'follow'\n};\n\nfetch(\"https://api.upstartcommerce.com/v1/shipping-methods?page=integer<int32>&pageSize=25\", requestOptions)\n   .then(response => response.text())\n   .then(result => console.log(result))\n   .catch(error => console.log('error', error));"
        },
        {
          "id": "example-2-ruby",
          "language": "ruby",
          "label": "Ruby",
          "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.upstartcommerce.com/v1/shipping-methods?page=integer<int32>&pageSize=25\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Get.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\nrequest[\"x-upstart-tenant\"] = \"string\"\n\nresponse = https.request(request)\nputs response.read_body\n"
        },
        {
          "id": "example-3-python",
          "language": "python",
          "label": "Python",
          "code": "import requests\nimport json\n\nurl = \"https://api.upstartcommerce.com/v1/shipping-methods?page=integer<int32>&pageSize=25\"\n\npayload = {}\nheaders = {\n   'accept': 'application/json',\n   'content-type': 'application/json',\n   'x-upstart-tenant': 'string'\n}\n\nresponse = requests.request(\"GET\", url, headers=headers, data=payload)\n\nprint(response.text)\n"
        }
      ],
      "selectedLanguageId": "example-0-curl"
    },
    "results": {
      "languages": [
        {
          "id": "response-0-200",
          "language": "200",
          "code": "// Success-one page of shipping methods returned.\n{\n  \"items\": [\n    {\n      \"calculator\": {},\n      \"dynamicProperties\": {},\n      \"id\": \"8A218593-40EB-4DD0-94BD-8ACA1D95BB14\",\n      \"limits\": {\n        \"dimensions\": {\n          \"width\": 10.5,\n          \"length\": 20,\n          \"height\": 15,\n          \"unit\": \"cm\"\n        },\n        \"weight\": {\n          \"value\": 2.5,\n          \"unit\": \"kg\"\n        }\n      },\n      \"media\": \"\",\n      \"name\": \"Shipping Method One\",\n      \"siteIds\": [\n        \"\"\n      ],\n      \"taxCode\": \"12345\"\n    }\n  ],\n  \"page\": \"\",\n  \"pageSize\": \"\",\n  \"total\": \"\"\n}"
        },
        {
          "id": "response-1-400",
          "language": "400",
          "code": "// The request contained information that the server was unable to process. Appropriate errors are provided in the response body.\n{\n  \"name\": \"\",\n  \"code\": \"\",\n  \"detail\": \"\",\n  \"reason\": \"\"\n}"
        },
        {
          "id": "response-2-401",
          "language": "401",
          "code": "// The provided credentials were not valid for this endpoint. It may be that they are expired or that the user's roles are insufficient.\n{\n  \"name\": \"\",\n  \"code\": \"\",\n  \"detail\": \"\",\n  \"reason\": \"\"\n}"
        }
      ],
      "selectedLanguageId": "response-0-200"
    }
  },
  "children": [
    {
      "text": ""
    }
  ]
}