VTEX Marketplace Protocol - External Seller Fulfillment API

The VTEX Marketplace Protocol External Seller Fulfillment API defines endpoints that external sellers must implement to receive and fulfill orders from VTEX marketplaces. It covers order notification, fulfillment status updates, and delivery tracking callbacks.

OpenAPI Specification

vtex-marketplace-protocol-external-seller-fulfillment-openapi-original.yml Raw ↑
openapi: 3.0.0
info:
  title: VTex Marketplace Protocol
  description: "The _Marketplace Protocol_ is a set of API requests and definitions to help you integrate external sellers into a VTEX marketplace as well as external marketplaces into VTEX sellers.\r\n\r\n## External Seller\r\n\r\nHere you will find the endpoints involved in the integration between a VTEX marketplace and an external seller. Note that some of these requests are typically sent by the seller while others are received.\r\n\r\n| **Request** | **From** | **To** |\r\n|-|-|-|\r\n| [Fulfillment simulation](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orderForms/simulation) | Marketplace | Seller |\r\n| [Order placement](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orders) | Marketplace | Seller |\r\n| [Authorize fulfillment](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orders/-sellerOrderId-/fulfill) | Marketplace | Seller |\r\n| [Marketplace order cancellation](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orders/-orderId-/cancel) | Marketplace | Seller |\r\n| [Send invoice](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/invoice) | Seller | Marketplace |\r\n| [Send tracking information](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/invoice/-invoiceNumber-) | Seller      | Marketplace |\r\n| [Update tracking status](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/invoice/-invoiceNumber-/tracking) | Seller | Marketplace |\r\n| [Cancel order in marketplace](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/cancel) | Seller | Marketplace |\r\n\r\nFor a detailed explanation of the steps required to develop a custom connector to sell products from an external seller in your storefront, check out our complete [External Seller Integration Guide](https://developers.vtex.com/docs/guides/external-seller-integration-guide).\r\n\r\n\r\n## External Marketplace\r\n\r\nIn this section, you will find the endpoints involved in the VTEX integration between an external marketplace and a VTEX seller.\r\n\r\n\r\n| **Request** | **From** | **To** |\r\n|-|-|-|\r\n| [VTEX Mapper Registration](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-mapper#post-/api/mkp-category-mapper/connector/register) | External marketplace | VTEX system |\r\n| [Send Category Mapping to VTEX Mapper](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-mapper#post-/api/mkp-category-mapper/categories/marketplace/-id-) |  External marketplace | VTEX system |\r\n| [New Order Integration](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/order-integration/orders) | External marketplace | VTEX system |\r\n| [Update Order Status](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#put-/api/order-integration/orders/status) | External marketplace | VTEX system |\r\n| [Fulfillment simulation - External Marketplace](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/checkout/pub/orderForms/simulation) | External marketplace | VTEX system |\r\n| [Place fulfillment order](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/fulfillment/pvt/orders)   | External marketplace | VTEX Seller |\r\n| [Authorize dispatch for fulfillment order](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/fulfillment/pvt/orders/-orderId-/fulfill) | External marketplace | VTEX Seller |\r\n\r\n\r\nFor a detailed explanation of the steps required to develop a custom connector to become an external
    marketplace for VTEX sellers, check out our complete [External Marketplace Integration Guide](https://developers.vtex.com/docs/guides/external-marketplace-integration-guide)."
  contact: {}
  version: '1.0'
servers:
  - url: https://{fulfillmentEndpoint}
    description: Fulfillment Endpoint.
    variables:
      fulfillmentEndpoint:
        description: This is the fulfillment endpoint registered for each specific external seller in the **seller management** section of VTEX's admin panel.
        default: '{fulfillmentEndpoint}'
paths:
  /pvt/orderForms/simulation:
    post:
      tags:
        - External Seller
      summary: VTex Fulfillment simulation - External Seller
      description: "This endpoint may be called upon by VTEX for fulfillment simulation in the external seller different contexts. See examples below.\n\nWhen a [price](https://developers.vtex.com/docs/api-reference/marketplace-apis#post-/notificator/-sellerId-/changenotification/-skuId-/price) or [inventory](https://developers.vtex.com/docs/api-reference/marketplace-apis#post-/notificator/-sellerId-/changenotification/-skuId-/inventory) notification request returns a response with status `200 OK`, it means that the SKU already exists in the marketplace. Whenever this happens, the marketplace will call the seller to get two updated information about the SKU: Price and Inventory.\n\nThe seller needs to have an endpoint implemented in order to receive this call and send a response containing the requested information to the marketplace. We call it the Fulfillment Simulation endpoint.\n\nIf the seller wishes to include other parameters in this call (like account name, or [sales channel](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV) ID), this should be done within their {fulfillmentEndpoint}. This path is then inserted in the marketplace's VTEX admin when [configuring a seller](https://help.vtex.com/en/tutorial/configurando-seller--tutorials_392). \n\nThe marketplace will send an object containing an array of items. The seller must use this list to get the updated information about the referred SKUs and send them back to the marketplace, following the response format explained in the API Reference. \n\nThis call is also applied in the Storefront simulation scenario, in which case the request from VTEX does not send the parameters `country` and `postalCode`. \nThe call's payload can be adapted into two scenarios: \n\n- **Displaying items in the storefront**: the address information can be nulled in the request since they are not mandatory data for this context.   \n- **Making a shopping cart simulation during checkout**: address information must be sent since this data is needed to calculate freight values. If the address information (including `postalCode` and `country`) is not sent through the call, VTEX interprets the stock balance as zero. Without a valid stock balance, the seller will not be shown as an option during checkout. \n  \n## Request body example - Indexing simulation\n\n```\n{\n    \"items\": [\n      {\n        \"id\": \"7908010136043\",\n        \"quantity\": 1,\n        \"seller\": \"1\",\n      }\n    ],\n    \"isCheckedIn\": false,\n  }\n``` \n## Request body example - Checkout simulation\n\n```\n{\n    \"items\": [\n      {\n        \"id\": \"7908010136043\",\n        \"quantity\": 1,\n        \"seller\": \"1\",\n      }\n    ],\n    \"postalCode\": \"22270-030\",\n    \"country\": \"BRA\",\n  }\n```\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed."
      operationId: fulfillment-simulation
      parameters:
        - $ref: '#/components/parameters/fulfillmentEndpoint'
        - $ref: '#/components/parameters/Accept'
        - $ref: '#/components/parameters/Content-Type'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/requestFulfillmentSimulation'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responseFulfillmentSimulation'
              example:
                country: BRA
                items:
                  - id: '2000037'
                    listPrice: 67203
                    measurementUnit: un
                    merchantName: mySeller1
                    offerings:
                      - type: Warranty
                        id: '5'
                        name: 1 year warranty
                        price: 10000
                    price: 67203
                    priceTags: []
                    priceValidUntil: '2014-03-01T22:58:28.143'
                    quantity: 1
                    requestIndex: 0
                    seller: '1'
                    unitMultiplier: 1
                logisticsInfo:
                  - itemIndex: 0
                    quantity: 1
                    shipsTo:
                      - BRA
                    slas:
                      - id: Curbside pickup
                        deliveryChannel: pickup-in-point
                        name: Curbside pickup
                        shippingEstimate: 0bd
                        price: 0
                        availableDeliveryWindows:
                          - startDateUtc: '2013-02-04T08:00:00+00:00'
                            endDateUtc: '2013-02-04T13:00:00+00:00'
                            price: 0
                        pickupStoreInfo:
                          isPickupStore: true
                          friendlyName: Santa Felicidade
                          address:
                            addressType: pickup
                            receiverName: Juliana
                            addressId: 548304ed-dd40-4416-b12b-4b32bfa7b1e0
                            postalCode: 82320-040
                            city: Curitiba
                            state: PR
                            country: BRA
                            street: Rua Domingos Strapasson
                            number: '100'
                            neighborhood: Santa Felicidade
                            complement: Loja 10
                            reference: Next to the unicorn statue
                            geoCoordinates:
                              - 49.334934
                              - 25.401705
                          additionalInfo: ''
                    stockBalance: 199
                    deliveryChannels:
                      - id: delivery
                        stockBalance: 179
                      - id: pickup-in-point
                        stockBalance: 20
                postalCode: '80250000'
                allowMultipleDeliveries: true
      deprecated: false
  /pvt/orders:
    post:
      tags:
        - External Seller
      summary: VTex Order placement
      description: "This request is sent by VTEX to the external seller once the customer finishes their checkout, to let the seller know there is a newly placed order. It does that by calling the **Order Placement** endpoint, which needs to be implemented by the seller.\n\nThe marketplace will send information such as the items contained in the cart, the client’s profile data, the shipping data, and the payment data. With all that, the seller will be able to create the order in their store.\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| VTEX Fulfilment | Fulfilment Resources | **Place Orders** |\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| Create orders | Place Orders |\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: order-placement
      parameters:
        - $ref: '#/components/parameters/fulfillmentEndpoint'
        - $ref: '#/components/parameters/content-length'
        - $ref: '#/components/parameters/authorization'
        - $ref: '#/components/parameters/Accept'
        - $ref: '#/components/parameters/accept-enconding'
        - $ref: '#/components/parameters/vtexOperationID'
        - $ref: '#/components/parameters/forwardedProto'
        - $ref: '#/components/parameters/forwardedFor'
        - $ref: '#/components/parameters/vtexCacheClientBypass'
        - $ref: '#/components/parameters/Content-Type'
        - $ref: '#/components/parameters/traceparent'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/orderPlacement'
            example:
              marketplaceOrderId: 1138342255777-01
              marketplaceServicesEndpoint: https://marketplaceservicesendpoint.myvtex.com/
              marketplacePaymentValue: 2499
              items:
                - id: 123456789abc
                  quantity: 1
                  seller: seller-example
                  commission: 0
                  freightCommission: 0
                  price: 2499
                  bundleItems:
                    - id: 12
                      quantity: 2
                    - id: 5
                      quantity: 1
                  itemsAttachment:
                    - id: attachment-1
                      name: Product Manual
                      url: https://example.com/manual.pdf
                  attachments:
                    - id: attachment-2
                      name: Product Image
                      url: https://example.com/image.jpg
                  priceTags:
                    - identifier: 1234abc-5678b-1234c
                      isPercentual: false
                      name: discount@name-1234abc-5678b-1234c
                      rawValue: 12
                      value: 1200
                  measurementUnit: g
                  unitMultiplier: 1
                  isGift: false
              paymentData:
              clientProfileData:
                email: [email protected]
                firstName: first-name
                lastName: last-name
                documentType: cpf
                document: '123456789'
                phone: '+55110988887777'
                corporateName:
                tradeName:
                corporateDocument:
                stateInscription:
                corporatePhone:
                isCorporate: false
              shippingData:
                address:
                  addressType: residential
                  receiverName: receiver-name
                  addressId: Home
                  postalCode: 12345-000
                  city: Rio de Janeiro
                  state: Rio de Janeiro
                  country: BRA
                  street: Praia de Botafogo
                  number: '300'
                  neighborhood: Botafogo
                  complement: 3rd floor
                  reference: Grey building
                  geoCoordinates:
                    - '49.334934'
                    - '25.401705'
                logisticsInfo:
                  - itemIndex: 0
                    selectedSla: Express
                    lockTTL: 8d
                    shippingEstimate: 7d
                    price: 1099
                    deliveryWindow:
                      startDateUtc: '2016-04-20T08:00:00+00:00'
                      endDateUtc: '2016-04-20T12:00:00+00:00'
                      listPrice: 10
                updateStatus: updated
              marketingData:
                utmSource: Facebook
                utmMedium: CPC
                utmCampaign: Black friday
                utmiPage: utmi_page-example
                utmiPart: utmi_part-exmaple
                utmiCampaign: utmi_campaign-exmaple
              openTextField: open-text-example
        required: true
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responseOrderPlacement'
              example:
                marketplaceOrderId: '959311095'
                orderId: '7890'
                followUpEmail: [email protected]
                items:
                  - id: '2002495'
                    quantity: 1
                    seller: '1'
                    commission: 0
                    freightCommission: 0
                    price: 2499
                    bundleItems: []
                    itemAttachment:
                      name:
                      content: {}
                    attachments: []
                    priceTags: []
                    measurementUnit: g
                    unitMultiplier: 1
                    isGift: false
                clientProfileData:
                  email: [email protected]
                  firstName: John
                  lastName: Smith
                  documentType: taxpayer registration number
                  document: '33333333333'
                  phone: '+55110988887777'
                  corporateName:
                  tradeName:
                  corporateDocument:
                  stateInscription:
                  corporatePhone:
                  isCorporate: false
                  userProfileId:
                shippingData:
                  address:
                    addressType: residencial
                    receiverName: John Smith
                    addressId: Home
                    postalCode: 12345-000
                    city: Rio de Janeiro
                    state: RJ
                    country: BRA
                    street: Praia de Botafogo
                    number: '300'
                    neighborhood: Botafogo
                    complement: 3rd floor
                    reference: Grey building
                    geoCoordinates:
                      - '49.334934'
                      - '25.401705'
                  logisticsInfo:
                    - itemIndex: 0
                      selectedSla: Express
                      lockTTL: 8d
                      shippingEstimate: 7d
                      price: 1099
                      deliveryWindow:
                        startDateUtc: '2016-04-20T08:00:00+00:00'
                        endDateUtc: '2016-04-20T12:00:00+00:00'
                        listPrice: 10
                customData:
                  openTextField:
                  marketingData:
                    utmSource: buscape
                    utmMedium: ''
                    utmCampaign: freeshipping
                    utmiPage: _
                    utmiPart: BuscaFullText
                    utmiCampaign: artscase for iphone 5
                paymentData:
                allowMultipleDeliveries: true
  /pvt/orders/{sellerOrderId}/fulfill:
    post:
      tags:
        - External Seller
      summary: VTex Authorize fulfillment
      description: "This request is sent from VTEX to the seller after the payment is approved, to notify them that the fulfillment process can start.\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed."
      operationId: authorize-fulfillment
      parameters:
        - $ref: '#/components/parameters/fulfillmentEndpoint'
        - $ref: '#/components/parameters/Accept'
        - $ref: '#/components/parameters/Content-Type'
        - $ref: '#/components/parameters/sellerOrderId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/requestOrderId'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/repsonseOrderId'
              example:
                date: '2014-10-06 18:52:00'
                marketplaceOrderId: 1138342255777-01
                orderId: '959311095'
                receipt: e39d05f9-0c54-4469-a626-8bb5cff169f8
  /pvt/orders/{orderId}/cancel:
    post:
      tags:
        - External Seller
      summary: VTex Marketplace order cancellation
      description: "This request may be sent from VTEX to the external seller in case of order cancelation. For that, the seller will need to implement the Marketplace order cancellation endpoint. Whenever this request is received by the seller, the order should be canceled and the fulfillment flow should not proceed. \n\nFor the seller to: \n\n- **Evaluate a cancellation request:** it is possible to send an empty body as a response to the cancellation request, meaning that the seller is evaluating whether to proceed with the cancellation or not. \n\n- **Confirm the cancellation request:** it is possible to confirm the order cancellation by the marketplace by responding to the call with a body including only one information: the `marketplaceOrderId`, which identifies the order in the marketplace. The seller should use this ID to trigger the cancellation of the corresponding order. The seller should then respond with the same `marketplaceOrderId` and also with the `orderId`, which identifies the order in the seller, the date and time of the notification receipt, and a protocol code that confirms the receipt of the request (which may have the value `null`). \n\n- **Refuse a cancellation request:** it is possible to to [send the Invoice](https://developers.vtex.com/vtex-rest-api/reference/external-seller#send-invoice), meaning that the cancellation has been denied, and the flow continues to the [Order Invoicing](https://developers.vtex.com/vtex-rest-api/docs/external-seller-integration-connector#order-invoicing) step, and the ones that follow it. \n\n>⚠️ This call should be made twice: once for the *Evaluate cancellation request* scenario, and a second time to *Confirm cancellation* or *Refuse cancellation*.\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 | **Order Cancellation** |\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| Cancela Pedidos | Order Cancellation |\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: mkp-order-cancellation
      parameters:
        - $ref: '#/components/parameters/fulfillmentEndpoint'
        - $ref: '#/components/parameters/Accept'
        - $ref: '#/components/parameters/Content-Type'
        - $ref: '#/components/parameters/orderId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/requestOrderId'
            example:
              marketplaceOrderId: 1138342255777-01
              marketplaceOrderGroup: group-123
              cancellationRequestId: 85835ab408514b52aa139e4236ce0c33
              cancellationRequestDate: '2024-03-04T15:45:02.1306363+00:00'
              reason: Out of stock
              requestedByUser: true
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/repsonseOrderId'
              example:
                date: '2019-05-09 15:31:23'
                marketplaceOrderId: '959311095'
                orderId: 1138342255777-01
                receipt: e39d05f9-0c54-4469-a626-8bb5cff169f8
security:
  - appKey: []
    appToken: []
components:
  schemas:
    fulfillmentItem:
      description: Details of an item to be fulfilled.
      required:
        - id
        - quantity
        - seller
      type: object
      properties:
        id:
          type: string
          description: SKU ID.
          example: '6'
        quantity:
          type: integer
          description: Quantity of items of the SKU in the cart.
          example: 1
        seller:
          type: string
          description: ID of the seller registered in VTEX.
          example: '01'
    orderPlacement:
      description: Informations related to the placement of an order.
      type: object
      properties:
        marketplaceOrderId:
          type: string
          description: Identifies the order in the marketplace.
          example: 1138342255777-01
        marketplaceServicesEndpoint:
          type: string
          description: Endpoint sent by VTEX to the seller, that will be used to send the invoice and tracking data to the marketplace. This endpoint will also be used in [change order in Multilevel Omnichannel Inventory](https://developers.vtex.com/docs/guides/change-orders-multilevel-omnichannel-inventory-external-marketplaces#implementators) operations in external marketplaces.
          example: https://marketplaceservicesendpoint.myvtex.com/
        marketplacePaymentValue:
          type: integer
          description: Amount that the marketplace agrees to pay to the seller. The last two digits are the cents. For example, $24.99 is represented 2499.
          example: 2499
        items:
          type: array
          description: Array of objects.
          items:
            description: Data about each SKU in the cart.
            type: object
            properties:
              id:
                type: string
                description: SKU ID.
                example: 123456789abc
              quantity:
                type: integer
                description: Quantity of the item.
                example: 1
              seller:
                type: string
                description: ID of the seller registered in VTEX.
                example: seller-example
              commission:
                type: integer
                description: Comission.
                example: 0
              freightCommission:
                type: integer
                description: Freight comission.
                example: 0
              price:
                type: integer
                description: SKU price. The last two digits are the 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:
                  $ref: '#/components/schemas/bundleItemsItem'
              itemsAttachment:
                type: array
                description: Attachments sold with the SKU.
                items:
                  $ref: '#/components/schemas/itemAttachment'
              attachments:
                type: array
                description: Array containing information on attachments.
                items:
                  type: object
                  description: Attachment information.
                  properties:
                    id:
                      type: string
                      description: Unique identifier of the attachment.
                      example: attachment-1
                    name:
                      type: string
                      description: Name of the attachment.
                      example: Product Image
                    url:
                      type: string
                      description: URL of the attachment.
                      example: https://example.com/image.jpg
              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:
                  description: Details of a price tag affecting the item's price.
                  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 value.
                      example: -12
                    value:
                      type: integer
                      description: Price tag raw 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 if the item is a gift (`true`).
                example: true
        paymentData:
          type: object
          description: In other contexts, this field tipically holds an object with payment information. However, since the payment is processed by the marketplace, it will be sent to the seller as `null` in this context.
          nullable: true
          example:
        clientProfileData:
          type: object
          description: Customer's profile information.
          required:
            - email
            - firstName
            - lastName
            - documentType
            - document
            - isCorporate
          properties:
            email:
              type: string
              description: Customer's email address.
              example: [email protected]
            firstName:
              type: string
              description: Customer's first name

# --- truncated at 32 KB (75 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vtex/refs/heads/main/openapi/vtex-marketplace-protocol-external-seller-fulfillment-openapi-original.yml