VTEX Configuration API

openapi: 3.0.0
info:
  title: VTex Anti-fraud Provider Account Configuration 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: Configuration
paths:
  /api/checkout/pvt/configuration/orderForm:
    get:
      tags:
      - Configuration
      summary: VTex Get orderForm configuration
      description: "Retrieves the settings that are currently applied to every orderForm in the account.\n\r\n\rThese settings are defined by the request [Update orderForm configuration](https://developers.vtex.com/docs/api-reference/checkout-api#post-/api/checkout/pvt/configuration/orderForm).\n\r\n\rAlways use this request to retrieve the current configuration before performing an update. By doing so you ensure that you are modifying only the properties you want.\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 | **Save OrderForm Configuration** |\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: GetorderFormconfiguration
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  paymentConfiguration:
                    type: object
                    description: Payment configuration information.
                    properties:
                      requiresAuthenticationForPreAuthorizedPaymentOption:
                        type: boolean
                        description: Determines whether pre-authorized payments require authentication.
                      allowInstallmentsMerge:
                        type: boolean
                        description: By default (when `false`), on a multi-seller purchase is on the run, a simple intersection with installment options configured by every seller will be available. When indicated as `true`, this option allows a more complex but flexible installment option, since it considers max installments of every seller configuration, even if those do not match. Installment values may not be equal in this case.
                  taxConfiguration:
                    type: object
                    description: External tax service configuration information.
                    nullable: true
                    properties:
                      url:
                        type: string
                        description: Endpoint URL.
                        nullable: true
                      authorizationHeader:
                        type: string
                        description: Authorization header.
                        nullable: true
                      appId:
                        type: string
                        description: Custom data ID sent to the tax system.
                      isMarketplaceResponsibleForTaxes:
                        type: boolean
                        description: Indicates whether the marketplace is responsible for the products taxes.
                  minimumQuantityAccumulatedForItems:
                    type: integer
                    description: Minimum SKU quantity by cart.
                  decimalDigitsPrecision:
                    type: integer
                    description: Number of price digits.
                  minimumValueAccumulated:
                    type: integer
                    description: Minimum cart value.
                    nullable: true
                  apps:
                    type: array
                    nullable: true
                    description: Array of objects containing Apps configuration information.
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: App ID.
                        fields:
                          type: array
                          description: Array of fields available to the app.
                          items:
                            type: string
                        major:
                          type: integer
                          description: App major version.
                  allowMultipleDeliveries:
                    type: boolean
                    description: On the same purchase, allows the selection of items from multiple delivery channels.
                    nullable: true
                  allowManualPrice:
                    type: boolean
                    description: Allows the editing of SKU prices right in the cart.
                    nullable: true
                  savePersonalDataAsOptIn:
                    type: boolean
                    description: Allows users to select whether they want the store to keep their personal and payment data saved.
                    nullable: true
                  maxNumberOfWhiteLabelSellers:
                    type: integer
                    description: Allows the input of a limit of white label sellers involved on the cart.
                    nullable: true
                  maskFirstPurchaseData:
                    type: boolean
                    description: Allows, on a first purchase, masking client's data. It could be useful when a shared cart is used and the client does not want to share its data.
                    nullable: true
                  recaptchaValidation:
                    type: string
                    description: "Configures reCAPTCHA validation for the account, defining in which situations the shopper will be prompted to validate a purchase with reCAPTCHA. Learn more about [reCAPTCHA validation for VTEX stores](https://help.vtex.com/en/tutorial/using-recaptcha-at-checkout--18Te3oDd7f4qcjKu9jhNzP)\n\r\n\rPossible values are:\n\r- `\"never\"`: no purchases are validated with reCAPTCHA.\n\r- `\"always\"`: every purchase is validated with reCAPTCHA.\n\r- `\"vtexCriteria\"`: only some purchases are validated with reCAPTCHA in order to minimize friction and improve shopping experience. VTEX's algorithm determines which sessions are trustworthy and which should be validated with reCAPTCHA. This is the recommended option."
                    example: vtexCriteria
                  requiresLoginToPlaceOrder:
                    type: boolean
                    description: Indicates whether authentication is required for completing purchases.
                    example: true
                  minimumPurchaseDowntimeSeconds:
                    type: integer
                    description: Minimum interval (in seconds) between successive purchases.
                    example: 90
                  cartAgeToUseNewCardSeconds:
                    type: integer
                    description: Minimum cart existence period (in seconds) before allowing the use of a new credit card.
                    example: 30
              example:
                paymentConfiguration:
                  requiresAuthenticationForPreAuthorizedPaymentOption: false
                  allowInstallmentsMerge: false
                  blockPaymentSession: null
                taxConfiguration: null
                minimumQuantityAccumulatedForItems: 1
                decimalDigitsPrecision: 2
                minimumValueAccumulated: null
                apps:
                - fields:
                  - name
                  - age
                  id: abcd
                  major: 1
                allowMultipleDeliveries: false
                allowManualPrice: true
                savePersonalDataAsOptIn: false
                maxNumberOfWhiteLabelSellers: null
                maskFirstPurchaseData: null
                recaptchaValidation: vtexCriteria
                requiresLoginToPlaceOrder: true
                minimumPurchaseDowntimeSeconds: 90
                cartAgeToUseNewCardSeconds: 30
      deprecated: false
    post:
      tags:
      - Configuration
      summary: VTex Update orderForm configuration
      description: "Determines settings that will apply to every orderForm in the account.\n\r\n\rFor example, if you create an app using this request, every orderForm of this account will have the custom fields created though it.\n\r\n\r>ℹ️ Always retrieve the current configuration before performing an update to ensure that you are modifying only the properties you want. Otherwise, old values can be overwritten. To retrieve the current configuration, use the request [Get orderForm configuration](https://developers.vtex.com/docs/api-reference/checkout-api#get-/api/checkout/pvt/configuration/orderForm).\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 | **Save OrderForm Configuration** |\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: UpdateorderFormconfiguration
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateorderFormconfigurationRequest'
            example:
              paymentConfiguration:
                requiresAuthenticationForPreAuthorizedPaymentOption: false
              taxConfiguration: null
              minimumQuantityAccumulatedForItems: 1
              decimalDigitsPrecision: 2
              minimumValueAccumulated: null
              apps: null
              allowMultipleDeliveries: null
              allowManualPrice: null
              requiresLoginToPlaceOrder: true
              minimumPurchaseDowntimeSeconds: 90
              cartAgeToUseNewCardSeconds: 30
        required: true
      responses:
        '204':
          description: No Content. The request has succeeded.
      deprecated: false
  /api/checkout/pvt/configuration/window-to-change-seller:
    get:
      tags:
      - Configuration
      summary: VTex Get window to change seller
      description: "Retrieves a marketplace's window to change seller, that is, the period when it is possible to choose another seller to fulfill a given order after the original seller has canceled it.\n\r\n\r> The default period for this window is of 2 days, but it can be configured by the request Update window to change seller.\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 | **Save OrderForm Configuration** |\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: GetWindowToChangeSeller
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      responses:
        '200':
          description: OK
          content:
            text/plain:
              example: '2'
      deprecated: false
    post:
      tags:
      - Configuration
      summary: VTex Update window to change seller
      description: "Updates a marketplace's window to change seller, that is, the period when it is possible to choose another seller to fulfill a given order after the original seller has canceled it.\n\r\n\r> It is possible to check the current window using the request Get window to change seller.\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 | **Save OrderForm Configuration** |\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: UpdateWindowToChangeSeller
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WaitingTime'
            example:
              waitingTime: 4
        required: true
      responses:
        '201':
          description: Created
      deprecated: false
  /api/checkout/pub/orderForm/{orderFormId}/messages/clear:
    post:
      tags:
      - Configuration
      summary: VTex Clear orderForm messages
      description: "This request removes all messages from the `messages` field of the orderForm , leaving it empty.\r\n\r\nYou must send an empty JSON in the body of the request.\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.\r\n\r\n**Important**: **Request Body** must always be sent with empty value \"{ }\" in this endpoint.\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: ClearorderFormMessages
      security: []
      parameters:
      - name: orderFormId
        in: path
        description: ID of the orderForm corresponding to the cart whose messages you want to remove.
        required: true
        style: simple
        schema:
          type: string
          example: ede846222cd44046ba6c638442c3505a
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: This object must be empty.
              default: {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    description: Object response.
                    type: object
                    properties:
                      value:
                        description: Object with response value.
                        type: object
                        properties:
                          orderFormId:
                            type: string
                            description: ID of the orderForm corresponding to a specific cart.
                          salesChannel:
                            type: string
                            description: Attribute created by the seller, in their VTEX store configuration.
                          loggedIn:
                            type: boolean
                            description: Indicates whether the user is logged into the store.
                          isCheckedIn:
                            type: boolean
                            description: Indicates whether order is checked in.
                          storeId:
                            type: string
                            description: ID of the store.
                            nullable: true
                          allowManualPrice:
                            type: boolean
                            description: Permission to modify item price manually.
                          canEditData:
                            type: boolean
                            description: Data can be edited.
                          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: Available account.
                          availableAddresses:
                            type: array
                            description: Information on each available address.
                            items:
                              type: object
                              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.
                          userType:
                            type: string
                            description: User type.
                            nullable: true
                          ignoreProfileData:
                            type: boolean
                            description: Ignore customer profile data.
                          value:
                            type: integer
                            description: Total value of the order without separating cents. For example, $24.99 is represented `2499`.
                          messages:
                            type: array
                            description: Array containing an object for each message generated by our servers while processing the request.
                            items:
                              type: string
                              description: Message.
                          items:
                            type: array
                            description: Information on each item in the order.
                            items:
                              type: object
                              properties:
                                uniqueId:
                                  type: string
                                  description: Unique ID.
                                id:
                                  type: string
                                  description: ID of the item.
                                productId:
                                  type: string
                                  description: Product ID.
                                productRefId:
                                  type: string
                                  description: Product Ref ID.
                                refId:
                                  type: string
                                  description: Ref ID.
                                ean:
                                  type: string
                                  description: European Article Number.
                                  nullable: true
                                name:
                                  type: string
                                  description: Product name.
                                skuName:
                                  type: string
                                  description: SKU name.
                                modalType:
                                  type: string
                                  description: Modal type.
                                  nullable: true
                                parentItemIndex:
                                  type: integer
                                  description: Parent item index.
                                  nullable: true
                                parentAssemblyBinding:
                                  type: string
                                  description: Parent assembly binding.
                                  nullable: true
                                priceValidUntil:
                                  type: string
                                  description: Price expiration date and time.
                                tax:
                                  type: integer
                                  description: Tax value in cents.
                                price:
                                  type: integer
                                  description: Price in cents.
                                listPrice:
                                  type: integer
                                  description: List price in cents.
                                manualPrice:
                                  type: integer
                                  description: Manual price in cents.
                                  nullable: true
                                manualPriceAppliedBy:
                                  type: string
                                  description: User that applied the manual price, if that is the case.
                                  nullable: true
                                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.
                                rewardValue:
                                  type: integer
                                  description: Reward value in cents.
                                isGift:
                                  type: boolean
                                  description: Indicates whether item is a gift.
                                additionalInfo:
                                  type: object
                                  description: Additional information.
                                  properties:
                                    dimension:
                                      type: string
                                      description: Dimension.
                                      nullable: true
                                    brandName:
                                      type: string
                                      description: Brand name.
                                    brandId:
                                      type: string
                                      d

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