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 shipping address and delivery options information in the shopping cart by the API.

The first step is to get the orderFormId of the shopping cart that you want to add the shipping address and delivery option information to. For more information, access the Get cart information by ID guide.

To add a shipping address to the shopping cart, you need to use the Add shipping address and select delivery option endpoint. In this request, you must send the orderFormId through the URL address, as shown in the example below:

https://{accountName}.{environment.com.br}/api/checkout/pub/orderForm/ede846222cd44046ba6c638442c3505a/attachments/shippingData

Additionally, you need to send the request body with the selectedAddresses array containing the following information:

• addressType: type of address (e.g. "residential", "pickup").
• receiverName: name of the person responsible for receiving the order at the address.
• postalCode: postal code information.
• city: shipping address city.
• state: shipping address state.
• country: shipping address country, indicated by the three-letter ISO code (e.g. "BRA", "USA").
• street: shipping address street.
• number: shipping address number.
• neighborhood: shipping address neighborhood.
• complement: shipping address complement (if necessary).
• reference: complement that might help locate the shipping address more precisely in case of delivery.
• geoCoordinates: longitude and latitude information of the shipping address.

After sending the request, the endpoint will return the response body containing the shipping address information in the shopping cart, as shown in the example below:

...
"shippingData": {
        "address": {
            "addressType": "residential",
            "receiverName": "receiver-name",
            "addressId": "c1333270f408494c88858ddc8b3de07e",
            "isDisposable": true,
            "postalCode": "12345-000",
            "city": "Rio de Janeiro",
            "state": "RJ",
            "country": "BRA",
            "street": "Praia de Botafogo",
            "number": "300",
            "neighborhood": "Botafogo",
            "complement": "3rd floor",
            "reference": "Grey building",
            "geoCoordinates": [
                -47.924747467041016,
                -15.832582473754883
            ]
        },
...

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

To add a delivery option to the shopping cart, you must have already added a shipping address (according to the previous section), and use the same Add shipping address and select delivery option endpoint. However, you need to send the request body with the logisticsInfo array containing the following information:

• itemIndex: item's position in the array or cart.
• selectedDeliveryChannel: delivery channel selected by the customer (e.g. "delivery", "pickup-in-point").
• selectedSla: selected SLA (e.g. "normal", "express").

After sending the request, the endpoint will return the response body containing the delivery option information in the shopping cart, as shown in the example below:

...
"logisticsInfo": [
            {
                "itemIndex": 0,
                "selectedSla": "normal",
                "selectedDeliveryChannel": "delivery",
                "addressId": "954ee939c1274633bfb7a5af4d6c642d",
                "slas": [],
                "shipsTo": [
                    "BRA"
                ],
                "itemId": "5",
                "deliveryChannels": [
                    {
                        "id": "delivery"
                    }
                ]
            },
...

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

• Message error example (code ORD001): "The CEP (XXXX) field in the shipping attachment is invalid": this message indicates that the postalCode used in the request does not exist or is incorrect.

{
    "fields": {},
    "error": {
        "code": "ORD001",
        "message": "The CEP (12340) field in the shipping attachment is invalid",
        "exception": null
    },
    "operationId": "37fcbaf6-9245-46b2-8735-f5fb304d1ac2"
}

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

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

• Message error example (code ORD015): "Unable to communicate with seller VTEX- Test International": this message indicates that the geoCoordinates used in the request do not exist or are incorrect.

{
    "fields": {},
    "error": {
        "code": "ORD015",
        "message": "Unable to communicate with seller VTEX- Test International",
        "exception": null
    },
    "operationId": "37fcbaf6-9245-46b2-8735-f5fb304d1ac2"
}

• Message error example (code ORD026): "A communication error with Postal Code Service has occurred": this message indicates that the country information used in the request is not in three-letter ISO code format or does not exist.

{
    "fields": {},
    "error": {
        "code": "ORD026",
        "message": "A communication error with Postal Code Service has occurred",
        "exception": null
    },
    "operationId": "37fcbaf6-9245-46b2-8735-f5fb304d1ac2"
}

• Message error example (code CHK0041): "Invalid item index": this message indicates that the itemIndex used in the request does not exist or is incorrect.

{
    "fields": {},
    "error": {
        "code": "CHK0041",
        "message": "Invalid item index",
        "exception": null
    },
    "operationId": "5d9f54e6-7db4-46d6-bca9-deeb278b8b98"
}

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

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