Marketplace Protocol
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…
Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.
Overview
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.
External Seller
Here 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.
| Request | From | To |
|---|---|---|
| Fulfillment simulation | Marketplace | Seller |
| Order placement | Marketplace | Seller |
| Authorize fulfillment | Marketplace | Seller |
| Marketplace order cancellation | Marketplace | Seller |
| Send invoice | Seller | Marketplace |
| Send tracking information | Seller | Marketplace |
| Update tracking status | Seller | Marketplace |
| Cancel order in marketplace | Seller | Marketplace |
For 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.
External Marketplace
In this section, you will find the endpoints involved in the VTEX integration between an external marketplace and a VTEX seller.
| Request | From | To |
|---|---|---|
| VTEX Mapper Registration | External marketplace | VTEX system |
| Send Category Mapping to VTEX Mapper | External marketplace | VTEX system |
| Authorize fulfillment | Marketplace | Seller |
| Place fulfillment order | External marketplace | VTEX Seller |
| Authorize dispatch for fulfillment order | External marketplace | VTEX Seller |
For 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.
Endpoints 15
External Seller
- POSTFulfillment simulation - External Seller
/:fulfillmentEndpoint/pvt/orderForms/simulationThis endpoint may be called upon by VTEX for fulfillment simulation in the external seller different contexts. See examples below. When a price or inventory… - POSTOrder placement
/:fulfillmentEndpoint/pvt/ordersThis 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… - POSTMarketplace order cancellation
/:fulfillmentEndpoint/pvt/orders/:orderId/cancelThis 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… - POSTAuthorize fulfillment
/:fulfillmentEndpoint/pvt/orders/:sellerOrderId/fulfillThis request is sent from VTEX to the seller after the payment is approved, to notify them that the fulfillment process can start. - POSTCancel order in marketplace
/:marketplaceServicesEndpoint/pvt/orders/:marketplaceOrderId/cancelThis request is sent by the external seller to the VTEX marketplace to cancel an order. - POSTSend invoice
/:marketplaceServicesEndpoint/pvt/orders/:marketplaceOrderId/invoiceThis request is sent by the external seller to the VTEX marketplace to send invoice information. This can be necessary in a regular order or in the case of a… - POSTSend tracking information
/:marketplaceServicesEndpoint/pvt/orders/:marketplaceOrderId/invoice/:invoiceNumberThis 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… - POSTUpdate tracking status
/:marketplaceServicesEndpoint/pvt/orders/:marketplaceOrderId/invoice/:invoiceNumber/trackingThis request is sent by the external seller to the VTEX marketplace to update a given order's tracking status.
External Marketplace
- POSTFulfillment simulation - External Marketplace
/api/checkout/pub/orderForms/simulation?affiliateId=MNF&sc=1This endpoint can be triggered by marketplaces to simulate the fulfillment of an item in the cart. The fulfillment information is useful whenever you need to… - POSTSend Category Mapping to VTEX Mapper
/portal.vtexcommercestable.com.br/api/mkp-category-mapper/categories/marketplace/:idMapping categories guarantees that the VTEX category tree has a correct association with the marketplace’s category tree. To perform this association, VTEX… - POSTVTEX Mapper Registration
/portal.vtexcommercestable.com.br/api/mkp-category-mapper/connector/register?an=accountNameMapping categories guarantees that the VTEX category tree has a correct association with the marketplace’s category tree. To perform this association, VTEX… - POSTNew Order Integration
/:accountName.vtexcommercestable.com.br/api/order-integration/orders?an=apiexamples&affiliateId=MKPAPI to integrate an external channel's order into the VTEX plataform. This process is asynchronous and a notification with the order's integration results… - PUTUpdate Order Status
/:accountName.vtexcommercestable.com.br/api/order-integration/orders/status?an=apiexamplesAPI request used to update an order status in VTEX. This process is asynchronous and a notification with the order's integration results will be sent to the… - POSTPlace fulfillment order
/:accountName.:environment.com.br/api/fulfillment/pvt/orders?sc=1&affiliateId=MKPCreates fulfillment order, meaning that it is an order for the seller's side in a sale made through a marketplace. This order assumes the transaction itself… - POSTAuthorize dispatch for fulfillment order
/:accountName.:environment.com.br/api/fulfillment/pvt/orders/:orderId/fulfill?sc=1&affiliateId=MKPCreates fulfillment order, meaning that it is an order for the seller's side in a sale made through a marketplace. This order assumes the transaction itself…
API details
- Base URL
https://vtex.local- Authentication
- An API key in the X-VTEX-API-AppKey header
An API key in the X-VTEX-API-AppToken header - Operations
- 15 operations on 15 pathsPOST 14PUT 1
- Main resources
- External Seller 8External Marketplace 7
- Response formats
application/json- Description format
- OpenAPI 3.0.0, API version
1.0 - Links
- OpenAPI document
- Listed from
- APIs.guru OpenAPI Directory (CC0-1.0)
Source updated
How to test the Marketplace Protocol in Swastik Codes
- Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
- Fork it into your workspaceChoose a workspace. You get your own copy of the Marketplace Protocol collection, without the publisher's secrets.
- Add your credentialsThis API uses an API key in the X-VTEX-API-AppKey header. Add yours in the collection's variables or an environment; the requests already reference it.
- Send a requestPick an endpoint, for example “Fulfillment simulation - External Seller” (POST /:fulfillmentEndpoint/pvt/orderForms/simulation), and press Send. Check the response, add tests and run the whole collection with the runner.
Frequently asked questions
What is the Marketplace Protocol?
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… It is listed under Other and has 15 endpoints.
Who publishes the Marketplace Protocol?
It is listed from VTEX's public API description (an OpenAPI document), not published by VTEX on Swastik Codes. Anyone who controls vtex.com can claim the profile by adding a DNS TXT record.
What is the base URL of the Marketplace Protocol?
Requests go to https://vtex.local. Endpoint paths are added to this base URL.
How do I authenticate with the Marketplace Protocol?
It accepts 2 methods: an API key in the X-VTEX-API-AppKey header; an API key in the X-VTEX-API-AppToken header.
How many endpoints does the Marketplace Protocol have?
15 operations on 15 paths (14 POST, 1 PUT). The largest groups are External Seller, External Marketplace.
Is forking the Marketplace Protocol free?
Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.