VTEX Shopping Cart API

openapi: 3.2.0
info:
  title: VTex Checkout Shopping Cart API
  description: '>ℹ️ Check the new [Checkout onboarding guide](https://developers.vtex.com/vtex-rest-api/docs/checkout-overview). We created this guide to improve the onboarding experience for developers at VTEX. It assembles all documentation on our Developer Portal about the Checkout and is organized by focusing on the developer''s journey.


    The Checkout API allows you to obtain and configure information about the shopping cart and its attachments, personalization of custom fields, orderForm structure, fulfillment data, order management, and identification of the sellers delivery region.


    >ℹ️ Data modification operations (`POST`, `PATCH`, `PUT` or `DELETE` endpoints) shall not be performed in parallel in the Checkout APIs. They need to be enqueued by the client/requester. Otherwise, old values ​​can be overwritten incorrectly or competition errors may occur.


    >⚠️ All endpoints that consult or edit the orderForm can change the authentication depending on the customer context. If you are handling information from a customer with a complete profile on the store, authentication will be required. You can only access or modify the customer data for these profiles with an authenticated request.


    ## Shopping cart


    Allows merchants to simulate, configure and customize shopping cart information.


    - [POST - Cart Simulation](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForms/simulation): simulate a cart in VTEX Checkout.

    - [GET - Get current or create a new cart](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/orderForm): get your current shopping cart information or to create a new cart.

    - [GET - Get cart information by ID](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/orderForm/-orderFormId-): get all information associated to a given shopping cart.

    - [POST - Add cart items](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/items): add a new item to the shopping cart.

    - [POST - Update cart items](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/items/update): change the quantity of one or more items in a specific cart or remove an item from the cart.

    - [PATCH - Handle cart items](https://developers.vtex.com/docs/api-reference/checkout-api#patch-/api/checkout/pub/orderForm/-orderFormId-/items): change the quantity or price of one or more items to the shopping cart or add a new item to the shopping cart.

    - [POST - Remove all items](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/items/removeAll): removes all items from a given cart, leaving it empty.

    - [PUT - Change price](https://developers.vtex.com/docs/api-reference/checkout-api#put-/api/checkout/pub/orderForm/-orderFormId-/items/-itemIndex-/price): changes the price of an SKU in a cart.

    - [GET - Cart installments](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/orderForm/-orderFormId-/installments): retrieves possible amount of installments and respective values for a given cart with a given payment method.


    ## Cart attachments


    Allows merchants to obtain client profiles and add information to a given shopping cart.


    - [GET - Get client profile by email](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/profiles): retrieve a client''s profile information by providing an email address.

    - [POST - Add client profile](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/attachments/clientProfileData): include client profile information to a given shopping cart.

    - [Patch - Ignore profile data](https://developers.vtex.com/docs/api-reference/checkout-api#patch-/api/checkout/pub/orderForm/-orderFormId-/profile): disable the automatic inclusion of profile information in a shopping cart when a shopper provides an email address at checkout.

    - [GET - Remove all personal data](https://developers.vtex.com/docs/api-reference/checkout-api#get-/checkout/changeToAnonymousUser/-orderFormId-): removes all user information, making a cart anonymous while leaving the items.

    - [POST - Add client preferences](https://developers.vtex.com/docs/api-reference/checkout-api#patch-/api/checkout/pub/orderForm/-orderFormId-/items): include client preferences information to a given shopping cart.

    - [POST - Add shipping address and select delivery option](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/attachments/shippingData): include shipping information and/or selected delivery option to a given shopping cart.

    - [POST - Add marketing data](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/attachments/marketingData): include marketing information to a given shopping cart.

    - [POST - Add payment data](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/attachments/paymentData): include payment information to a given shopping cart.

    - [POST - Add merchant context data](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/attachments/merchantContextData): add to the cart any relevant information that is related to the context of a specific order.

    - [POST - Add coupons to the cart](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/coupons): add coupons to a given shopping cart.


    ## Custom data


    Allows merchants to manage custom fields that were created by an app in their account.


    - [PUT - Set multiple custom field values](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/coupons): allows you to update the values of custom fields created in your account''s apps.

    - [PUT - Set single custom field value](https://developers.vtex.com/docs/api-reference/checkout-api#put-/api/checkout/pub/orderForm/-orderFormId-/customData/-appId-/-appFieldName-): allows you to update the value of a specific custom field created in your account''s apps.

    - [DELETE - Remove single custom field value](https://developers.vtex.com/docs/api-reference/checkout-api#delete-/api/checkout/pub/orderForm/-orderFormId-/customData/-appId-/-appFieldName-): allows you to remove the value of a specific custom field created in your account''s apps.


    ## Configuration


    Allows merchants to configure orderForm in the account and seller exchange on a given order.


    - [GET - Get orderForm configuration](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pvt/configuration/orderForm): retrieves the settings that are currently applied to every [`orderForm`](https://developers.vtex.com/docs/guides/orderform-fields) in the account.

    - [POST - Update orderForm configuration](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pvt/configuration/orderForm): determines settings that will apply to every [`orderForm`](https://developers.vtex.com/docs/guides/orderform-fields) in the account.

    - [GET - Get window to change seller](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pvt/configuration/window-to-change-seller): retrieves a marketplace’s window to change seller.

    - [POST - Update window to change seller](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pvt/configuration/window-to-change-seller): updates a marketplace’s window to change seller.

    - [POST - Clear orderForm messages](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/messages/clear): removes all messages from the `messages` field of the [`orderForm`](https://developers.vtex.com/docs/guides/orderform-fields).


    ## Fulfillment


    Allows merchants to obtain pickup points and address information.


    - [GET - List pickup points by location](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/pickup-points): retrieves information on pickup points close to a given location determined by geocoordinates or postal code.

    - [GET - Get address by postal code](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/postal-code/-countryCode-/-postalCode-): retrieves address information for a given postal code and country.


    ## Order placement


    Allows merchants to place and process orders by creating a new cart or using an existing cart.


    - [POST - Place order from an existing cart](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/orderForm/-orderFormId-/transaction): places an order from an existing [`orderForm`](https://developers.vtex.com/docs/guides/orderform-fields) object, meaning an existing cart.

    - [PUT - Place order](https://developers.vtex.com/docs/api-reference/checkout-api#put-/api/checkout/pub/orders): places order without having any prior cart information.

    - [POST - Process order](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pub/gatewayCallback/-orderGroup-): order processing callback request, which is made after an order''s payment is approved.


    ## Region


    Allows merchants to obtain a list of sellers serving a specific delivery region.


    - [GET - Get sellers by region or address](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pub/regions/-regionId-)": retrieves a list of sellers that cater to a specific region or address.


    ## Common parameters in the documentation


    | Parameter name            | Description                                                                             |

    |---------------------------|-----------------------------------------------------------------------------------------|

    | `{{accountName}}`         | Store account name                                                                      |

    | `{{environment}}`         | The environment that will be called. Change for vtexcommercestable or vtexcommmercebeta |

    | `{{X-VTEX-API-AppKey}}`   | Located in the headers of the requests, user authentication key                         |

    | `{{X-VTEX-API-AppToken}}` | Located in the headers of the requests, authentication password                         |

    '
  contact: {}
  version: '1.0'
servers:
- url: https://{accountName}.{environment}.com.br
  description: VTEX server URL.
  variables:
    accountName:
      description: Name of the VTEX account. Used as part of the URL
      default: apiexamples
    environment:
      description: Environment to use. Used as part of the URL.
      enum:
      - vtexcommercestable
      default: vtexcommercestable
security:
- appKey: []
  appToken: []
- VtexIdclientAutCookie: []
tags:
- name: Shopping Cart
paths:
  /api/checkout/pub/orderForms/simulation:
    post:
      tags:
      - Shopping Cart
      summary: VTex Cart simulation
      description: 'This endpoint is used to simulate a cart in VTEX Checkout.


        It receives an SKU ID, the quantity of items in the cart and the seller ID.


        It returns all information about the cart, such as the selling price of each item, pricing and promotion data, payment and logistics info.


        This request is useful whenever you need to know the availability of fulfilling an order for a specific cart setting, since the API response will let you know the updated price, inventory and shipping data.


        >⚠️ The fields (`sku id`, `quantity`, `seller`, `country`, `postalCode` and `geoCoordinates`) are just examples of content that you can simulate in your cart. You can add more fields to the request as per your need. Access the [orderForm](https://developers.vtex.com/docs/guides/orderform-fields) guide to check the available fields.


        ## Permissions


        This endpoint does not require [authentication](https://developers.vtex.com/docs/guides/authentication) or [permissions](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).'
      operationId: CartSimulation
      security: []
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: RnbBehavior
        in: query
        description: 'This parameter defines which promotions apply to the simulation. Use `0` for simulations at cart stage, which means all promotions apply. In case of window simulation use `1`, which indicates promotions that apply nominal discounts over the total purchase value shouldn''t be considered on the simulation.


          Note that if this not sent, the parameter is `1`.'
        required: false
        style: form
        schema:
          type: integer
          example: 0
      - name: sc
        in: query
        description: Trade Policy (Sales Channel) identification.
        required: false
        style: form
        schema:
          type: integer
          example: 1
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - id
              - quantity
              - seller
              properties:
                items:
                  type: array
                  description: Array containing information about the SKUs inside the cart to be simulated.
                  items:
                    type: object
                    description: SKU information.
                    properties:
                      id:
                        type: string
                        description: The SKU ID.
                        example: '1'
                      quantity:
                        type: integer
                        format: int32
                        description: The quantity of items of this specific SKU in the cart to be simulated.
                        example: 1
                      seller:
                        type: string
                        description: The ID of the seller responsible for this SKU. This ID can be found in your VTEX Admin.
                        example: '1'
                country:
                  type: string
                  description: Three letter ISO code of the country of the shipping address. This value must be sent along with the `postalCode` or `geoCoordinates` values.
                  example: BRA
                postalCode:
                  type: string
                  description: Postal code.
                  example: 12345-000
                geoCoordinates:
                  type: array
                  description: Array containing two floats with geocoordinates, first longitude, then latitude.
                  example:
                  - -47.924747467041016
                  - -15.832582473754883
                  items:
                    description: Geocoordinates.
                    type: number
                    example: -47.924747467041016
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    description: Information on each item in the cart.
                    items:
                      type: object
                      description: Object containing information of the item.
                      properties:
                        id:
                          type: string
                          description: ID of the item.
                        requestIndex:
                          type: integer
                          description: Request index information.
                        quantity:
                          type: integer
                          description: The quantity of the item the cart.
                        seller:
                          type: string
                          description: The seller responsible for the SKU.
                        sellerChain:
                          type: array
                          description: Sellers involved in the chain. The list should contain only one seller, unless it is a [Multilevel Omnichannel Inventory](https://help.vtex.com/en/tutorial/multilevel-omnichannel-inventory--7M1xyCZWUyCB7PcjNtOyw4) order.
                          items:
                            type: string
                            description: Seller.
                        tax:
                          type: integer
                          description: Tax value in cents.
                        taxCode:
                          type: string
                          description: A unique identifier code assigned to a tax within the VTEX Admin.
                        priceValidUntil:
                          type: string
                          description: Price expiration date and time.
                        price:
                          type: integer
                          description: Price in cents.
                        listPrice:
                          type: integer
                          description: List price in cents.
                        rewardValue:
                          type: integer
                          description: Reward value in cents.
                        sellingPrice:
                          type: integer
                          description: Selling price in cents. Note that this field may be subject to rounding discrepancies. We recommend retrieving data from the `priceDefinition` data structure instead.
                        offerings:
                          type: array
                          description: Array containing offering information of SKU service. A service is an item that may come with a product, optionally and with cost. It is used to assign a value of an additional service itself to an SKU.
                          items:
                            type: object
                            description: Service general information.
                            properties:
                              type:
                                type: string
                                description: Service type.
                              id:
                                type: string
                                description: Service type ID.
                              name:
                                type: string
                                description: Name of the service type.
                              allowGiftMessage:
                                type: boolean
                                description: Option to display the service type on the gift card.
                              attachmentOfferings:
                                type: array
                                description: Array of attachments that will be added to the service type. The attachment is used to add customized information to the service.
                                items:
                                  type: string
                                  description: Attachment of the product.
                              price:
                                type: integer
                                description: Service type price.
                        priceTags:
                          type: array
                          description: Array of price tags, each of which, modifies the price in some way, like discounts or rates that apply to the item in the context of the order.
                          items:
                            type: object
                            description: Price tag information.
                            properties:
                              name:
                                type: string
                                description: Price tag name.
                              value:
                                type: integer
                                description: Price tag value.
                              rawValue:
                                type: integer
                                description: Price tag raw value.
                              isPercentual:
                                type: boolean
                                description: Indicates whether price tag value is applied through a percentage.
                              identifier:
                                type:
                                - string
                                - 'null'
                                description: Price tag identifier.
                              owner:
                                type: string
                                description: Identification of the responsible for the price tag.
                        measurementUnit:
                          type: string
                          description: Measurement unit.
                        unitMultiplier:
                          type: integer
                          description: Unit multiplier.
                        parentItemIndex:
                          type:
                          - integer
                          - 'null'
                          description: Parent item index.
                        parentAssemblyBinding:
                          type:
                          - string
                          - 'null'
                          description: Parent assembly binding.
                        availability:
                          type: string
                          description: Availability.
                        priceDefinition:
                          type: object
                          description: Price information for all units of a specific item.
                          properties:
                            calculatedSellingPrice:
                              type: integer
                              description: Item's calculated unitary selling price in cents.
                            total:
                              type: integer
                              description: Total value for all units of the item in cents.
                            sellingPrices:
                              type: array
                              description: Array of objects, each containing value (in cents) and quantity for the different rounding instances that can be combined to form the correctly rounded total.
                              items:
                                type: object
                                description: Item value and rounding quantity.
                                properties:
                                  value:
                                    type: integer
                                    description: Value in cents for that specific rounding.
                                  quantity:
                                    type: integer
                                    description: Rounding quantity, meaning how many items are rounded to this value.
                  ratesAndBenefitsData:
                    type: object
                    description: Information on pricing and promotions that apply to the order.
                    properties:
                      rateAndBenefitsIdentifiers:
                        type: array
                        description: List with pricing and promotions identifiers.
                        items:
                          type: string
                          description: Promotion identifier.
                      teaser:
                        type: array
                        description: List with pricing and promotions teaser.
                        items:
                          type: string
                          description: Promotion teaser.
                  paymentData:
                    type: object
                    description: Payment data information.
                    properties:
                      installmentOptions:
                        type: array
                        description: List of Installment options.
                        items:
                          type: object
                          description: Information about the installment option.
                          properties:
                            paymentSystem:
                              type: integer
                              description: Payment system identification.
                            bin:
                              type:
                              - string
                              - 'null'
                              description: Card bin.
                            paymentName:
                              type:
                              - string
                              - 'null'
                              description: Payment name.
                            paymentGroupName:
                              type:
                              - string
                              - 'null'
                              description: Payment group name.
                            value:
                              type: integer
                              description: Total value assigned to this payment.
                            installments:
                              type: array
                              description: Installment information.
                              items:
                                type: object
                                description: Installment information.
                                properties:
                                  count:
                                    type: integer
                                    description: Count information.
                                  hasInterestRate:
                                    type: boolean
                                    description: Indicates whether the payment has interest.
                                  interestRate:
                                    type: integer
                                    description: Interest rate value.
                                  value:
                                    type: integer
                                    description: Value of the order without the interest rate. The value is shown without separating cents.
                                  total:
                                    type: integer
                                    description: Total value of the order without separating cents. For example, $24.99 is represented `2499`.
                                  sellerMerchantInstallments:
                                    type: array
                                    description: Seller merchant installments information.
                                    items:
                                      type: object
                                      description: Installment information.
                      paymentSystems:
                        type: array
                        description: Information on payment systems.
                        items:
                          type: object
                          description: Payment system information.
                          properties:
                            id:
                              type: integer
                              description: Payment system ID.
                            name:
                              type: string
                              description: Payment system name.
                            groupName:
                              type: string
                              description: Payment group name.
                            validator:
                              type:
                              - object
                              - 'null'
                              description: Payment system validator.
                            stringId:
                              type: string
                              description: String ID.
                            template:
                              type: string
                              description: Template.
                            requiresDocument:
                              type: boolean
                              description: Indicates whether a document is required.
                            displayDocument:
                              type: boolean
                              description: Indicates whether a document is shown.
                            isCustom:
                              type: boolean
                              description: Indicates whether it is custom.
                            description:
                              type: string
                              description: Description.
                            requiresAuthentication:
                              type: boolean
                              description: Indicates whether a authentication is required.
                            dueDate:
                              type: string
                              description: Payment due date.
                            availablePayments:
                              type:
                              - string
                              - 'null'
                              description: Availability of payment.
                      payments:
                        type: array
                        description: Information on each payment.
                        items:
                          type: string
                          description: Payment information.
                      giftCards:
                        type: array
                        description: Gift card information, if it applies to the order.
                        items:
                          type: string
                          description: Gift card.
                      giftCardMessages:
                        type: array
                        description: Array of gift card messages.
                        items:
                          type: string
                          description: Gift card message.
                      availableAccounts:
                        type: array
                        description: Available accounts.
                        items:
                          type: string
                          description: Available account.
                      availableTokens:
                        type: array
                        description: Available tokens.
                        items:
                          type: string
                          description: Available token.
                      availableAssociations:
                        type: object
                        description: Available associations.
                  selectableGifts:
                    type: array
                    description: Array containing the data of the items selected as a gift.
                    items:
                      type: string
                      description: Selected gift item.
                  marketingData:
                    type:
                    - object
                    - 'null'
                    description: Object containing promotion data such as coupon tracking information and internal or external UTMs.
                  postalCode:
                    type:
                    - string
                    - 'null'
                    description: Postal code.
                  country:
                    type: string
                    description: Three letter ISO code of the country of the shipping address.
                  logisticsInfo:
                    type: array
                    description: Array with logistics information on each item of the `items` array in the `orderForm`.
                    items:
                      description: Logistics information of a item.
                      type: object
                      properties:
                        itemIndex:
                          type: integer
                          description: Index of item in items array.
                        addressId:
         

# --- truncated at 32 KB (282 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vtex/refs/heads/main/openapi/vtex-shopping-cart-api-openapi.yml