VTEX Cart Attachments API

openapi: 3.0.0
info:
  title: VTex Anti-fraud Provider Account Cart Attachments API
  description: ">ℹ️ Onboarding guide\r\n>\r\n> Check the new [Payments onboarding guide](https://developers.vtex.com/docs/guides/payments-overview). We created this guide to improve the onboarding experience for developers at VTEX. It assembles all documentation on our Developer Portal about Payments and is organized by focusing on the developer's journey.\r\n\r\nThe Anti-fraud Provider Protocol is a set of definitions to help you integrate your anti-fraud service API into VTEX platform.\r\n\r\nTo achieve this, you need to implement a web API (REST) following the specifications described in this documentation.\r\n\r\n>⚠️ You can also access our [template on GitHub](https://github.com/vtex-apps/antifraud-provider-example) to help you quickly develop your anti-fraud connector using the Anti-fraud Provider Protocol and VTEX IO.\r\n\r\nTo learn more about the Anti-fraud Provider Protocol, check our [developer guide](https://developers.vtex.com/docs/guides/how-the-integration-protocol-between-vtex-and-antifraud-companies-works).\r\n\r\n## Anti-fraud Provider API Index\r\n\r\n### Anti-fraud  Flow\r\n\r\n- `POST` [Send Anti-fraud Pre-Analysis Data (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/pre-analysis)\r\n- `POST` [Send Anti-fraud Data](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/transactions)\r\n- `PUT` [Update Anti-fraud Transactions (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#put-/transactions/-transactionId-)\r\n- `GET` [List Anti-fraud Provider Manifest](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/manifest)\r\n- `GET` [Get Anti-fraud Status](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/transactions/-transactions.id-)\r\n- `DELETE` [Stop Anti-fraud Analysis (optional)](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#delete-/transactions/-transactions.Id-)\r\n\r\n### OAuth Flow\r\n\r\n1. `POST` [Retrieve Token](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#post-/authorization/token)\r\n2. `GET` [Redirect](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/redirect)\r\n3. `GET` [Return to VTEX](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/authorizationCode)\r\n4. `GET` [Get Credentials](https://developers.vtex.com/docs/api-reference/antifraud-provider-protocol#get-/authorization/credentials)"
  version: '1.0'
