--- title: Add Items to Cart slug: api-documentation/add-items-to-cart docTags: createdAt: 2026-08-27T16:53:32.339Z --- { "id": "1uyrJfUBT8DfgnU5BB06s", "type": "api-oas-v2", "data": { "method": "POST", "url": "https://api.upstartcommerce.com/v1/cart/profile/cart/items", "servers": [ { "url": "https://api.upstartcommerce.com/v1/cart/profile/cart/items" } ], "name": "Add Items to Cart", "description": "This endpoint appends the indicated items to the consumer's active cart.", "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": "required", "name": "x-upstart-site", "type": "string", "description": "The site identifier." } ], "queryParameters": [], "bodyDataParameters": [ { "kind": "required", "name": "body", "type": "object", "description": "Object providing purchase data.", "customType": "AddCartItems", "schema": [ { "name": "items", "kind": "required", "type": "array", "description": "Object data describing an active cart.", "modelRef": "#/components/schemas/AddCartItem", "customType": "AddCartItem[]", "schema": [ { "name": "id", "kind": "optional", "type": "string", "description": "This is typically not set. This is the id that will uniquely identify the cart item.", "format": "uuid" }, { "name": "catalogItemId", "kind": "required", "type": "string", "description": "Unique identifier for a catalog item." }, { "name": "productItemSkuId", "kind": "optional", "type": "string", "description": "

Unique identifier for the concrete SKU (stock keeping unit) being added.

", "default": "N/A" }, { "name": "targetItemIds", "kind": "optional", "type": "array", "description": "

Target items are cart item ids / references to products from protection plans, product-associated services, and warranties. Products and other types of services are not allowed to have targetItems, warranty must reference only one product and protection plan and product-associated services must reference one or more products.

", "example": "", "default": [], "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" }, { "name": "targetShipmentIds", "kind": "optional", "type": "array", "description": "

Target shipments are references from shipping-only-associated services. It can refer to one or more shipments. Other types of services, products, protection plans, nor warranties are not allowed to have targetShipmentIds.

", "example": "", "default": [], "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" }, { "name": "quantity", "kind": "optional", "type": "integer", "description": "

This represents quantity of this item to add to the cart. It's not allowed to be specified for warranties and protection plans (cart handles quantities itself for these). If not specified for product, it defaults to 1.

", "format": "int32" }, { "name": "shippingMethodId", "kind": "optional", "type": "string", "description": "Unique identifier for the shipping method being used for this item.", "format": "uuid" } ] }, { "name": "locationId", "kind": "optional", "type": "string", "description": "Unique identifier of the location this item is associated with.", "example": "MSP-123" }, { "name": "postalCode", "kind": "optional", "type": "string", "description": "Standard postal code", "example": "03101" }, { "name": "country", "kind": "optional", "type": "string", "description": "

A 2-character country code.

", "example": "US" }, { "name": "currency", "kind": "optional", "type": "string", "description": "

Currency used for this cart (applying the 3-character ISO code).

", "example": "USD" }, { "name": "timezoneId", "kind": "optional", "type": "string", "description": "

Timezone id (tz database). If not specified - tenant's default timezone is used.

", "example": "America/Denver" } ], "modelRef": "#/components/schemas/AddCartItems", "isExpanded": true } ], "formDataParameters": [], "oAuthParameters": [ { "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" }, { "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" } ], "cookieParameters": [] }, "responses": [ { "statusCode": "201", "description": "

Success-the items were added to the cart.

", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "This holds the id of the cart and the items that were updated.", "customType": "CartItemsUpdated", "schema": [ { "name": "id", "kind": "required", "type": "string", "description": "Unique identifier of the updated cart.", "format": "uuid" }, { "name": "itemIds", "kind": "required", "type": "array", "description": "", "example": "", "itemType": "string", "customType": "string[]", "itemExample": "", "itemDefault": "" } ], "modelRef": "#/components/schemas/CartItemsUpdated", "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": "" } ], "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 } ] }, { "statusCode": "404", "description": "The requested resource was not found in the NoChannel system.", "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": "1ESRPCPpN6wWcurI7WeEU", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url https://api.upstartcommerce.com/v1/cart/profile/cart/items \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --header 'x-upstart-tenant: string' \\\n --header 'x-upstart-site: string' \\\n --data '{\n \"items\": [\n {\n \"catalogItemId\": \"\",\n \"productItemSkuId\": \"N/A\",\n \"targetItemIds\": [],\n \"targetShipmentIds\": []\n }\n ]\n }'" }, { "id": "MsDgeMOFli4y5y8k2i7TE", "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\");\nmyHeaders.append(\"x-upstart-site\", \"string\");\n\nvar raw = JSON.stringify({\n \"items\": [\n {\n \"catalogItemId\": \"\",\n \"productItemSkuId\": \"N/A\",\n \"targetItemIds\": [],\n \"targetShipmentIds\": []\n }\n ]\n});\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://api.upstartcommerce.com/v1/cart/profile/cart/items\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "5H5IRoLaD27q-Kix4fBqv", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.upstartcommerce.com/v1/cart/profile/cart/items\")\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[\"x-upstart-site\"] = \"string\"\nrequest.body = JSON.dump({\n \"items\": [\n {\n \"catalogItemId\": \"\",\n \"productItemSkuId\": \"N/A\",\n \"targetItemIds\": [],\n \"targetShipmentIds\": []\n }\n ]\n})\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "sC38QfLjuAiSPAFXqVvAg", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://api.upstartcommerce.com/v1/cart/profile/cart/items\"\n\npayload = json.dumps({\n \"items\": [\n {\n \"catalogItemId\": \"\",\n \"productItemSkuId\": \"N/A\",\n \"targetItemIds\": [],\n \"targetShipmentIds\": []\n }\n ]\n})\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json',\n 'x-upstart-tenant': 'string',\n 'x-upstart-site': 'string'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "1ESRPCPpN6wWcurI7WeEU" }, "results": { "languages": [ { "id": "AtUO5BIaWawT64Oq6d4q1", "language": "201", "code": "// Success-the items were added to the cart.\n{\n \"id\": \"\",\n \"itemIds\": [\n \"\"\n ]\n}" }, { "id": "xH_IMPPk6-9Q09uSwzIDZ", "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}" }, { "id": "yyWSJ-lwNDiSLc701hOb2", "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}" }, { "id": "GZLy2E6oToIFp69f8KSlI", "language": "404", "code": "// The requested resource was not found in the NoChannel system.\n{\n \"name\": \"\",\n \"code\": \"\",\n \"detail\": \"\",\n \"reason\": \"\"\n}" } ], "selectedLanguageId": "AtUO5BIaWawT64Oq6d4q1" } }, "children": [ { "text": "" } ] }