Add shipping address and select delivery option

Use this request to include shipping information and/or selected delivery option to a given shopping cart.

To add shipping addresses, send the selectedAddresses array. To select a delivery option, use the logisticsInfo array.

The orderFormId identifies the shopping cart. For more information, see orderForm.

This request has a timeout of 12 seconds.

⚠️ If the request modifies a customer with a complete profile, the response will return masked data. To access unmasked data, use an authenticated request.

Delivery option selection

If no selectedSla is sent in the request body, the API will automatically select the best delivery option among the ones available in the slas array, excluding pickup options and scheduled delivery options. If no such option is available, none will be selected.

The best delivery option selected is the one that can fulfill the biggest item quantity for the lowest price. This selection does not consider delivery time.

This process happens after the White Label Sellers selection in the Checkout pipeline. White label sellers selection is a separate process and is the responsibility of the Order Allocation module. For more information, see the White label sellers selection article.

For a pickup option or a scheduled delivery option to be selected, it must be explicitly sent in the request body in the selectedSla field.

Permissions

Any user or API key must have at least one of the appropriate License Manager resources to be able to successfully run this request. Otherwise they will receive a status code 403 error. These are the applicable resources for this endpoint:

Product	Category	Resource
Checkout	CheckoutResources	Read Shopping Cart

There are no applicable predefined roles for this resource list. You must create a custom role and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see Authentication overview.

❗ To prevent integrations from having excessive permissions, consider the best practices for managing API keys when assigning License Manager roles to integrations.

orderFormIdstring required

Example:ede846222cd44046ba6c638442c3505a

ID of the orderForm that will receive client profile information.

individualShippingEstimatesboolean

Example:true

Shows the product's estimated shipping date in the shippingEstimate field from the orderForm.

Content-Typestring required

Type of the content being sent.

Acceptstring required

HTTP Client Negotiation Accept Header. Indicates the types of responses the client can understand.

Request body

clearAddressIfPostalCodeNotFoundboolean

This field should be sent as false to prevent the address information from being filled in automatically based on the postalCode information.

Example request

{
  "selectedAddresses": [
    {
      "addressType": "residential",
      "receiverName": "receiver name",
      "addressId": "c3701fc4c61b4d1b91f67e81415db44d",
      "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
      ]
    }
  ],
  "logisticsInfo": [
    {
      "selectedDeliveryChannel": "delivery",
      "selectedSla": "normal"
    }
  ]
}

Response

OK

orderFormIdstring

ID of the orderForm corresponding to a specific cart.

salesChannelstring

Attribute created by the seller, in their VTEX store configuration.

loggedInboolean

Indicates whether the user is logged into the store.

isCheckedInboolean

Indicates whether order is checked in.

storeIdstring nullable

ID of the store.

allowManualPriceboolean

Permission to modify item price manually.

canEditDataboolean

Data can be edited.

userProfileIdstring nullable

Unique ID associated with the customer profile.

profileProviderstring

Profile provider.

availableAccountsstring[]

Available accounts.

userTypestring nullable

User type.

ignoreProfileDataboolean

Ignore customer profile data.

valueinteger

Total value of the order without separating cents. For example, $24.99 is represented as 2499.

messagesstring[]

Array containing an object for each message generated by our servers while processing the request.

selectableGiftsstring[]

Array containing the data of the item selected as a gift.

totalizersobject[]

Array containing an object for each totalizer for the purchase. Totalizers contain the sum of values for a specific part of the order (e.g. Total item value, Total shipping value).

commercialConditionDataobject nullable

Object containing commercial condition information.

storePreferencesDataobject

Object containing data from the store's configuration (stored in VTEX's License Manager).

giftRegistryDataobject nullable

Gift registry list information.

openTextFieldstring nullable

Optional field meant to hold additional information about the order. We recommend using this field for text, not data formats such as JSON even if escaped. For that purpose, see Creating customizable fields.

hooksDataobject nullable

Hooks information.

subscriptionDataobject nullable

Subscription information.

v52

Add shipping address and select delivery option

Delivery option selection

Permissions

Path parameters

Query parameters

Headers

Request body

Example request

Response