Add cart items

The shopping cart is where the information on the products chosen by the customer while browsing a store is gathered. This data may include item prices, shipping value, payment, and delivery methods, among others.

This guide will describe how to add new items to a shopping cart by the API.

Getting shopping cart information

The first step is to get the orderFormId of the shopping cart to which you want to add items. For more information, access the Get cart information by ID guide.

Adding items to the shopping cart

To add items to the shopping cart, you need to use the Add cart items endpoint. In this request, you must send the following information through the URL:

Path param: orderFormId value.
Query param: allowedOutdatedData. You can set up this query as false or true to define whether some cart information can be updated through the minicart.

See a URL example below:

https://accountname.environment.com.br/api/checkout/pub/orderForm/ede846222cd44046ba6c638442c3505a/items?allowedOutdatedData=paymentData

Additionally, you must send the request body containing the following information about the new item to be added to the cart:

quantity
seller
id
index
price

️ price should be sent only in case you want to make a bulk price change.

See a request body example below:


_10{
_10     "orderItems": [
_10          {
_10               "quantity": 3,
_10               "seller": "cosmetics1",
_10               "id": "2005",
_10               "index": 0
_10          }
_10     ]
_10}

After sending the request, the endpoint will return the response body containing the shopping cart information including the new item added, as shown in the example below:


_80...
_80"items": [
_80        {
_80            "uniqueId": "D1E0949706A3441DA0386929FAB6E7E8",
_80            "id": "2005",
_80            "productId": "3",
_80            "productRefId": "",
_80            "refId": null,
_80            "ean": "978020137962",
_80            "name": "Weightless Waves Mild Lather Cleanser 50 ml",
_80            "skuName": "50 ml",
_80            "modalType": null,
_80            "parentItemIndex": null,
_80            "parentAssemblyBinding": null,
_80            "assemblies": [],
_80            "priceValidUntil": "2023-11-07T22:14:44Z",
_80            "tax": 0,
_80            "taxCode": "54WC8ZN6K8",
_80            "price": 3190,
_80            "listPrice": 3190,
_80            "manualPrice": null,
_80            "manualPriceAppliedBy": null,
_80            "sellingPrice": 3107,
_80            "rewardValue": 0,
_80            "isGift": false,
_80            "additionalInfo": {
_80                "dimension": null,
_80                "brandName": "VALDIE&CO",
_80                "brandId": "2000000",
_80                "offeringInfo": null,
_80                "offeringType": null,
_80                "offeringTypeId": null
_80            },
_80            "preSaleDate": null,
_80            "productCategoryIds": "/2/",
_80            "productCategories": {
_80                "2": "Computers"
_80            },
_80            "quantity": 3,
_80            "seller": "cosmetics1",
_80            "sellerChain": [
_80                "cosmetics1"
_80            ],
_80            "imageUrl": "http://cosmetics2.vteximg.com.br/arquivos/ids/155401-55-55/ID-001-MAIN.jpg?v=637109313796670000",
_80            "detailUrl": "/weightless-waves-mild-lather-cleanser/p",
_80            "components": [],
_80            "bundleItems": [],
_80            "attachments": [],
_80            "attachmentOfferings": [],
_80            "offerings": [],
_80            "priceTags": [
_80                {
_80                    "name": "discount@price-0e45a4e3-6084-4bf9-bff7-0fe8403699fc#ac2d3d37-5845-45a6-9254-191449d6f100",
_80                    "value": -416,
_80                    "rawValue": -4.160,
_80                    "isPercentual": false,
_80                    "identifier": "0e45a4e3-6084-4bf9-bff7-0fe8403699fc",
_80                    "owner": "cosmetics2"
_80                }
_80            ],
_80            "availability": "available",
_80            "measurementUnit": "un",
_80            "unitMultiplier": 1.0000,
_80            "manufacturerCode": null,
_80            "priceDefinition": {
_80                "calculatedSellingPrice": 3107,
_80                "total": 15534,
_80                "sellingPrices": [
_80                    {
_80                        "value": 3107,
_80                        "quantity": 4
_80                    },
_80                    {
_80                        "value": 3106,
_80                        "quantity": 1
_80                    }
_80                ]
_80            }
_80        },
_80...

️ For more information about the meaning of each of the fields available in the shopping cart, access the orderForm overview.

Error codes

The following errors may appear as a message in the response body.

400 - Bad Request

Message error example (code ORD002): "Invalid order form". The orderFormId information is not valid.


_10{
_10    "fields": {},
_10    "error": {
_10        "code": "ORD002",
_10        "message": "Invalid order form",
_10        "exception": null
_10    },
_10    "operationId": "5d9f54e6-7db4-46d6-bca9-deeb278b8b98"
_10}

Message error example (code CHK0024): "Invalid seller for item". This message indicates that the seller used in the request does not exist, is incorrect or has not been informed.


_10{
_10    "fields": {},
_10    "error": {
_10        "code": "CHK0024",
_10        "message": "Invalid seller for item",
_10        "exception": null
_10    },
_10    "operationId": "abe5d1b9-a85f-4f10-a3e8-f783082c5c3d"
_10}

403 - Forbidden

Message error example (code CHK003): "Access denied". This message indicates that it is not possible to make a bulk price change on this item.


_10{
_10    "fields": {},
_10    "error": {
_10        "code": "CHK003",
_10        "message": "Access denied",
_10        "exception": null
_10    },
_10    "operationId": "a6ea8b84-68d9-43a7-902e-846e8c5c05b6"
_10}

404 - Not Found

Message error example: "The requested URL was not found on the server". Check that the URL data is correct.


_10<body>
_10	<h1>404 Not Found</h1>
_10	<p>The requested URL was not found on this server.</p>
_10</body>