VTEX Marketplace Protocol - External Seller Marketplace API

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)."
  version: '1.0'
servers:
  - url: https://{marketplaceServicesEndpoint}
    description: Marketplace Service Endpoint
    variables:
      marketplaceServicesEndpoint:
        description: This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).
        default: '{marketplaceServicesEndpoint}'
paths:
  /pvt/orders/{marketplaceOrderId}/invoice:
    post:
      tags:
        - External Seller
      summary: VTex Send invoice
      description: "This request is sent by the external seller to the VTEX marketplace to send invoice information.\n\nThis can be necessary in a regular order or in the case of a return. The `type` field is used to indicate which of these is the case.\r\n\r\n## Permissions\r\n\r\nCheck with your service provider to know what permissions are needed."
      operationId: send-invoice
      parameters:
        - $ref: '#/components/parameters/Accept'
        - $ref: '#/components/parameters/Content-Type'
        - $ref: '#/components/parameters/marketplaceOrderId'
        - $ref: '#/components/parameters/marketplaceServicesEndpoint'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/requestSendInvoice'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responseFulfill'
              example:
                date: '2021-06-09T15:22:56.7612218-02:00'
                orderId: 1138342255777-01
                receipt: 527b1ae251264ef1b7a9b597cd8f16b9
      deprecated: false
  /pvt/orders/{marketplaceOrderId}/invoice/{invoiceNumber}:
    post:
      tags:
        - External Seller
      summary: VTex Send tracking information
      description: "This request is sent by the external seller to the VTEX marketplace to add tracking information to a given order's invoice, in case it is necessary to do so after the invoice has been sent.\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| OMS | OMS access | **Notify invoice** |\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| Allows you to report invoices (NF) and tracking data | Notify invoice |\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: send-tracking-information
      parameters:
        - $ref: '#/components/parameters/marketplaceServicesEndpoint'
        - $ref: '#/components/parameters/marketplaceOrderId'
        - $ref: '#/components/parameters/invoiceNumber'
        - $ref: '#/components/parameters/Accept'
        - $ref: '#/components/parameters/Content-Type'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/requestSendTracking'
            example:
              courier: courier-example
              trackingNumber: 12345678abc
              trackingUrl: https://courier-example.com/tracking
              dispatchedDate: '2021-06-09'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responseFulfill'
              example:
                date: '2021-06-09T15:22:56.7612218-02:00'
                orderId: 1138342255777-01
                receipt: 527b1ae251264ef1b7a9b597cd8f16b9
      deprecated: false
  /pvt/orders/{marketplaceOrderId}/invoice/{invoiceNumber}/tracking:
    post:
      tags:
        - External Seller
      summary: VTex Update tracking status
      description: "This request is sent by the external seller to the VTEX marketplace to update a given order's tracking status.\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| OMS | OMS access | **Notify invoice** |\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| Allows you to report invoices (NF) and tracking data | Notify invoice |\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: update-tracking-status
      parameters:
        - $ref: '#/components/parameters/marketplaceServicesEndpoint'
        - $ref: '#/components/parameters/marketplaceOrderId'
        - $ref: '#/components/parameters/invoiceNumber'
        - $ref: '#/components/parameters/Accept'
        - $ref: '#/components/parameters/Content-Type'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/requestUpdateTrackingStatus'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responseFulfill'
              example:
                date: '2021-06-09T15:22:56.7612218-02:00'
                orderId: 1138342255777-01
                receipt: 527b1ae251264ef1b7a9b597cd8f16b9
      deprecated: false
  /pvt/orders/{marketplaceOrderId}/cancel:
    post:
      tags:
        - External Seller
      summary: VTex Cancel order in marketplace
      description: "This request is sent by the external seller to the VTEX marketplace to cancel an order.\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| Cancel Orders | 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: cancel-order-in-marketplace
      parameters:
        - $ref: '#/components/parameters/marketplaceServicesEndpoint'
        - $ref: '#/components/parameters/marketplaceOrderId'
        - $ref: '#/components/parameters/Accept'
        - $ref: '#/components/parameters/Content-Type'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/requestCancelOrderMarketplace'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/responseFulfill'
              example:
                date: '2021-06-09T15:22:56.7612218-02:00'
                orderId: 1138342255777-01
                receipt: 527b1ae251264ef1b7a9b597cd8f16b9
      deprecated: false
security:
  - appKey: []
    appToken: []
  - VtexIdclientAutCookie: []
