--- title: Get Rate for Item slug: api-documentation/get-rate-for-item docTags: createdAt: 2026-08-27T17:08:07.245Z --- { "id": "LNhCnfh27AebXMEqI4_ad", "type": "api-oas-v2", "data": { "method": "POST", "url": "https://api.upstartcommerce.com/v1/shipping-method/rate/catalog-item", "servers": [ { "url": "https://api.upstartcommerce.com/v1/shipping-method/rate/catalog-item" } ], "name": "Get Rate for Item", "description": "

This endpoint returns the shipping rate for a catalog item.

\n

Authorized permissions:

\n\n

Authorized roles:

\n", "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": [], "bodyDataParameters": [ { "kind": "required", "name": "body", "type": "object", "description": "The request must provide details of the catalog item for which shipping rate should be calculated.", "customType": "CatalogItemShippingRatesRequest", "schema": [ { "name": "catalogItemId", "kind": "required", "type": "string", "description": "Unique identifier for a catalog item.", "example": "item1" }, { "name": "country", "kind": "required", "type": "string", "description": "The target country.", "example": "USA" }, { "name": "currency", "kind": "required", "type": "string", "description": "

The 3-character ISO code.

", "example": "USD" }, { "name": "locationToId", "kind": "optional", "type": "string", "description": "Unique identifier for the location to which a shipment should be sent.", "example": "1562368" }, { "name": "postalCode", "kind": "required", "type": "string", "description": "The target ZIP code.", "example": "43234" }, { "name": "productItemSkuId", "kind": "required", "type": "string", "description": "

Unique identifier of the stock keeping unit (SKU) of an item.

", "example": "SKU_item1" }, { "name": "quantity", "kind": "required", "type": "integer", "description": "The count of items in the shipment.", "example": 1, "minimum": 1 }, { "name": "shippingMethodIds", "kind": "required", "type": "array", "description": "An array of shipping method ids.", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "8A218593-40EB-4DD0-94BD-8ACA1D95BB14", "itemDefault": "" }, { "name": "stateOrRegion", "kind": "optional", "type": "string", "description": "The target state or region.", "example": "California" } ], "modelRef": "#/components/schemas/CatalogItemShippingRatesRequest", "isExpanded": true } ], "formDataParameters": [], "oAuthParameters": [ { "id": "LoggedIn", "name": "LoggedIn", "kind": "optional", "type": "http", "description": "The presence of this token indicates that the user is a known consumer that has previously logged into the platform.", "scheme": "bearer" }, { "id": "NoChannelPortalAccess", "name": "NoChannelPortalAccess", "kind": "optional", "type": "http", "description": "

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.

", "scheme": "bearer" }, { "id": "AnonymousAuth", "name": "AnonymousAuth", "kind": "optional", "type": "http", "description": "This is the most basic authentication. The minimum requirement for access is a token representing the user as an anonymous client.", "scheme": "bearer" } ], "cookieParameters": [] }, "responses": [ { "statusCode": "200", "description": "

Success-resulting shipping rate returned.

", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "This represents a successful response for shipping rates request.", "customType": "CatalogItemShippingRatesResponse", "schema": [ { "name": "catalogItemId", "kind": "required", "type": "string", "description": "Unique identifier for a catalog item.", "example": "item1" }, { "name": "currency", "kind": "required", "type": "string", "description": "

The 3-character ISO code.

", "example": "USD", "pattern": "^[A-Z]{3}$" }, { "name": "errors", "kind": "required", "type": "array", "description": "

This represents an array of errors, if applicable.

", "modelRef": "#/components/schemas/ErrorMessage", "customType": "ErrorMessage[]", "schema": [ { "name": "level", "kind": "required", "type": "string", "description": "Level of an error message.", "example": "INFO", "enum": [ "INFO", "WARN", "ERROR" ] }, { "name": "code", "kind": "required", "type": "string", "description": "Code of an error message.", "example": "ERR-123" }, { "name": "message", "kind": "optional", "type": "string", "description": "Message of an error message.", "example": "Something unexpected happened" }, { "name": "detail", "kind": "optional", "type": "string", "description": "Details of an error message.", "example": "Could not contact other service" } ] }, { "name": "items", "kind": "required", "type": "array", "description": "An array of the items in the current cart.", "modelRef": "#/components/schemas/CatalogItemShippingItem", "customType": "CatalogItemShippingItem[]", "schema": [ { "name": "country", "kind": "required", "type": "string", "description": "This represents the country.", "example": "USA" }, { "name": "errors", "kind": "required", "type": "array", "description": "

This represents an array of errors, if applicable.

", "modelRef": "#/components/schemas/ErrorMessage", "customType": "ErrorMessage[]", "schema": [ { "name": "level", "kind": "required", "type": "string", "description": "Level of an error message.", "example": "INFO", "enum": [ "INFO", "WARN", "ERROR" ] }, { "name": "code", "kind": "required", "type": "string", "description": "Code of an error message.", "example": "ERR-123" }, { "name": "message", "kind": "optional", "type": "string", "description": "Message of an error message.", "example": "Something unexpected happened" }, { "name": "detail", "kind": "optional", "type": "string", "description": "Details of an error message.", "example": "Could not contact other service" } ] }, { "name": "locationFromId", "kind": "optional", "type": "string", "description": "This represents an id of the location from which a shipment is sent.", "example": "locationFromId", "default": "" }, { "name": "locationToId", "kind": "optional", "type": "string", "description": "Unique identifier for the location to which a shipment should be sent.", "example": "locationToId", "default": "" }, { "name": "packages", "kind": "required", "type": "array", "description": "This represents shipping packages.", "modelRef": "#/components/schemas/ShippingPackage", "customType": "ShippingPackage[]", "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", "description": "The width of the package.", "example": 10.5, "format": "double" }, { "name": "length", "kind": "required", "type": "number", "description": "The length of the package.", "example": 20, "format": "double" }, { "name": "height", "kind": "required", "type": "number", "description": "The height of the package.", "example": 15, "format": "double" }, { "name": "unit", "kind": "required", "type": "string", "description": "The unit of measurement for dimensions.", "example": "cm", "enum": [ "cm", "m", "in", "mm" ] } ] }, { "name": "insuredValue", "kind": "optional", "type": "number", "description": "This represents the value of an insurance.", "example": 100, "default": 0 }, { "name": "packageCode", "kind": "optional", "type": "string", "description": "This represents a package code.", "example": "PackageCode", "default": "" }, { "name": "weight", "kind": "required", "type": "object", "description": "Represents the weight of a shipping package.", "modelRef": "#/components/schemas/Weight", "customType": "Weight", "schema": [ { "name": "value", "kind": "required", "type": "number", "description": "The weight value.", "example": 2.5, "format": "double" }, { "name": "unit", "kind": "required", "type": "string", "description": "The unit of measurement for the weight.", "example": "kg", "enum": [ "g", "kg", "lb" ] } ] } ] }, { "name": "postalCode", "kind": "required", "type": "string", "description": "This represents the ZIP code.", "example": "43234" }, { "name": "rateServiceCode", "kind": "optional", "type": "string", "description": "This represents a rate service code.", "example": "rateServiceCode", "default": "" }, { "name": "rateVariants", "kind": "required", "type": "array", "description": "This represents rate variants.", "modelRef": "#/components/schemas/ShippingRate", "customType": "ShippingRate[]", "schema": [ { "name": "carrierCode", "kind": "required", "type": "string", "description": "Unique identifier for the carrier.", "example": "carrierCode" }, { "name": "carrierDeliveryDates", "kind": "required", "type": "string", "description": "This represents carrier delivery dates or delivery estimation." }, { "name": "carrierId", "kind": "required", "type": "string", "description": "Unique identifier for the carrier.", "example": "DHL" }, { "name": "deliveryDays", "kind": "optional", "type": "integer", "description": "This represents a number of days to deliver a shipping.", "example": 5, "format": "int32" }, { "name": "estimatedDeliveryDate", "kind": "optional", "type": "string", "description": "This represents an estimated date of delivery.", "example": "2017-07-21T17:32:28Z", "format": "date-time" }, { "name": "packageType", "kind": "optional", "type": "string", "description": "This represents a package type.", "example": "packageType" }, { "name": "pricing", "kind": "required", "type": "object", "description": "This represents a pricing of a shipping rate.", "modelRef": "#/components/schemas/ShippingRatePricing", "customType": "ShippingRatePricing", "schema": [ { "name": "confirmation", "kind": "optional", "type": "number", "description": "This represents the confirmation.", "example": 200 }, { "name": "insurance", "kind": "optional", "type": "number", "description": "This represents the value of an insurance.", "example": 100 }, { "name": "other", "kind": "optional", "type": "number", "description": "This represents other pricing.", "example": 10 }, { "name": "shipping", "kind": "required", "type": "number", "description": "This represents the value of a shipping.", "example": 100 }, { "name": "fee", "kind": "optional", "type": "number", "description": "This represents the sum of all the additional shipping fees.", "example": 20 } ] }, { "name": "rateId", "kind": "required", "type": "string", "description": "Unique identifier for a shipping rate.", "example": "rate1" }, { "name": "serviceCode", "kind": "required", "type": "string", "description": "This represents a service code.", "example": "serviceCode" }, { "name": "serviceType", "kind": "required", "type": "string", "description": "This represents a service type.", "example": "serviceType" }, { "name": "shipDate", "kind": "optional", "type": "string", "description": "This represents an actual date of shipping.", "example": "2017-07-21T17:32:28Z", "format": "date-time" } ] }, { "name": "shippingMethodId", "kind": "required", "type": "string", "description": "Unique identifier for a shipping method.", "format": "uuid" }, { "name": "shippingMethodName", "kind": "required", "type": "string", "description": "This represents a shipping method name.", "example": "Standard shipping", "default": "" } ] }, { "name": "productItemSkuId", "kind": "required", "type": "string", "description": "

Unique identifier of the stock keeping unit (SKU) of an item.

", "example": "SKU_item1", "default": "" } ], "modelRef": "#/components/schemas/CatalogItemShippingRatesResponse", "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": "", "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": "", "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": "I1omraLXg12k-Eqq-DU1n", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url https://api.upstartcommerce.com/v1/shipping-method/rate/catalog-item \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --header 'x-upstart-tenant: string' \\\n --data '{\n \"catalogItemId\": \"item1\",\n \"country\": \"USA\",\n \"currency\": \"USD\",\n \"postalCode\": \"43234\",\n \"productItemSkuId\": \"SKU_item1\",\n \"quantity\": 1,\n \"shippingMethodIds\": []\n }'" }, { "id": "-6pcIcMc7yeCYYnqSwVWt", "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 raw = JSON.stringify({\n \"catalogItemId\": \"item1\",\n \"country\": \"USA\",\n \"currency\": \"USD\",\n \"postalCode\": \"43234\",\n \"productItemSkuId\": \"SKU_item1\",\n \"quantity\": 1,\n \"shippingMethodIds\": []\n});\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://api.upstartcommerce.com/v1/shipping-method/rate/catalog-item\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "ocRiXA4tyeM8xgD8oZ169", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.upstartcommerce.com/v1/shipping-method/rate/catalog-item\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\nrequest[\"x-upstart-tenant\"] = \"string\"\nrequest.body = JSON.dump({\n \"catalogItemId\": \"item1\",\n \"country\": \"USA\",\n \"currency\": \"USD\",\n \"postalCode\": \"43234\",\n \"productItemSkuId\": \"SKU_item1\",\n \"quantity\": 1,\n \"shippingMethodIds\": []\n})\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "OfHOy5vjpJ7-9skY4PG64", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://api.upstartcommerce.com/v1/shipping-method/rate/catalog-item\"\n\npayload = json.dumps({\n \"catalogItemId\": \"item1\",\n \"country\": \"USA\",\n \"currency\": \"USD\",\n \"postalCode\": \"43234\",\n \"productItemSkuId\": \"SKU_item1\",\n \"quantity\": 1,\n \"shippingMethodIds\": []\n})\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json',\n 'x-upstart-tenant': 'string'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "I1omraLXg12k-Eqq-DU1n" }, "results": { "languages": [ { "id": "33IKcdDmoe8p3rpItmpIV", "language": "200", "code": "// Success-resulting shipping rate returned.\n{\n \"catalogItemId\": \"item1\",\n \"currency\": \"USD\",\n \"errors\": [\n {\n \"level\": \"INFO\",\n \"code\": \"ERR-123\",\n \"message\": \"Something unexpected happened\",\n \"detail\": \"Could not contact other service\"\n }\n ],\n \"items\": [\n {\n \"country\": \"USA\",\n \"errors\": [\n {\n \"level\": \"INFO\",\n \"code\": \"ERR-123\",\n \"message\": \"Something unexpected happened\",\n \"detail\": \"Could not contact other service\"\n }\n ],\n \"locationFromId\": \"locationFromId\",\n \"locationToId\": \"locationToId\",\n \"packages\": [\n {\n \"dimensions\": {\n \"width\": 10.5,\n \"length\": 20,\n \"height\": 15,\n \"unit\": \"cm\"\n },\n \"insuredValue\": 100,\n \"packageCode\": \"PackageCode\",\n \"weight\": {\n \"value\": 2.5,\n \"unit\": \"kg\"\n }\n }\n ],\n \"postalCode\": \"43234\",\n \"rateServiceCode\": \"rateServiceCode\",\n \"rateVariants\": [\n {\n \"carrierCode\": \"carrierCode\",\n \"carrierDeliveryDates\": \"\",\n \"carrierId\": \"DHL\",\n \"deliveryDays\": 5,\n \"estimatedDeliveryDate\": \"2017-07-21T17:32:28Z\",\n \"packageType\": \"packageType\",\n \"pricing\": {\n \"confirmation\": 200,\n \"insurance\": 100,\n \"other\": 10,\n \"shipping\": 100,\n \"fee\": 20\n },\n \"rateId\": \"rate1\",\n \"serviceCode\": \"serviceCode\",\n \"serviceType\": \"serviceType\",\n \"shipDate\": \"2017-07-21T17:32:28Z\"\n }\n ],\n \"shippingMethodId\": \"\",\n \"shippingMethodName\": \"Standard shipping\"\n }\n ],\n \"productItemSkuId\": \"SKU_item1\"\n}" }, { "id": "Ev3VuTstGsEWLrt7F9kHu", "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": "lBMZmFIfZn77tgDbkSXlL", "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": "33IKcdDmoe8p3rpItmpIV" } }, "children": [ { "text": "" } ] }