VTEX Order Placement API

openapi: 3.0.0
info:
  title: VTex Anti-fraud Provider Account Order Placement 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: Order Placement
paths:
  /api/checkout/pub/orderForm/{orderFormId}/transaction:
    post:
      tags:
      - Order Placement
      summary: VTex Place order from an existing cart
      description: "This endpoint places an order from an existing `orderForm` object, meaning an existing cart.\n\r\n\rAfter the creation of an order with this request, you have five minutes to send payment information and then request payment processing.\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: PlaceOrderFromExistingOrderForm
      security: []
      parameters:
      - name: orderFormId
        in: path
        description: ID of the `orderForm` corresponding to the cart from which to place the order.
        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
              required:
              - referenceId
              - value
              - referenceValue
              - interestValue
              properties:
                referenceId:
                  title: referenceId
                  type: string
                  description: ID of the `orderForm` corresponding to the cart from which to place the order. This is the same as the `orderFormId` parameter.
                  example: 41a22925298a4ddca95318131a25b000
                savePersonalData:
                  title: savePersonalData
                  type: boolean
                  description: '`true` if the shopper''s data provided during checkout should be saved for future reference.'
                  example: false
                optinNewsLetter:
                  title: optinNewsLetter
                  type: boolean
                  description: True if the shopper opted to receive the newsletter.
                  example: false
                  nullable: true
                value:
                  type: integer
                  description: Total value of the order without separating cents. For example, $24.99 is represented `2499`.
                  example: 6800
                referenceValue:
                  type: integer
                  description: Reference value of the order for calculating interest if that is the case. Can be equal to the total value and does not separate cents. For example, $24.99 is represented `2499`.
                  example: 6800
                interestValue:
                  type: integer
                  description: Interest rate to be used in case it applies.
                  example: 0
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/orderForm'
              example:
                orderForm: null
                transactionData:
                  merchantTransactions:
                  - id: STORE
                    transactionId: 62FEDE228E2144649CF67812C4E5ER79
                    merchantName: STORE
                    payments:
                    - paymentSystem: 6
                      bin: null
                      accountId: '12'
                      value: 15650
                      referenceValue: 15650
                      giftCardRedemptionCode: null
                      giftCardProvider: null
                      giftCardId: null
                  receiverUri: https://store.vtexpayments.com.br/split/v976778amgh/payments
                  gatewayCallbackTemplatePath: /checkout/gatewayCallback/v976778amgh/{messageCode}
                orders:
                - orderId: v976778amgh-01
                  orderGroup: v976778amgh
                  state: order-created
                  isCheckedIn: false
                  sellerOrderId: 00-v976778amgh-01
                  storeId: '1'
                  value: 15650
                  items:
                  - uniqueId: 0F93E9C4926A4CD97FDD4C2599BDF9DB
                    id: '2000016'
                    productId: '2000002'
                    refId: 35-Preto
                    ean: null
                    name: Produto Seleção SKU - Lista 35 - Preto
                    skuName: 35 - Preto
                    modalType: null
                    priceValidUntil: '2018-02-16T23:42:44.5467295Z'
                    tax: 0
                    price: 15000
                    listPrice: 15000
                    manualPrice: null
                    sellingPrice: 15000
                    rewardValue: 1
                    isGift: false
                    additionalInfo:
                      brandName: Marca Um
                      brandId: '1'
                      offeringInfo: null
                      offeringType: null
                      offeringTypeId: null
                    preSaleDate: null
                    productCategoryIds: /12/28/
                    productCategories:
                      '12': Departamento 5
                      '28': Categoria 5-3
                    defaultPicker: null
                    handlerSequence: 0
                    handling: false
                    quantity: 1
                    seller: '1'
                    imageUrl: http://store.vteximg.com.br/arquivos/ids/168463-55-55/imagem-modo-lista.png
                    detailUrl: /produto-selecao-sku-lista/p
                    components: []
                    bundleItems: []
                    attachments: []
                    itemAttachment:
                      name: null
                      content: {}
                    attachmentOfferings: []
                    offerings: []
                    priceTags: []
                    availability: available
                    measurementUnit: un
                    unitMultiplier: 1
                  sellers:
                  - id: '1'
                    name: Store
                    logo: Logo
                  totals:
                  - id: Items
                    name: Total dos Itens
                    value: 15000
                  - id: Discounts
                    name: Total dos Descontos
                    value: 0
                  - id: Shipping
                    name: Total do Frete
                    value: 650
                  - id: Tax
                    name: Total da Taxa
                    value: 0
                  clientProfileData:
                    email: clark.kent@examplemail.com
                    firstName: Clark
                    lastName: Kent
                    document: '12345678900'
                    documentType: cpf
                    phone: '+5500123456789'
                    corporateName: company-name
                    tradeName: trade-name
                    corporateDocument: '12345678000100'
                    stateInscription: '12345678'
                    corporatePhone: '551100988887777'
                    isCorporate: false
                    profileCompleteOnLoading: false
                    profileErrorOnLoading: false
                    customerClass: null
                  ratesAndBenefitsData:
                    attachmentId: ratesAndBenefitsData
                    rateAndBenefitsIdentifiers: []
                    teaser: []
                  shippingData:
                    attachmentId: shippingData
                    address:
                      addressType: residential
                      receiverName: Marcelo
                      addressId: 49ad09e5fba8434a8ff1e0faa4b60ceb
                      postalCode: '28050987'
                      city: Rio de Janeiro
                      state: RJ
                      country: BRA
                      street: Rua da minha casa
                      number: '123'
                      neighborhood: Copacabana
                      complement: 15º andar
                      reference: null
                      geoCoordinates: []
                    logisticsInfo:
                    - itemIndex: 0
                      selectedSla: Normal
                      slas:
                      - id: n2_2
                        name: n2_2
                        deliveryIds:
                        - courierId: 1de4790
                          warehouseId: '1_1'
                          dockId: N2
                          courierName: N2_2
                          quantity: 1
                        shippingEstimate: 6bd
                        shippingEstimateDate: null
                        lockTTL: 7d
                        availableDeliveryWindows:
                        - startDateUtc: '2017-03-27T00:00:00+00:00'
                          endDateUtc: '2017-03-27T00:00:00+00:00'
                          price: 0
                          lisPrice: 0
                          tax: 0
                        - startDateUtc: '2017-03-28T00:00:00+00:00'
                          endDateUtc: '2017-03-28T00:00:00+00:00'
                          price: 0
                          lisPrice: 0
                          tax: 0
                        deliveryWindow: null
                        price: 650
                        listPrice: 650
                        tax: 0
                        pickupStoreInfo:
                          isPickupStore: false
                          friendlyName: null
                          address: null
                          additionalInfo: null
                          dockId: null
                      - id: Normal
                        name: Normal
                        deliveryIds:
                        - courierId: 2p1t
                          warehouseId: '1_1'
                          dockId: N2
                          courierName: Post_Test_2
                          quantity: 1
                        shippingEstimate: 6bd
                        shippingEstimateDate: null
                        lockTTL: 7d
                        availableDeliveryWindows: []
                        deliveryWindow: null
                        price: 650
                        listPrice: 650
                        tax: 0
                        pickupStoreInfo:
                          isPickupStore: false
                          friendlyName: null
                          address: null
                          additionalInfo: null
                          dockId: null
                      - id: P_T
                        name: P_T
                        deliveryIds:
                        - courierId: 1p1t
                          warehouseId: '1_1'
                          dockId: N2
                          courierName: Post_Teste
                          quantity: 1
                        shippingEstimate: 6bd
                        shippingEstimateDate: null
                        lockTTL: 7d
                        availableDeliveryWindows: []
                        deliveryWindow: null
                        price: 1462
                        listPrice: 1462
                        tax: 0
                        pickupStoreInfo:
                          isPickupStore: false
                          friendlyName: null
                          address: null
                          additionalInfo: null
                          dockId: null
                      - id: Econômica
                        name: Econômica
                        deliveryIds:
                        - courierId: 2B9C2C7D-7A76-485D-94EF-701D041E448C
                          warehouseId: '1_1'
                          dockId: '1_1_1'
                          courierName: 'Leve 30kg (De: 10000-000 Até: 25999-999) '
                          quantity: 1
                        shippingEstimate: 20bd
                        shippingEstimateDate: null
                        lockTTL: 7d
                        availableDeliveryWindows: []
                        deliveryWindow: null
                        price: 2265
                        listPrice: 2265
                        tax: 0
                        pickupStoreInfo:
                          isPickupStore: false
                          friendlyName: null
                          address: null
                          additionalInfo: null
                          dockId: null
                      shipsTo:
                      - BRA
                      itemId: '2000016'
                    availableAddresses:
                    - addressType: residential
                      receiverName: Marcelo
                      addressId: 49ad09e5fba8434a8ff1e0faa4b60ceb
                      postalCode: '28050642'
                      city: Rio de Janeiro
                      state: RJ
                      country: BRA
                      street: Rua da minha casa
                      number: '123'
                      neighborhood: Copacabana
                      complement: 15º andar
                      reference: null
                      geoCoordinates: []
                  paymentData:
                    attachmentId: paymentData
                    transactionId: 62FEDE228E2144649CF67812C4E5DD87
                    payments:
                    - paymentSystem: 6
                      bin: null
                      accountId: '12'
                      tokenId: null
                      value: 34390
                      referenceValue: 34390
                      giftCardRedemptionCode: null
                      giftCardProvider: null
                      giftCardId: null
                    giftCards: []
                    transactions:
                    - isActive: true
                      transactionId: 62FEDE228E2144649CF67812C4E5DD87
                      merchantName: STORE
                      payments:
                      - paymentSystem: 6
                        bin: null
                        accountId: '12'
                        tokenId: null
                        value: 34390
                        referenceValue: 34390
                        giftCardRedemptionCode: null
                        giftCardProvider: null
                        giftCardId: null
                    merchantName: STORE
                  clientPreferencesData:
                    attachmentId: clientPreferencesData
                    locale: pt-BR
                    optinNewsLetter: true
                  giftRegistryData: null
                  marketingData: null
                  storePreferencesData:
                    countryCode: BRA
                    checkToSavePersonDataByDefault: false
                    templateOptions:
                      toggleCorporate: false
                    timeZone: E. South America Standard Time
                    currencyCode: BRL
                    currencyLocale: 1046
                    currencySymbol: R$
                    currencyFormatInfo:
                      currencyDecimalDigits: 2
                      currencyDecimalSeparator: ','
                      currencyGroupSeparator: .
                      currencyGroupSize: 3
                      startsWithCurrencySymbol: true
                  openTextField:
                    attachmentId: openTextField
                    value: null
                  changeData: null
                  salesChannel: '1'
                  followUpEmail: f1e7309d88dd4633825ce183d52a50a6@ct.vtex.com.br
                  creationDate: '2017-02-16T23:42:43.9605088Z'
                  lastChange: '2017-02-16T23:42:47.62285Z'
                  timeZoneCreationDate: '2017-02-16T21:42:43.9605088'
                  timeZoneLastChange: '2017-02-16T21:42:47.62285'
                  isCompleted: false
                  hostName: ambienteqa
                  merchantName: null
                  userType: User type
                  roundingError: 0
      deprecated: false
  /api/checkout/pub/orders:
    put:
      tags:
      - Order Placement
      summary: VTex Place order
      description: "Places order without having any prior cart information. This means all information on items, client, payment and shipping must be sent in the body.\r\n\r\n>⚠️ The authentication of this endpoint is required if you are creating an order with an item that has an attachment that creates a Subscription. For more information, access [Subscriptions API](https://developers.vtex.com/docs/api-reference/subscriptions-api-v3).\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 | **Orders Full Access** |\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: PlaceOrder
      parameters:
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/Accept'
      - name: sc
        in: query
        description: Trade Policy (Sales Channel) identification. This query can be used to create an order for a specific sales channel.
        required: false
        style: form
        schema:
          type: integer
          example: 1
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - items
              - clientProfileData
              - shippingData
              - paymentData
              properties:
                items:
                  type: array
                  description: Array of objects containing information on each of the order's items.
                  items:
                    type: object
                    required:
                    - id
                    - quantity
                    - seller
                    properties:
                      id:
                        type: string
                        description: The SKU ID.
                        example: '123'
                      quantity:
                        type: integer
                        format: int32
                        description: The quantity of items of this specific SKU in the cart to be simulated.
                        example: 1
                      seller:
                        type: string
                        description: The ID of the seller responsible for this SKU. This ID can be found in your VTEX Admin.
                        example: '1'
                      commission:
                        type: integer
                        description: Comission.
                        example: 10
                      freightCommission:
                        type: integer
                        description: Freight comission
                        example: 10
                      price:
                        type: integer
                        description: Item price within the context of the order without separating cents. For example, $24.99 is represented `2499`.
                        example: 2499
                      bundleItems:
                        type: array
                        description: 'Information on services sold along with the SKU. Example: a gift package.'
                        items:
                          type: object
                          properties:
                            type:
                              type: string
                              description: Service type.
                              example: type-example
                            id:
                              type: string
                              description: Service identifier.
                              example: id-example
                            name:
                              type: string
                              description: Service name.
                              example: name-example
                            price:
                              type: integer
                              description: Service price. The last two digits are the cents.
                              example: 199
                      itemAttachment:
                        type: object
                        description: Item attachment.
                        properties:
                          name:
                            type: string
                            description: Attachment name.
                            example: name-example
                          content:
                            type: string
                            description: Content referring to the customization requested by the customer.
                            example: content-example
                      attachments:
                        type: array
                        description: Array containing information on attachments.
                        items:
                          type: string
                      priceTags:
                        type: array
                        description: Array of price tags, each of which, modifies the price in some way, like discounts or rates that apply to the item in the context of the order.
                        items:
                          type: object
                          properties:
                            identifier:
                              type: string
                              description: Price tag identifier.
                              example: 1234abc-5678b-1234c
                            isPercentual:
                              type: boolean
                              description: '`true` if price tag value is applied through a percentage.'
                              example: false
                            name:
                              type: string
                              description: Price tag name.
                              example: discount@name-1234abc-5678b-1234c
                            rawValue:
                              type: integer
                              description: Price tag raw value.
                              example: -12
                            value:
                              type: integer
                              description: Price tag value.
                              example: -1200
                      measurementUnit:
                        type: string
                        description: SKU measurement unit.
                        example: g
                      unitMultiplier:
                        type: integer
                        description: SKU unit multiplier.
                        example: 1
                      isGift:
                        type: boolean
                        description: Indicates whether the order is a gift.
                        example: false
                    example:
                      id: '123456789'
                      quantity: 1
                      seller: '1'
                clientProfileData:
                  type: object
                  description: "Customer's profile information. The `email` functions as a customer's ID.\n\r\n\rFor customers already in your database, sending only the email address is enough to register the order to the shopper’s existing account.\n\r\n\r> If the shopper exists in you database but is not logged in, sending other profile information along with the email will cause the platform to fail placing the order. This happens because this action is interpreted as an attempt to edit profile data, which is not possible unless the customer is logged in to the store."
                  required:
                  - email
                  nullable: true
                  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: '`true` if the customer is a legal entity.'
                      example: false
                shippingData:
                  type: object
                  description: Shipping information.
                  nullable: true
                  properties:
                    address:
                      type: object
                      description: "Shipping address.\n\r\n\rFor customers already in your data base, it is enough to send this object only with an `addressId`, which you may obtain from a [Cart simulation request](https://developers.vtex.com/vtex-rest-api/reference/shopping-cart#cartsimulation), for example."
                      nullable: true
                      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: Home
                          nullable: true
                        postalCode:
                  

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