--- title: Add Items to Cart slug: api-documentation/U5Eg-add-items-to-cart docTags: createdAt: 2026-08-27T16:53:32.339Z --- { "id": "LU8RfTZxZDK62yh89Rgx4", "type": "api-oas-v2", "data": { "method": "POST", "url": "https://api.upstartcommerce.com/v1/cart/{customerId}/cart/items", "servers": [ { "url": "https://api.upstartcommerce.com/v1/cart/{customerId}/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": [ { "kind": "required", "name": "customerId", "type": "string", "description": "Unique identifier representing the \"owner\" of the cart." } ], "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": "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" } ], "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": "Ag66tJDbM-4Po1yBgXSWw", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url https://api.upstartcommerce.com/v1/cart/{customerId}/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": "F8djHgOV1F6-WEwtmk7bb", "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/{customerId}/cart/items\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "5JjNqIwUwr4hW07MZ8r02", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.upstartcommerce.com/v1/cart/{customerId}/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": "zzoiKqOFkAvFFz8NE9hJJ", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://api.upstartcommerce.com/v1/cart/{customerId}/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": "Ag66tJDbM-4Po1yBgXSWw" }, "results": { "languages": [ { "id": "17oC7vFJqYEZdDNFP6QIM", "language": "201", "code": "// Success-the items were added to the cart.\n{\n \"id\": \"\",\n \"itemIds\": [\n \"\"\n ]\n}" }, { "id": "EGB6vLHJ_VtpnatwiDTJq", "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": "iNu4YUN_fj2yiiy2Xs9B-", "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": "G9A3nL0Cp9uSX33mC_CFR", "language": "404", "code": "// The requested resource was not found in the NoChannel system.\n{\n \"name\": \"\",\n \"code\": \"\",\n \"detail\": \"\",\n \"reason\": \"\"\n}" } ], "selectedLanguageId": "17oC7vFJqYEZdDNFP6QIM" } }, "children": [ { "text": "" } ] }