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

{
  "id": "HUkh8LXxS1NgW95CrtIzh",
  "type": "api-oas-v2",
  "data": {
    "method": "GET",
    "url": "https://api.upstartcommerce.com/v1/shipping-carriers",
    "servers": [
      {
        "url": "https://api.upstartcommerce.com/v1/shipping-carriers"
      }
    ],
    "name": "List Shipping Carriers",
    "description": "<p>This endpoint returns one page of the tenant's shipping carriers, optionally narrowed by a text search.</p>\n<p>A caller sees the shipping carriers on the sites they are allowed to read, plus the shipping carriers 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 carrier matches when any one of the words matches. Every word but the last has to equal\na whole word of the id, name, tracking URL, description, account number or a site id, ignoring case and punctuation. The last word only has to start one.</p>\n<p>Results are ordered by name or by id, case-sensitively (upper case sorts before lower case). Equal names are ordered 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 description and the tracking URL. 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.carrier.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",
            "id",
            "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 carriers returned.</p>",
        "jsonExample": "",
        "isExpanded": true,
        "schema": [
          {
            "kind": "optional",
            "type": "object",
            "description": "<p>One page of shipping carriers, with the total number that matched.</p>",
            "customType": "ShippingCarrierPage",
            "schema": [
              {
                "name": "items",
                "kind": "required",
                "type": "array",
                "description": "<p>The shipping carriers on this page, in the requested order.</p>",
                "modelRef": "#/components/schemas/ShippingCarrier",
                "customType": "ShippingCarrier[]",
                "schema": [
                  {
                    "name": "id",
                    "kind": "required",
                    "type": "string",
                    "description": "Unique identifier for the shipping carrier. This will be assigned unless it is provided.",
                    "example": "usps"
                  },
                  {
                    "name": "name",
                    "kind": "required",
                    "type": "string",
                    "description": "Carrier name",
                    "example": "USPS"
                  },
                  {
                    "name": "siteIds",
                    "kind": "required",
                    "type": "array",
                    "description": "",
                    "example": "",
                    "itemType": "string",
                    "customType": "string[]",
                    "itemExample": "",
                    "itemDefault": ""
                  },
                  {
                    "name": "description",
                    "kind": "optional",
                    "type": "string",
                    "description": ""
                  },
                  {
                    "name": "trackingUrl",
                    "kind": "optional",
                    "type": "string",
                    "description": "<p>Tracking URL. If defined, tracking is supported for given carrier. Placeholder for trackingNumber {{trackingNumber}}</p>",
                    "example": "https://tools.usps.com/go/TrackConfirmAction?tRef=fullpage&tLc=2&text28777=&tLabels={{trackingNumber}}"
                  },
                  {
                    "name": "accountNumber",
                    "kind": "optional",
                    "type": "string",
                    "description": "Account number for carrier."
                  }
                ]
              },
              {
                "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 carriers that matched, across all pages.</p>",
                "format": "int32"
              }
            ],
            "modelRef": "#/components/schemas/ShippingCarrierPage",
            "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-carriers?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-carriers?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-carriers?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-carriers?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 carriers returned.\n{\n  \"items\": [\n    {\n      \"id\": \"usps\",\n      \"name\": \"USPS\",\n      \"siteIds\": [\n        \"\"\n      ],\n      \"description\": \"\",\n      \"trackingUrl\": \"https://tools.usps.com/go/TrackConfirmAction?tRef=fullpage&tLc=2&text28777=&tLabels={{trackingNumber}}\",\n      \"accountNumber\": \"\"\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": ""
    }
  ]
}