servers:
- url: https://{providerApiEndpoint}
  description: Anti-fraud provider endpoint URL.
  variables:
    providerApiEndpoint:
      description: Anti-fraud provider endpoint URL.
      default: '{providerApiEndpoint}'
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\r\n\rIf the response body fields are empty, the following situations may have occurred:\n\r\n\r1. There is no client registered with the email address provided in your store, or;\n\r2. 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).\r\n\r\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.\r\n\r\n## Permissions\r\n\r\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:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Checkout | CheckoutResources | **Shopping Cart Full Access** |\r\n\r\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):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Checkout Admin | Shopping Cart Full Access |\r\n\r\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).\r\n\r\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
                          description: Address ID.
                          nullable: true
                        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
                          description: Complement to the address.
                          nullable: true
                        reference:
                          type: string
                          description: Reference that may help in the location of the address.
                          nullable: true
                        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
                        description: Email address.
                        nullable: true
                      firstName:
                        type: string
                        description: First name.
                        nullable: true
                      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
                        description: Name of the company. Used for corporate clients.
                        nullable: true
                      tradeName:
                        type: string
                        description: Trade name. Used for corporate clients.
                        nullable: true
                      corporateDocument:
                        type: string
                        description: Document. Used for corporate clients.
                        nullable: true
                      stateInscription:
                        type: string
                        description: State inscription. Used for corporate clients.
                        nullable: true
                      corporatePhone:
                        type: string
                        description: Telephone number. Used for corporate clients.
                        nullable: true
                      isCorporate:
                        type: boolean
                        description: Indicates whether client is corporate.
                        example: false
                      profileCompleteOnLoading:
                        type: boolean
                        description: Profile complete when loading.
                        nullable: true
                      profileErrorOnLoading:
                        type: string
                        description: Profile error when loading.
                        nullable: true
                      customerClass:
                        type: string
                        description: Customer class.
                        nullable: true
                  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.\r\n\r\nThe [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.\n\r\n\r> This request has a time out of 12 seconds.\r\n\r\n>⚠️ 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.\r\n\r\n## Permissions\r\n\r\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:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Checkout | CheckoutResources | **Read Shopping Cart** |\r\n\r\nThere 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).\r\n\r\n>❗ 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
                  description: Customer's email address.
                  example: customer@examplemail.com
                  nullable: true
                firstName:
                  type: string
                  description: Customer's first name.
                  example: first-name
                  nullable: true
                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.\r\n\r\nTo add shipping addresses send the `selectedAddresses` array. For delivery option use the `logisticsInfo` array.\r\n\r\nThe [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.\n\r\n\r> This request has a time out of 12 seconds.\r\n\r\n>⚠️ 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.\r\n\r\n## Permissions\r\n\r\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:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Checkout | CheckoutResources | **Read Shopping Cart** |\r\n\r\nThere 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).\r\n\r\n>❗ 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: AddShippingAddress
      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
              properties:
                clearAddressIfPostalCodeNotFound:
                  type: boolean
                  description: This field should be sent as `false` to prevent the address information from being filled in automatically based on the `postalCode` information.
                  example: false
                selectedAddresses:
                  type: array
                  description: List of objects with addresses information.
                  items:
                    type: object
                    description: Address information.
                    properties:
                      addressType:
                        type: string
                        description: Type of address. For example, `Residential` or `Pickup`, among others.
                        example: residential
                      receiverName:
                        type: string
                        description: Name of the person who is going to receive the order.
                        example: receiver name
                      addressId:
                        type: string
                        description: Address ID.
                        example: c3701fc4c61b4d1b91f67e81415db44d
                        nullable: true
                      postalCode:
                        type: string
                        description: Postal Code.
                        example: 12345-000
                      city:
                        type: string
                        description: City of the shipping address.
                        example: Rio de Janeiro
                      state:
                        type: string
                        description: State of the shipping address.
                        example: RJ
                      country:
                        type: string
                        description: Three letter ISO code of the country of the shipping address.
                        example: BRA
                      street:
                        type: string
                        description: Street of the shipping address.
                        example: Praia de Botafogo
                      number:
                        type: string
                        description: Number of the building, house or apartment in the shipping address.
                        example: '300'
                      neighborhood:
                        type: string
                        description: Neighborhood of the shipping address.
                        example: Botafogo
                      complement:
                        type: string
                        description: Complement to the shipping address in case it applies.
                        example: 3rd floor
                      reference:
                        type: string
                        description: Complement that might help locate the shipping address more precisely in case of delivery.
                        example: Grey building
                      geoCoordinates:
                        type: array
                        description: Array containing two floats with geocoordinates, first longitude, then latitude.
                        example:
                        - -47.924747467041016
                        - -15.832582473754883
                        items:
                          type: number
                          example: -47.924747467041016
                          description: Geocoordinates.
                logisticsInfo:
                  type: array
                  description: Array with logistics information on each item of the `items` array in the `orderForm`.
                  items:
                    type: object
                    description: Logistic information.
                    properties:
                      itemIndex:
                        type: integer
                        description: Index of item in items array.
                        example: 0
                      selectedDeliveryChannel:
                        type: string
                        description: Delivery channel selected by the customer. For example, `"delivery"` or `"pickup-in-point"`.
                        example: delivery
                        nullable: true
                      selectedSla:
                        type: string
                        description: Selected SLA. For example, `"normal"` or `"express"`.
                        example: normal
                        nullable: true
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/orderForm'
              example:
                orderFormId: 2f586e50342a4f87b7e0654c56299e88
                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:
                  address:
                    addressType: residential
                    receiverName: Clark Kent
                    addressId: c3701fc4c61b4d1b91f67e81415db44d
                    isDisposable: true
                    postalCode: '12345000'
                    city: Rio de Janeiro
                    state: ST
                    country: BRA
                    street: My street
                    number: '1091'
                    neighborhood: My neighborhood
                    complement: null
                    reference: null
                    geoCoordinates: []
                  logisticsInfo:
                  - itemIndex: 0
                    selectedSla: Normal
                    selectedDeliveryChannel: delivery
                    addressId: f239ad30f8c948a382543ab2c739b967
                    slas:
                    - id: Retirada (VTEXSP)
                      deliveryChannel: pickup-in-point
                      name: Retirada (VTEXSP)
                      deliveryIds:
                      - courierId: 1ee17c2
                        warehouseId: '1_1'
                        dockId: '1'
                        courierName: Retira em Loja
                        quantity: 2
                        kitItemDetails: []
                      shippingEstima

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