VTEX Cart Attachments API

openapi: 3.2.0
info:
  title: VTex Checkout Cart Attachments 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: Cart Attachments
paths:
  /api/checkout/pub/profiles:
    get:
      tags:
      - Cart Attachments
      summary: VTex Get client profile by email
      description: "Retrieves a client's profile information by providing an email address.\n\nIf the response body fields are empty, the following situations may have occurred:\n\n1. There is no client registered with the email address provided in your store, or;\n2. Client profile is invalid or incomplete. However, you can use the query parameter `ensureComplete=false` to get incomplete profiles. For more information, see [SmartCheckout - Customer information automatic fill-in](https://help.vtex.com/en/tutorial/smartcheckout-customer-information-automatic-fill-in--2Nuu3xAFzdhIzJIldAdtan).\n\n>⚠️ The authentication of this endpoint can change depending on the customer context. If you are consulting information from a customer with a complete profile on the store, the response will return the customer's data masked. You can only access the customer data with an authenticated request.\n\n## Permissions\n\nAny user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) 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:\n\n| **Product** | **Category** | **Resource** |\n| --------------- | ----------------- | ----------------- |\n| Checkout | CheckoutResources | **Shopping Cart Full Access** |\n\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\n\n| **Role** | **Resource** | \n| --------------- | ----------------- | \n| Checkout Admin | Shopping Cart Full Access |\n\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or application keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using application keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm).\n\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication)."
      operationId: GetClientProfileByEmail
      security: []
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: email
        in: query
        description: Client's email address to be searched.
        required: true
        style: form
        schema:
          type: string
          example: clark.kent@examplemail.com
      - name: ensureComplete
        in: query
        description: Indicates whether the returned profiles must be complete or not.
        required: false
        style: form
        schema:
          type: boolean
          example: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  userProfileId:
                    type: string
                    description: Unique ID associated with the customer profile.
                  profileProvider:
                    type: string
                    description: Profile provider.
                  availableAccounts:
                    type: array
                    description: Available accounts.
                    items:
                      type: string
                      description: Account name.
                  availableAddresses:
                    type: array
                    description: Information on each available address.
                    items:
                      type: object
                      description: Address information.
                      properties:
                        addressType:
                          type: string
                          description: Address type.
                        receiverName:
                          type: string
                          description: Name of the receiver.
                        addressId:
                          type:
                          - string
                          - 'null'
                          description: Address ID.
                        isDisposable:
                          type: boolean
                          description: Indicates whether address is disposable.
                        city:
                          type: string
                          description: City of the address.
                        state:
                          type: string
                          description: State of the address.
                        country:
                          type: string
                          description: Country of the address. ISO three-letter code.
                        street:
                          type: string
                          description: Street of the address.
                        number:
                          type: string
                          description: Number of the address.
                        neighborhood:
                          type: string
                          description: Neighborhood of the address.
                        complement:
                          type:
                          - string
                          - 'null'
                          description: Complement to the address.
                        reference:
                          type:
                          - string
                          - 'null'
                          description: Reference that may help in the location of the address.
                        geoCoordinates:
                          type: array
                          description: Array containing two floats with geocoordinates, first longitude, then latitude.
                          items:
                            type: number
                            description: Geocoordinates numbers.
                  userProfile:
                    type: object
                    description: Customer profile information.
                    properties:
                      email:
                        type:
                        - string
                        - 'null'
                        description: Email address.
                      firstName:
                        type:
                        - string
                        - 'null'
                        description: First name.
                      lastName:
                        type: string
                        description: Last name.
                      document:
                        type: string
                        description: Document.
                      documentType:
                        type: string
                        description: Document type.
                      phone:
                        type: string
                        description: Telephone number.
                      corporateName:
                        type:
                        - string
                        - 'null'
                        description: Name of the company. Used for corporate clients.
                      tradeName:
                        type:
                        - string
                        - 'null'
                        description: Trade name. Used for corporate clients.
                      corporateDocument:
                        type:
                        - string
                        - 'null'
                        description: Document. Used for corporate clients.
                      stateInscription:
                        type:
                        - string
                        - 'null'
                        description: State inscription. Used for corporate clients.
                      corporatePhone:
                        type:
                        - string
                        - 'null'
                        description: Telephone number. Used for corporate clients.
                      isCorporate:
                        type: boolean
                        description: Indicates whether client is corporate.
                        example: false
                      profileCompleteOnLoading:
                        type:
                        - boolean
                        - 'null'
                        description: Profile complete when loading.
                      profileErrorOnLoading:
                        type:
                        - string
                        - 'null'
                        description: Profile error when loading.
                      customerClass:
                        type:
                        - string
                        - 'null'
                        description: Customer class.
                  isComplete:
                    type: boolean
                    description: Indicates whether customer profile is complete.
              example:
                userProfileId: fb542e51-5488-4c34-8d17-ed8fcf597a94
                profileProvider: VTEX
                availableAccounts: []
                availableAddresses:
                - addressType: residential
                  receiverName: Clark Kent
                  addressId: 666c2e830bd9474ab6f6cc53fb6dd2d2
                  isDisposable: false
                  postalCode: 12345-000
                  city: Metropolis
                  state: NY
                  country: USA
                  street: My street
                  number: '123'
                  neighborhood: My neighborhood
                  complement: Complement
                  reference: Reference
                  geoCoordinates:
                  - -47.924747467041016
                  - -15.832582473754883
                userProfile:
                  email: clark.kent@example.com
                  firstName: Clark
                  lastName: Kent
                  document: '12345678900'
                  documentType: cpf
                  phone: '+556199999999'
                  corporateName: company-name
                  tradeName: trade-name
                  corporateDocument: '12345678000100'
                  stateInscription: '12345678'
                  corporatePhone: '551100988887777'
                  isCorporate: false
                  profileCompleteOnLoading: false
                  profileErrorOnLoading: false
                  customerClass: null
                isComplete: true
      deprecated: false
  /api/checkout/pub/orderForm/{orderFormId}/attachments/clientProfileData:
    post:
      tags:
      - Cart Attachments
      summary: VTex Add client profile
      description: 'Use this request to include client profile information to a given shopping cart.


        The [orderForm](https://developers.vtex.com/docs/guides/orderform-fields) is the data structure which represents a shopping cart and contains all information pertaining to it. Hence, the `orderFormId` is the identification code of a given cart.


        > This request has a time out of 12 seconds.


        >⚠️ The authentication of this endpoint can change depending on the customer context. If you are modifying information from a customer with a complete profile on the store, the response will return the customer''s data masked. You can only access the customer data with an authenticated request.


        ## Permissions


        Any user or [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) 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](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-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](https://developers.vtex.com/docs/guides/authentication).


        >❗ To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https://help.vtex.com/en/tutorial/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.'
      operationId: AddClientProfile
      security: []
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: orderFormId
        in: path
        description: ID of the orderForm that will receive client profile information.
        required: true
        style: simple
        schema:
          type: string
          example: ede846222cd44046ba6c638442c3505a
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: Customer's profile information.
              required:
              - email
              - firstName
              - lastName
              - documentType
              - document
              properties:
                email:
                  type:
                  - string
                  - 'null'
                  description: Customer's email address.
                  example: customer@examplemail.com
                firstName:
                  type:
                  - string
                  - 'null'
                  description: Customer's first name.
                  example: first-name
                lastName:
                  type: string
                  description: Customer's last name.
                  example: last-name
                documentType:
                  type: string
                  description: Type of the document informed by the customer.
                  example: cpf
                document:
                  type: string
                  description: Document number informed by the customer.
                  example: '123456789'
                phone:
                  type: string
                  description: Customer's phone number.
                  example: '+55110988887777'
                corporateName:
                  type: string
                  description: Company name, if the customer is a legal entity.
                  example: company-name
                tradeName:
                  type: string
                  description: Trade name, if the customer is a legal entity.
                  example: trade-name
                corporateDocument:
                  type: string
                  description: Corporate document, if the customer is a legal entity.
                  example: '12345678000100'
                stateInscription:
                  type: string
                  description: State inscription, if the customer is a legal entity.
                  example: '12345678'
                corporatePhone:
                  type: string
                  description: Corporate phone number, if the customer is a legal entity.
                  example: '+551100988887777'
                isCorporate:
                  type: boolean
                  description: Set `true` if the customer is a legal entity.
                  example: false
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              example:
                orderFormId: 9ceee0fde6db489fbc809a0e2ab13a86
                salesChannel: '1'
                loggedIn: false
                isCheckedIn: false
                storeId: '1'
                checkedInPickupPointId: '21'
                allowManualPrice: false
                canEditData: true
                userProfileId: fb542e51-5488-4c34-8d17-ed8fcf597a94
                userType: User type
                ignoreProfileData: false
                value: 0
                messages: []
                items: []
                selectableGifts: []
                totalizers: []
                shippingData: null
                clientProfileData:
                  email: clark.kent@examplemail.com
                  firstName: Clark
                  lastName: Kent
                  document: '44444444444'
                  documentType: cpf
                  phone: '+5511123456789'
                  corporateName: company-name
                  tradeName: trade-name
                  corporateDocument: '12345678000100'
                  stateInscription: '12345678'
                  corporatePhone: '551100988887777'
                  isCorporate: false
                  profileCompleteOnLoading: false
                  profileErrorOnLoading: false
                  customerClass: null
                paymentData:
                  updateStatus: updated
                  installmentOptions: []
                  paymentSystems: []
                  payments:
                  - paymentSystem: 6
                    bin: null
                    accountId: '12'
                    tokenId: null
                    value: 34390
                    referenceValue: 34390
                    giftCardRedemptionCode: null
                    giftCardProvider: null
                    giftCardId: null
                  giftCards: []
                  giftCardMessages: []
                  availableAccounts: []
                  availableTokens: []
                marketingData: null
                sellers: []
                clientPreferencesData:
                  locale: pt-BR
                  optinNewsLetter: null
                commercialConditionData: null
                storePreferencesData:
                  countryCode: BRA
                  saveUserData: true
                  timeZone: E. South America Standard Time
                  currencyCode: BRL
                  currencyLocale: 1046
                  currencySymbol: R$
                  currencyFormatInfo:
                    currencyDecimalDigits: 2
                    currencyDecimalSeparator: ','
                    currencyGroupSeparator: .
                    currencyGroupSize: 3
                    startsWithCurrencySymbol: true
                giftRegistryData: null
                openTextField: null
                invoiceData: null
                customData: null
                itemMetadata:
                  items:
                  - id: '1'
                    seller: '1'
                    name: Ração Royal Canin Feline Urinary 500g
                    skuName: Ração Royal Canin Feline Urinary 500g
                    productId: '1'
                    refId: '0001'
                    ean: '123456789'
                    imageUrl: http://lojadobreno.vteximg.com.br/arquivos/ids/155450-55-55/Racao-Royal-Canin-Feline-Urinary-SO.jpg?v=637139444438700000
                    detailUrl: /racao-royal-canin-feline-urinary/p
                    assemblyOptions: []
                hooksData: null
                ratesAndBenefitsData:
                  rateAndBenefitsIdentifiers: []
                  teaser: []
                subscriptionData: null
                itemsOrdination:
                  criteria: NAME
                  ascending: true
              schema:
                $ref: '#/components/schemas/orderForm'
      deprecated: false
  /api/checkout/pub/orderForm/{orderFormId}/attachments/shippingData:
    post:
      tags:
      - Cart Attachments
      summary: VTex Add shipping address and select delivery option
      description: '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. For delivery option use the `logisticsInfo` array.


        The [orderForm](https://developers.vtex.com/docs/guides/orderform-fields) is the data structure which represents a shopping cart and contains all information pertaining to it. Hence, the `orderFormId` is the identification code of a given cart.


        > This request has a time out of 12 seconds.


        >⚠️ The authentication of this endpoint can change depending on the customer context. If you are modifying information from a customer with a complete profile on the store, the response will return the customer''s data masked. You can only access the customer data with an au

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