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

{
  "id": "VE-S68gs2nHopDt-XH7l2",
  "type": "api-oas-v2",
  "data": {
    "method": "GET",
    "url": "https://api.upstartcommerce.com/v1/shipping-fees",
    "servers": [
      {
        "url": "https://api.upstartcommerce.com/v1/shipping-fees"
      }
    ],
    "name": "List Shipping Fees",
    "description": "<p>This endpoint returns one page of the tenant's shipping fees, optionally narrowed by a text search.</p>\n<p>A caller sees the shipping fees on the sites they are allowed to read, plus the shipping fees 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 fee matches when any one of the words matches. Every word but the last has to equal\na whole word of the id, name, description, a site id, a catalog item id, a SKU id, a price or a currency, 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 a catalog item id, a SKU id, the name and the description, in that order. 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.fee.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 fees returned.</p>",
        "jsonExample": "",
        "isExpanded": true,
        "schema": [
          {
            "kind": "optional",
            "type": "object",
            "description": "<p>One page of shipping fees, with the total number that matched.</p>",
            "customType": "ShippingFeePage",
            "schema": [
              {
                "name": "items",
                "kind": "required",
                "type": "array",
                "description": "<p>The shipping fees on this page, in the requested order.</p>",
                "modelRef": "#/components/schemas/ShippingFee",
                "customType": "ShippingFee[]",
                "schema": [
                  {
                    "name": "id",
                    "kind": "required",
                    "type": "string",
                    "description": "Unique shipping fee identifier.",
                    "example": "fee1"
                  },
                  {
                    "name": "name",
                    "kind": "required",
                    "type": "string",
                    "description": "Fee name",
                    "example": "Shipping And Handling fee"
                  },
                  {
                    "name": "description",
                    "kind": "optional",
                    "type": "string",
                    "description": ""
                  },
                  {
                    "name": "siteIds",
                    "kind": "required",
                    "type": "array",
                    "description": "",
                    "example": "",
                    "itemType": "string",
                    "customType": "string[]",
                    "itemExample": "",
                    "itemDefault": ""
                  },
                  {
                    "name": "catalogSkuItems",
                    "kind": "required",
                    "type": "array",
                    "description": "A reference to a specific SKU of a catalog item.",
                    "modelRef": "#/components/schemas/CatalogSkuItem",
                    "customType": "CatalogSkuItem[]",
                    "schema": [
                      {
                        "name": "catalogItemId",
                        "kind": "required",
                        "type": "string",
                        "description": "Catalog item ID"
                      },
                      {
                        "name": "skuItemId",
                        "kind": "optional",
                        "type": "array",
                        "description": "",
                        "example": "",
                        "itemType": "string",
                        "customType": "string[]",
                        "itemExample": "",
                        "itemDefault": ""
                      }
                    ]
                  },
                  {
                    "name": "prices",
                    "kind": "required",
                    "type": "array",
                    "description": "A shipping fee amount and the currency it is expressed in.",
                    "modelRef": "#/components/schemas/ShippingFeePricing",
                    "customType": "ShippingFeePricing[]",
                    "schema": [
                      {
                        "name": "price",
                        "kind": "required",
                        "type": "number",
                        "description": ""
                      },
                      {
                        "name": "currency",
                        "kind": "required",
                        "type": "string",
                        "description": ""
                      }
                    ]
                  }
                ]
              },
              {
                "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 fees that matched, across all pages.</p>",
                "format": "int32"
              }
            ],
            "modelRef": "#/components/schemas/ShippingFeePage",
            "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-fees?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-fees?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-fees?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-fees?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 fees returned.\n{\n  \"items\": [\n    {\n      \"id\": \"fee1\",\n      \"name\": \"Shipping And Handling fee\",\n      \"description\": \"\",\n      \"siteIds\": [\n        \"\"\n      ],\n      \"catalogSkuItems\": [\n        {\n          \"catalogItemId\": \"\",\n          \"skuItemId\": [\n            \"\"\n          ]\n        }\n      ],\n      \"prices\": [\n        {\n          \"price\": 0,\n          \"currency\": \"\"\n        }\n      ]\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": ""
    }
  ]
}