HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.

Accept

Content-Type

invoiceNumber

marketplaceOrderId

This is an endpoint sent from VTEX to the external seller in the [Order placement request](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orders).

marketplaceServicesEndpoint

Object used to request the cancellation of an order on the marketplace.

Insert here the reason for the order's cancellation.

Object used to send invoice information related to an order.

Indicates the type of the invoice. Use `"Output"` for regular orders and `"Input"` for returns.

Request body object used to update the tracking status of an order.

Array containing information on each tracking event received.

Indicates if order has been delivered. `false` if it is in transit.

Order ID referring to the Invoice number sent.

[User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours.

VtexIdclientAutCookie

Unique identifier of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys).

X-VTEX-API-AppKey

Secret token of the [application key](https://developers.vtex.com/docs/guides/api-authentication-using-application-keys).

X-VTEX-API-AppToken

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](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orderForms/simulation) | Marketplace | Seller |
| [Order placement](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orders) | Marketplace | Seller |
| [Authorize fulfillment](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orders/-sellerOrderId-/fulfill) | Marketplace | Seller |
| [Marketplace order cancellation](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orders/-orderId-/cancel) | Marketplace | Seller |
| [Send invoice](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/invoice) | Seller | Marketplace |
| [Send tracking information](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/invoice/-invoiceNumber-) | Seller      | Marketplace |
| [Update tracking status](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/invoice/-invoiceNumber-/tracking) | Seller | Marketplace |
| [Cancel order in marketplace](https://developers.vtex.com/docs/api-reference/marketplace-protocol#post-/pvt/orders/-marketplaceOrderId-/cancel) | 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](https://developers.vtex.com/docs/guides/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](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-mapper#post-/api/mkp-category-mapper/connector/register) | External marketplace | VTEX system |
| [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 |
| [New Order Integration](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/order-integration/orders) | External marketplace | VTEX system |
| [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 |
| [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 |
| [Place fulfillment order](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-marketplace-orders#post-/api/fulfillment/pvt/orders)   | External marketplace | VTEX Seller |
| [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 |


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](https://developers.vtex.com/docs/guides/external-marketplace-integration-guide).

Marketplace Protocol

This request is sent by the external seller to the VTEX marketplace to cancel an order.

## Permissions

Any 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:

| **Product** | **Category** | **Resource** |
| --------------- | ----------------- | ----------------- |
| Checkout | CheckoutResources | **Order Cancellation** |

You 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):

| **Role** | **Resource** | 
| --------------- | ----------------- | 
| Cancel Orders | Order Cancellation |

>❗ 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).

To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).

This 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 return. The `type` field is used to indicate which of these is the case.

## Permissions

Check with your service provider to know what permissions are needed.

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.

## Permissions

Any 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:

| **Product** | **Category** | **Resource** |
| --------------- | ----------------- | ----------------- |
| OMS | OMS access | **Notify invoice** |

You 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):

| **Role** | **Resource** | 
| --------------- | ----------------- | 
| Allows you to report invoices (NF) and tracking data | Notify invoice |

>❗ 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).

To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).

This request is sent by the external seller to the VTEX marketplace to update a given order's tracking status.

## Permissions

Any 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:

| **Product** | **Category** | **Resource** |
| --------------- | ----------------- | ----------------- |
| OMS | OMS access | **Notify invoice** |

You 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):

| **Role** | **Resource** | 
| --------------- | ----------------- | 
| Allows you to report invoices (NF) and tracking data | Notify invoice |

>❗ 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).

To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).

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).

This request is sent by the external seller to the VTEX marketplace to cancel an order.

Cancel order in marketplace

This request is sent by the external seller to the VTEX marketplace to send invoice information.

Send invoice

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.

Send tracking information

This request is sent by the external seller to the VTEX marketplace to update a given order's tracking status.

Update tracking status

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.