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