components:
  securitySchemes:
    appKey:
      type: apiKey
      in: header
      name: X-VTEX-API-AppKey
      description: Unique identifier of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys).
    appToken:
      type: apiKey
      in: header
      name: X-VTEX-API-AppToken
      description: Secret token of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys).
    VtexIdclientAutCookie:
      type: apiKey
      in: header
      name: VtexIdclientAutCookie
      description: '[User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours.'
  parameters:
    Content-Type:
      name: Content-Type
      in: header
      description: Type of the content being sent.
      required: true
      style: simple
      schema:
        type: string
        default: application/json
    Accept:
      name: Accept
      in: header
      description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
      required: true
      style: simple
      schema:
        type: string
        default: application/json
    marketplaceServicesEndpoint:
      name: marketplaceServicesEndpoint
      in: path
      description: This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/vtex-rest-api/reference/external-seller#order-placement).
      required: true
      style: simple
      schema:
        type: string
        example: marketplaceservicesendpoint.myvtex.com
    marketplaceOrderId:
      name: marketplaceOrderId
      in: path
      description: Identifies the order in the marketplace.
      required: true
      style: simple
      schema:
        type: string
        example: 1138342255777-01
    invoiceNumber:
      name: invoiceNumber
      in: path
      description: Invoice number.
      required: true
      style: simple
      schema:
        type: string
        example: NFe-00002
  schemas:
    requestSendInvoice:
      type: object
      description: Object used to send invoice information related to an order.
      required:
        - type
        - invoiceNumber
        - items
      properties:
        type:
          type: string
          description: Indicates the type of the invoice. Use `"Output"` for regular orders and `"Input"` for returns.
          example: Output
        invoiceNumber:
          type: string
          description: Invoice number.
          example: NFe-00002
        courier:
          type: string
          description: Courier, if available on invoice.
          example: courier-example
        trackingNumber:
          type: string
          description: Tracking number.
          example: 12345678abc
        trackingUrl:
          type: string
          description: Tracking URL.
          example: https://courier-example.com/tracking
        items:
          type: array
          description: Array containing the order items.
          items:
            type: object
            description: Specification data for each order item.
            required:
              - id
              - quantity
              - price
            properties:
              id:
                type: string
                description: SKU ID.
                example: '6'
              quantity:
                type: integer
                description: Quantity of items of the SKU in the cart.
                example: 1
              price:
                type: integer
                description: Price of the item.
                example: 5500
        issuanceDate:
          type: string
          description: Issuance date.
          example: '2021-05-21T10:00:00'
        invoiceValue:
          type: integer
          description: Invoice value.
          example: 6000
    responseFulfill:
      properties:
        date:
          type: string
          description: Request processing date and time.
        orderId:
          type: string
          description: Order ID referring to the Invoice number sent.
        receipt:
          type: string
          description: Requisition receipt code.
      example:
        date: '2021-06-09T15:22:56.7612218-02:00'
        orderId: 1138342255777-01
        receipt: 527b1ae251264ef1b7a9b597cd8f16b9
    requestSendTracking:
      required:
        - courier
        - trackingNumber
        - trackingUrl
        - dispatchedDate
      properties:
        courier:
          type: string
          description: Courier.
          example: courier-example
        trackingNumber:
          type: string
          description: Tracking number.
          example: 12345678abc
        trackingUrl:
          type: string
          description: Tracking URL.
          example: https://courier-example.com/tracking
        dispatchedDate:
          type: string
          description: Date of order dispatch.
          example: '2021-06-09'
    requestUpdateTrackingStatus:
      type: object
      description: Request body object used to update the tracking status of an order.
      required:
        - isDelivered
      properties:
        isDelivered:
          type: boolean
          description: Indicates if order has been delivered. `false` if it is in transit.
          example: true
        events:
          type: array
          description: Array containing information on each tracking event received.
          items:
            type: object
            description: Description of tracking event fields.
            properties:
              city:
                type: string
                description: City where the event ocurred.
                example: Rio de Janeiro
              state:
                type: string
                description: State where the event ocurred.
                example: Rio de Janeiro
              description:
                type: string
                description: Description of the event.
                example: Order delivered.
              date:
                type: string
                description: Date when event ocurred.
                example: '2021-03-16'
    requestCancelOrderMarketplace:
      type: object
      description: Object used to request the cancellation of an order on the marketplace.
      required:
        - reason
      properties:
        reason:
          type: string
          description: Insert here the reason for the order's cancellation.
          example: Product is unavailable.
tags:
  - name: External Seller