{
"openapi": "3.0.0",
"info": {
"title": "Marketplace API",
"description": "The **Marketplace API** enables marketplaces and sellers hosted on VTEX to perform their collaborative operations. \r\n\r\n>⚠️ The marketplace must [create an appKey and appToken](https://developers.vtex.com/docs/guides/getting-started-authentication) for each non-VTEX seller that will use this API.\r\n\r\n## Index\r\n\r\n### Notification\r\n\r\nEndpoints used by sellers to notify marketplaces that the price or inventory language has changed for one of their SKUs.\r\n\r\n`POST` [Notify marketplace of price update](https://developers.vtex.com/docs/api-reference/marketplace-apis#post-/notificator/-sellerId-/changenotification/-skuId-/price)\r\n\r\n`POST` [Notify marketplace of inventory update](https://developers.vtex.com/docs/api-reference/marketplace-apis#post-/notificator/-sellerId-/changenotification/-skuId-/inventory)\r\n\r\n\r\n### Suggestions\r\n\r\n#### Get Suggestions\r\n\r\nSearch and filter all suggestions using specific criteria.\r\n\r\n`GET` [Get all SKU Suggestions](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions)\r\n\r\n`GET` [Get SKU Suggestion by ID](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions/-sellerId-/-sellerSkuId-)\r\n\r\n\r\n#### Manage Suggestions\r\n\r\nSend or delete SKU suggestions from the seller to marketplace.\r\n\r\n`PUT` [Send SKU Suggestion](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/-sellerId-/-sellerSkuId-)\r\n\r\n`DELETE` [Delete SKU Suggestion](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#delete-/suggestions/-sellerId-/-sellerSkuId-)\r\n\r\n\r\n#### Get Versions\r\n\r\nSearch and filter all versions of suggestions, using specific criteria.\r\n\r\n`GET` [Get all versions](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions/-sellerId-/-sellerskuid-/versions)\r\n\r\n`GET` [Get version by ID](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions/-sellerId-/-sellerskuid-/versions/-version-)\r\n\r\n\r\n#### Match Received SKUs\r\n\r\nMatch SKU suggestions received in the marketplace.\r\n\r\n`PUT` [Match Received SKUs individually](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/-sellerId-/-sellerskuid-/versions/-version-/matches/-matchid-)\r\n\r\n`PUT` [Match Multiple Received SKUs](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/matches/action/-actionName-)\r\n\r\n\r\n#### SKU Approval Settings\r\n\r\nAllows marketplaces to configure rules for automatically and manually approving SKUs received from sellers.\r\n\r\n`GET`[Get autoApprove Status in Account Settings](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions/configuration/autoapproval/toggle) \r\n\r\n`PUT`[Activate autoApprove in Marketplace's Account](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/configuration/autoapproval/toggle) \r\n\r\n`GET`[Get Account's Approval Settings](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions/configuration)\r\n\r\n`PUT`[Save Account's Approval Settings](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/configuration)\r\n\r\n`GET`[Get Seller's Approval Settings](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#get-/suggestions/configuration/seller/-sellerId-)\r\n\r\n`PUT`[Save Seller's Approval Settings](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/configuration/seller/-sellerId-)\r\n\r\n`PUT`[Activate autoApprove Setting for a Seller](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/configuration/autoapproval/toggle/seller/-sellerId-) \r\n\r\n\r\n### Matched Offers\r\n\r\nOffers are seller products and SKUs that were sent to the marketplace, and already have their price and inventory level configured.\r\n\r\n`GET`[Get Matched Offers List](https://developers.vtex.com/docs/api-reference/marketplace-apis#get-/offer-manager/pvt/offers)\r\n\r\n`GET`[Get Matched Offer's Data by SKU ID](https://developers.vtex.com/docs/api-reference/marketplace-apis#get-/offer-manager/pvt/product/-productId-/sku/-skuId-) \r\n\r\n`GET`[Get Matched Offer's Data by Product ID](https://developers.vtex.com/docs/api-reference/marketplace-apis#get-/offer-manager/pvt/product/-productId-)\r\n",
"version": "1.0"
},
"servers": [
{
"url": "https://{accountName}.{environment}.com.br/api",
"description": "VTEX Server URL.",
"variables": {
"accountName": {
"description": "Name of the VTEX account. Used as part of the URL.",
"default": "apiexamples"
},
"environment": {
"description": "Environment to use. Used as part of the URL.",
"enum": [
"vtexcommercestable"
],
"default": "vtexcommercestable"
}
}
}
],
"paths": {
"/notificator/{sellerId}/changenotification/{skuId}/price": {
"post": {
"tags": [
"Notification"
],
"summary": "Notify marketplace of price update",
"description": "This endpoint is used by *sellers* to notify marketplaces that the price has changed for one of their SKUs. \n\nThere is no request body in this call, indicating the new price value, for instance. It only notifies a specific marketplace (`accountName`) that a seller (`sellerId`) has changed the price of an SKU (`skuId`). \n\n*Marketplaces* will then call the [fulfillment endpoint](https://developers.vtex.com/vtex-rest-api/reference/fulfillment-simulation) provided in the seller registration form to get the updated price information.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [permissions](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#machine-authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.",
"operationId": "PriceNotification",
"parameters": [
{
"$ref": "#/components/parameters/accept"
},
{
"$ref": "#/components/parameters/accountName"
},
{
"$ref": "#/components/parameters/contentType"
},
{
"$ref": "#/components/parameters/environment"
},
{
"$ref": "#/components/parameters/sellerId"
},
{
"$ref": "#/components/parameters/skuId"
}
],
"responses": {
"202": {
"description": "Accepted"
}
},
"deprecated": false
}
},
"/notificator/{sellerId}/changenotification/{skuId}/inventory": {
"post": {
"tags": [
"Notification"
],
"summary": "Notify marketplace of inventory update",
"description": "This endpoint is used by *sellers* to notify marketplaces that the inventory level has changed for one of their SKUs. \n\nThere is no request body in this call, indicating the new inventory level, for instance. It only notifies a specific marketplace (`accountName`) that a seller (`sellerId`) has changed the inventory level of an SKU (`skuId`). \n\n*Marketplaces* will then call the [fulfillment endpoint](https://developers.vtex.com/vtex-rest-api/reference/fulfillment-simulation) provided in the seller registration form to get the updated inventory information.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [permissions](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#machine-authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.",
"operationId": "InventoryNotification",
"parameters": [
{
"$ref": "#/components/parameters/accountName"
},
{
"$ref": "#/components/parameters/environment"
},
{
"$ref": "#/components/parameters/accept"
},
{
"$ref": "#/components/parameters/contentType"
},
{
"$ref": "#/components/parameters/sellerId"
},
{
"$ref": "#/components/parameters/skuId"
}
],
"responses": {
"202": {
"description": "Accepted"
}
},
"deprecated": false
}
},
"/offer-manager/pvt/offers": {
"get": {
"tags": [
"Matched Offers"
],
"summary": "Get Matched Offers List",
"description": "Offers are seller's products and SKUs that were sent to the marketplace, and already have their price and inventory level configured. \n\n This endpoint retrieves the available offers in a marketplace. It differs from the Get Suggestions endpoints, since it retrieves products that were already matched by the marketplace, and are currently in its catalog. \n\nIt is possible to filter the search through the following parameters: \n\n- rows \n- sort \n\n- start \n\n- fq\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [permissions](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#machine-authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.",
"operationId": "Getofferslist",
"parameters": [
{
"$ref": "#/components/parameters/sort"
},
{
"$ref": "#/components/parameters/rows"
},
{
"$ref": "#/components/parameters/start"
},
{
"$ref": "#/components/parameters/fq"
},
{
"$ref": "#/components/parameters/accountName"
},
{
"$ref": "#/components/parameters/contentType"
},
{
"$ref": "#/components/parameters/environment"
},
{
"$ref": "#/components/parameters/accept"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/responseGetMatchedOffersList"
},
"example": [
{
"LastModified": "2021-05-06T21:37:24.262529",
"ProductId": "941947",
"CategoryId": 1563,
"BrandId": 2004291,
"ProductName": "Produto Teste 04 - Preto - 40",
"Skus": [
{
"SkuId": "1070268",
"EanId": null,
"RefId": null,
"NameComplete": "Produto Teste 04 - Preto - 40 Cor:Preto",
"Name": "Cor:Preto",
"IsActive": true,
"MainImage": {
"ImageId": "53878805",
"ImageLabel": null,
"ImageTag": "![\"image-8b4364782e664d76a6ebc8702008e478\"](\"~/arquivos/ids/53878805-#width#-#height#/image-8b4364782e664d76a6ebc8702008e478.jpg\")
",
"ImagePath": "~/arquivos/ids/53878805-#width#-#height#/image-8b4364782e664d76a6ebc8702008e478.jpg",
"IsMain": true,
"IsZoomSize": true,
"ImageText": "image-8b4364782e664d76a6ebc8702008e478",
"LastModified": "2021-04-06T03:01:30.747"
},
"Offers": [
{
"SellerId": "1",
"SellerSkuId": "1070268",
"OffersPerSalesChannel": [
{
"SaleChannel": 1,
"Price": 0,
"ListPrice": 0,
"PriceWithoutDiscount": 0,
"AvailableQuantity": 0
}
],
"AvailableSalesChannels": null
},
{
"SellerId": "madesacms",
"SellerSkuId": "3298",
"OffersPerSalesChannel": [
{
"SaleChannel": 0,
"Price": 1200,
"ListPrice": 1200,
"PriceWithoutDiscount": 1200,
"AvailableQuantity": 10000000
}
],
"AvailableSalesChannels": null
}
]
}
]
}
]
}
}
}
},
"deprecated": false
}
},
"/offer-manager/pvt/product/{productId}/sku/{skuId}": {
"get": {
"tags": [
"Matched Offers"
],
"summary": "Get Matched Offer's Data by SKU ID",
"description": "Offers are seller products and SKUs that were sent to the marketplace, and already have their price and inventory level configured. \n\nThis endpoint retrieves the available offers for a speciic SKU ID in the marketplace's catalog. It differs from the Get Suggestions endpoints, since it retrieves products that were already matched by the marketplace operator, and are currently active in its catalog. \n\nThe call returns a list of offers for that ID, that contain the following data: \n\n- Seller that sells the SKU \n\n- Correspondent SKU ID \n\n- SKU's price value \n\n- Inventory level \n\n- Sales channel (or [trade policy](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV#master-data)) that it is available at.",
"operationId": "GetSKUoffers",
"parameters": [
{
"$ref": "#/components/parameters/accountName"
},
{
"$ref": "#/components/parameters/environment"
},
{
"$ref": "#/components/parameters/contentType"
},
{
"$ref": "#/components/parameters/accept"
},
{
"$ref": "#/components/parameters/productId"
},
{
"$ref": "#/components/parameters/skuId"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/responseGetMatchedOffersDataBySKU"
},
"example": [
{
"productId": "1561208",
"skuId": "1559161",
"nameComplete": "Blusa Cardigan Manga Longa Vestem - Feminina - CINZA G",
"mainImage": {
"imagePath": "~/arquivos/ids/8567753-#width#-#height#/image-05b40d3167b5b7ed42285124f6862f12.jpg"
},
"sellersOffers": [
{
"sellerId": "1",
"sellerSkuId": "1559161",
"salesChannelOffer": [
{
"salesChannelId": "1",
"salesChannelName": "Principal",
"price": 49.99,
"listPrice": 59.99,
"priceWithoutDiscount": 49.99,
"availableQuantity": 8
},
{
"salesChannelId": "2",
"salesChannelName": "Online Store",
"price": 47.99,
"listPrice": 59.99,
"priceWithoutDiscount": 47.99,
"availableQuantity": 12
}
]
}
]
}
]
}
}
}
},
"deprecated": false
}
},
"/offer-manager/pvt/product/{productId}": {
"get": {
"tags": [
"Matched Offers"
],
"summary": "Get Matched Offer's Data by Product ID",
"description": "Offers are seller products and SKUs that were sent to the marketplace, and already have their price and inventory level configured. \n\nThis endpoint retrieves the available offers for a speciic Product ID in the marketplace's catalog. It differs from the Get Suggestions endpoints, since it retrieves products that were already matched by the marketplace operator, and are currently active in its catalog. \n\nThe call returns a list of offers for that ID, that contain the following data: \n\n- Seller that sells the SKU \n\n- Correspondent SKU ID \n\n- SKU's price value \n\n- Inventory level \n\n- Sales channel (or [trade policy](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV#master-data)) that it is available at.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [permissions](https:\/\/help.vtex.com\/en\/tutorial\/license-manager-resources--3q6ztrC8YynQf6rdc6euk3).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https:\/\/developers.vtex.com\/docs\/guides\/authentication-overview#machine-authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing app keys](https:\/\/help.vtex.com\/en\/tutorial\/best-practices-application-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.",
"operationId": "GetProductoffers",
"parameters": [
{
"$ref": "#/components/parameters/accountName"
},
{
"$ref": "#/components/parameters/environment"
},
{
"$ref": "#/components/parameters/contentType"
},
{
"$ref": "#/components/parameters/accept"
},
{
"$ref": "#/components/parameters/productId"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/responseGetMatchedOffersDataByProductId"
},
"example": [
{
"productId": "1561208",
"skuId": "1559161",
"nameComplete": "Blusa Cardigan Manga Longa Vestem - Feminina - CINZA G",
"mainImage": {
"imagePath": "~/arquivos/ids/8567753-#width#-#height#/image-05b40d3167b5b7ed42285124f6862f12.jpg"
},
"sellersOffers": [
{
"sellerId": "1",
"sellerSkuId": "1559161",
"salesChannelOffer": {
"salesChannelId": "1",
"salesChannelName": "Principal",
"price": 0.0,
"listPrice": 0.0,
"priceWithoutDiscount": 0.0,
"availableQuantity": 0
}
}
]
},
{
"productId": "1561208",
"skuId": "1559163",
"nameComplete": "Blusa Cardigan Manga Longa Vestem - Feminina - CINZA PP",
"mainImage": {
"imagePath": "~/arquivos/ids/8567753-#width#-#height#/image-05b40d3167b5b7ed42285124f6862f12.jpg"
},
"sellersOffers": [
{
"sellerId": "1",
"sellerSkuId": "1559161",
"salesChannelOffer": {
"salesChannelId": "1",
"salesChannelName": "Principal",
"price": 0.0,
"listPrice": 0.0,
"priceWithoutDiscount": 0.0,
"availableQuantity": 0
}
}
]
}
]
}
}
}
},
"deprecated": false
}
},
"/seller-register/pvt/seller-leads": {
"post": {
"tags": [
"Seller Invite"
],
"summary": "Invite Seller Lead",
"description": "This API is used by marketplace operators to invite sellers to join their marketplace. The request sends an email to the seller, inviting sellers to activate their store. The invitation's link in the email is unique per user, and available for only seven days for the seller to click and begin activating their store. \n\nThe email template is completely customizable. All email templates that VTEX sends to seller leads can be found and edited in the marketplace's VTEX Admin, on the Message Center section.\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| Seller Register | Seller Administration | **Save Seller** |\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 new sellers and edit data from all sellers linked to Marketplace account from the sellers management page. | Save Seller |\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": "CreateSellerLead",
"parameters": [
{
"$ref": "#/components/parameters/accountName"
},
{
"$ref": "#/components/parameters/environment"
},
{
"$ref": "#/components/parameters/accept"
},
{
"$ref": "#/components/parameters/contentType"
}
],
"requestBody": {
"description": "This request requires detailed information about the seller, including their email, name, account name, sales channel, and other related details. Data should be in JSON format and follow the schema specified in 'CreateSellerLeadRequest'. A sample valid payload is provided for reference, including details such as address, contact information, and acceptance of legal terms.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateSellerLeadRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/responseCreateSellerLead"
},
"example":{
"sellerId": "7890123456",
"createdAt": "2023-01-01T12:34:56Z",
"updatedAt": "2023-01-01T12:34:56Z"
}
}
}
}
},
"deprecated": false
},
"get": {
"tags": [
"Seller Invite"
],
"summary": "List Seller Leads",
"operationId": "ListSellerLeads",
"description": "This call's response includes a list of all sellers invited by the marketplace operator to join them. Retrieved results can be filtered by adding optional query fields to the request. Each seller listed includes the following information: \n\n- `id` \n\n- `createdAt` \n\n- `status` \n\n- `isConnected` \n\n- `sellerEmail` \n\n- `sellerName` \n\n- `salesChannel` \n\n- `email`\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| Seller Register | Seller Administration | **View Seller** |\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| View all sellers linked to the Marketplace account described on the sellers management page, including recovering seller data, either from the sellers listing, or a specific seller. | View Seller |\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).",
"parameters": [
{
"$ref": "#/components/parameters/accountName"
},
{
"$ref": "#/components/parameters/environment"
},
{
"$ref": "#/components/parameters/offset"
},
{
"$ref": "#/components/parameters/limit"
},
{
"$ref": "#/components/parameters/isConnected"
},
{
"$ref": "#/components/parameters/search"
},
{
"$ref": "#/components/parameters/status"
},
{
"$ref": "#/components/parameters/orderBy"
},
{
"$ref": "#/components/parameters/accept"
},
{
"$ref": "#/components/parameters/contentType"
}
],
"responses": {
"200": {
"description": "OK",
"headers": {}
}
},
"deprecated": false
}
},
"/seller-register/pvt/seller-leads/{sellerLeadId}": {
"put": {
"tags": [
"Seller Invite"
],
"summary": "Accept Seller Lead",
"operationId": "AcceptSellerLead",
"description": "This endpoint is triggered by the seller onboarding wizard, once the seller confirms their invitation. It can be used by marketplace operators to manually accept seller leads, and carry on with their onboarding process. \n\nNote that there's no specific API call that allows status changes. The operations only allow the seller lead to move forward: \n\n From `invite` > to `Accept` > closing on `Create Seller`. \n\nIf you want to change the status, you can start the process again, by deleting that lead through the *Delete Seller Lead* endpoint, and resending the invite through the *Resend Seller Lead's Invite* endpoint.",
"parameters": [
{
"$ref": "#/components/parameters/accountName"
},
{
"$ref": "#/components/parameters/environment"
},
{
"$ref": "#/components/parameters/sellerId"
},
{
"$ref": "#/components/parameters/contentType"
}
],
"requestBody": {
"description": "This request requires information about the seller who is accepting the lead, including their email, name, account name, sales channel, and other relevant details.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AcceptSellerLeadRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"headers": {}
}
},
"deprecated": false
},
"get": {
"tags": [
"Seller Invite"
],
"summary": "Get Seller Lead's Data by Id",
"operationId": "RetrieveSellerLead",
"description": "Marketplace operators may call this endpoint to retrieve information about a specific seller invited to the Seller Portal, by searching through their `Seller Lead Id`. To know the chosen seller's `sellerLeadId`, marketplace operators can count on the *List Sellers* endpoint's response as well. Each seller listed includes the following information: \n\n- `id` \n\n- `createdAt` \n\n- `status` \n\n- `isConnected` \n\n- `sellerEmail` \n\n- `sellerName` \n\n- `salesChannel` \n\n- `email`",
"parameters": [
{
"$ref": "#/components/parameters/accountName"
},
{
"$ref": "#/components/parameters/environment"
},
{
"$ref": "#/components/parameters/sellerId"
},
{
"$ref": "#/components/parameters/accept"
},
{
"$ref": "#/components/parameters/contentType"
}
],
"responses": {
"200": {
"description": "OK",
"headers": {}
}
},
"deprecated": false
},
"delete": {
"tags": [
"Seller Invite"
],
"summary": "Delete Seller Lead",
"description": "This endpoint permanently deletes a seller previously invited to the marketplace, if the seller has not already accepted the invitation.",
"operationId": "RemoveSellerLead",
"parameters": [
{
"$ref": "#/components/parameters/accountName"
},
{
"$ref": "#/components/parameters/environment"
},
{
"$ref": "#/components/parameters/sellerLeadId"
},
{
"$ref": "#/components/parameters/accept"
},
{
"$ref": "#/components/parameters/contentType"
}
],
"responses": {
"200": {
"description": "OK",
"headers": {}
}
},
"deprecated": false
}
},
"/seller-register/pvt/seller-leads/{sellerLeadId}/seller": {
"put": {
"tags": [
"Seller Invite"
],
"summary": "Create Seller From Lead",
"operationId": "CreateSellerFromSellerLead",
"description": "This endpoint is used by marketplace operators to create seller accounts. The request will only accept Seller Leads whose status is `accepted`. If they are already `connected` or `invited`, the call will not be fulfilled. \n\nThe creation of the account at VTEX is done by an internal Billing service. There is no seller account and marketplace affiliation if you do not go through this step. \n\nNote that there's no specific API call that allows status changes. The operations only allow the seller lead to move forward: \n\n From `invite` > to `Accept` > closing on `Create Seller`. \n\nIf you want to change the status, you can start the process again, by deleting that lead through the *Delete Seller Lead* endpoint, and resending the invite through the *Resend Seller Lead's Invite* endpoint.",
"parameters": [
{
"$ref": "#/components/parameters/accountName"
},
{
"$ref": "#/components/parameters/environment"
},
{
"$ref": "#/components/parameters/isActive"
},
{
"$ref": "#/components/parameters/sellerId"
},
{
"$ref": "#/components/parameters/accept"
},
{
"$ref": "#/components/parameters/contentType"
}
],
"responses": {
"200": {
"description": "OK",
"headers": {}
}
},
"deprecated": false
}
},
"/seller-register/pvt/seller-leads/{sellerLeadId}/status": {
"put": {
"tags": [
"Seller Invite"
],
"summary": "Resend Seller Lead Invite",
"description": "This endpoint allows marketplace operators to resend an invitation to a seller lead, previously invited to join their marketplace. The request will only accept Seller Leads whose status is `invited`. If they are already `connected` or `accepted`, the call will not be fulfilled.",
"operationId": "ResendSellerLeadRequest",
"parameters": [
{
"$ref": "#/components/parameters/accountName"
},
{
"$ref": "#/components/parameters/environment"
},
{
"$ref": "#/components/parameters/sellerId"
},
{
"$ref": "#/components/parameters/accept"
},
{
"$ref": "#/components/parameters/contentType"
}
],
"requestBody": {
"description": "This request requires information specifying the action to be taken, such as the status to be resent.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResendSellerLeadRequestRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"headers": {}
}
},
"deprecated": false
}
},
"/seller-register/pvt/sellers/{sellerId}/commissions": {
"get": {
"tags": [
"Seller Commissions"
],
"summary": "List Seller Commissions by seller ID",
"description": "This endpoint retrieves all comissions configured for a specific seller. It is not necessary to send a request body.\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** | **Role** |\r\n|---|---|---|---|\r\n| Seller Register | Seller adminstration | View Seller | View all sellers linked to the Marketplace account described on the sellers management page, including recovering seller data, either from the sellers listing, or a specific seller. |\r\n| Seller Register | Seller administration | Save Seller | Create new sellers and edit data from all sellers linked to Marketplace account from the sellers management page. |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with this feature or use one of the predefined roles from the list above.\r\n\r\n >❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) 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).",
"operationId": "ListSellerCommissions",
"parameters": [
{
"$ref": "#/components/parameters/accountName"
},
{
"$ref": "#/components/parameters/environment"
},
{
"$ref": "#/components/parameters/sellerId"
},
{
"$ref": "#/components/parameters/accept"
},
{
"$ref": "#/components/parameters/contentType"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"description": "Array with objects containing information about the category, seller and percentage of commission applied.",
"items": {
"$ref": "#/components/schemas/responseSellerCommissionsID"
}
},
"example": {
"categoryId": "51",
"categoryName": "Clothes",
"categoryFullPath": [
"2.0",
"Boys",
"Clothes"
],
"productCommissionPercentage": 7.75,
"freightCommissionPercentage": 2.33
}
}
}
}
},
"deprecated": false
},
"put": {
"tags": [
"Seller Commissions"
],
"summary": "Upsert Seller Commissions in bulk",
"description": "This endpoint is used by marketplace operators to define comissions for multiple categories, sending an array with multiple objects in the same call.\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** | **Role** |\r\n|----|----|----|----|\r\n| Seller Register | Seller administration | Save Seller | Create new sellers and edit data from all sellers linked to Marketplace account from the sellers management page. |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with this feature or use one of the predefined roles from the list above.\r\n\r\n >❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) 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).",
"operationId": "BulkUpsertSellerCommissions",
"parameters": [
{
"$ref": "#/components/parameters/accountName"
},
{
"$ref": "#/components/parameters/environment"
},
{
"$ref": "#/components/parameters/accept"
},
{
"$ref": "#/components/parameters/contentType"
},
{
"$ref": "#/components/parameters/sellerId"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "array",
"description": "Array with objects containing information about the category, seller and commission percentage to be applied.",
"items": {
"$ref": "#/components/schemas/BulkUpsertSellerCommissionsRequest"
}
}
}
},
"required": true
},
"responses": {
"204": {
"description": "No Content"
}
},
"deprecated": false
}
},
"/seller-register/pvt/sellers/{sellerId}/commissions/{categoryId}": {
"delete": {
"tags": [
"Seller Commissions"
],
"summary": "Remove Seller Commissions by Category ID",
"operationId": "RemoveSellerCommissions",
"description": "This endpoint removes a seller comission on the selected category.\r\n\r\n >❗This action cannot be undone, to reconfigure the commission it is necessary to use the [Upsert Seller Commissions in Bulk endpoint](https://developers.vtex.com/docs/api-reference/marketplace-apis#put-/seller-register/pvt/sellers/-sellerId-/commissions/categories?endpoint=put-/seller-register/pvt/sellers/-sellerId-/commissions/categories). \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** | **Role** |\r\n|----|----|----|----|\r\n| Seller Register | Seller administration | Save Seller | Create new sellers and edit data from all sellers linked to Marketplace account from the sellers management page. |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with this feature or use one of the predefined roles from the list above.\r\n\r\n >❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) 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).",
"parameters": [
{
"$ref": "#/components/parameters/accountName"
},
{
"$ref": "#/components/parameters/environment"
},
{
"$ref": "#/components/parameters/accept"
},
{
"$ref": "#/components/parameters/contentType"
},
{
"$ref": "#/components/parameters/sellerId"
},
{
"$ref": "#/components/parameters/categoryId"
}
],
"responses": {
"204": {
"description": "No Content"
}
},
"deprecated": false
},
"get": {
"tags": [
"Seller Commissions"
],
"summary": "Get Seller Commissions by Category ID",
"operationId": "RetrieveSellerCommissions",
"description": "This endpoint retrieves seller comissions applied to the selected category. It is not necessary to send a request body.\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** | **Role** |\r\n|---|---|---|---|\r\n| Seller Register | Seller adminstration | View Seller | View all sellers linked to the Marketplace account described on the sellers management page, including recovering seller data, either from the sellers listing, or a specific seller. |\r\n| Seller Register | Seller administration | Save Seller | Create new sellers and edit data from all sellers linked to Marketplace account from the sellers management page. |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with this feature or use one of the predefined roles from the list above.\r\n\r\n >❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) 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).",
"parameters": [
{
"name": "accountName",
"in": "path",
"description": "Name of the VTEX account that belongs to the marketplace. All data extracted, and changes added will be posted into this account.",
"required": true,
"schema": {
"type": "string",
"default": "apiexamples"
}
},
{
"name": "environment",
"in": "path",
"required": true,
"description": "Environment to use. Used as part of the URL.",
"schema": {
"type": "string",
"default": "vtexcommercestable"
}
},
{
"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"
}
},
{
"name": "Content-Type",
"in": "header",
"description": "Describes the type of the content being sent.",
"required": true,
"style": "simple",
"schema": {
"type": "string",
"default": "application/json"
}
},
{
"name": "sellerId",
"in": "path",
"description": "A string that identifies the seller in the marketplace. This ID must be created by the marketplace.",
"required": true,
"style": "simple",
"schema": {
"type": "string",
"default": "seller123"
}
},
{
"name": "categoryId",
"in": "path",
"description": "ID of the category in which the comission was applied",
"required": true,
"style": "simple",
"schema": {
"type": "string",
"default": "6"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/responseSellerCommissionsID"
}
}
}
}
},
"deprecated": false
}
},
"/seller-register/pvt/sellers": {
"post": {
"tags": [
"Sellers"
],
"summary": "Configure Seller Account",
"description": "This endpoint is used by marketplace operators to configure the accounts of sellers that have already accepted the invitation to join their marketplaces. \n\nFor marketplaces to [add sellers](https://help.vtex.com/en/tutorial/adding-a-seller--tutorials_392) without the [Seller Invite](https://help.vtex.com/en/tutorial/marketplace-invited-sellers--6rb2FkcslmDueJ689Ulb9A) feature, call this endpoint directly. \n\nThis call includes all the information a seller needs to activate their account.",
"operationId": "UpsertSellerRequest",
"parameters": [
{
"$ref": "#/components/parameters/accountName"
},
{
"$ref": "#/components/parameters/environment"
},
{
"$ref": "#/components/parameters/accept"
},
{
"$ref": "#/components/parameters/contentType"
}
],
"requestBody": {
"description": "Request to upsert seller information.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpsertSellerRequest"
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"headers": {}
}
},
"deprecated": false
},
"get": {
"tags": [
"Sellers"
],
"summary": "List Sellers",
"description": "This endpoint lists all Sellers. This call's results can be filtered by [trade policies](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV#master-data) through the `sc` query param.",
"operationId": "GetListSellers",
"parameters": [
{
"$ref": "#/components/parameters/accountName"
},
{
"$ref": "#/components/parameters/environment"
},
{
"$ref": "#/components/parameters/from"
},
{
"$ref": "#/components/parameters/to"
},
{
"$ref": "#/components/parameters/keyword"
},
{
"$ref": "#/components/parameters/integration"
},
{
"$ref": "#/components/parameters/group"
},
{
"$ref": "#/components/parameters/isActive"
},
{
"$ref": "#/components/parameters/isBetterScope"
},
{
"$ref": "#/components/parameters/isVtex"
},
{
"$ref": "#/components/parameters/sc"
},
{
"$ref": "#/components/parameters/sellerType"
},
{
"$ref": "#/components/parameters/sort"
},
{
"$ref": "#/components/parameters/accept"
},
{
"$ref": "#/components/parameters/contentType"
}
],
"responses": {
"200": {
"description": "OK",
"headers": {}
}
},
"deprecated": false
}
},
"/seller-register/pvt/sellers/{sellerId}": {
"patch": {
"tags": [
"Sellers"
],
"summary": "Update Seller by Seller ID",
"description": "This endpoint allows marketplace operators to update the information of sellers connected to their account. You can replace a path's value with another value in order to update that single information. There is no need to fill all the body params available, only the one you wish to update.",
"operationId": "UpdateSeller",
"parameters": [
{
"$ref": "#/components/parameters/accountName"
},
{
"$ref": "#/components/parameters/environment"
},
{
"$ref": "#/components/parameters/accept"
},
{
"$ref": "#/components/parameters/contentType"
},
{
"$ref": "#/components/parameters/sellerId"
}
],
"requestBody": {
"description": "array of objects",
"content": {
"application/json": {
"schema": {
"type": "array",
"description": "array of objects",
"title": "Request body",
"items": {
"description": "Object representing the mapping configuration between the marketplace's sales channel and the seller's affiliate channel. This configuration allows for associating a marketplace sales channel with a seller's affiliate channel for proper sales channel management.",
"type": "object",
"required": [
"operation",
"path",
"value"
],
"properties": {
"operation": {
"type": "string",
"description": "The action being performed, which is always going to be `replace`.",
"default": "replace"
},
"path": {
"type": "string",
"default": "/field",
"description": "The path in which the value is being updated. It follows the standardized format `/{field}`, where `{field}` is the path's name."
},
"value": {
"type": "boolean",
"default": false,
"description": "The value that is being updated. Notice that the type will depend on the path that is being updated."
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"headers": {}
}
},
"deprecated": false
},
"get": {
"tags": [
"Sellers"
],
"summary": "Get Seller data by ID",
"operationId": "GetRetrieveSeller",
"description": "Marketplace operator may call this endpoint to retrieve information about a specific seller by filtering by ID. It is also possible to filter results by sales channel (or [trade policy](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV#master-data)) through the `sc` query param.",
"parameters": [
{
"$ref": "#/components/parameters/accountName"
},
{
"$ref": "#/components/parameters/environment"
},
{
"$ref": "#/components/parameters/sc"
},
{
"$ref": "#/components/parameters/sellerId"
},
{
"$ref": "#/components/parameters/accept"
},
{
"$ref": "#/components/parameters/contentType"
}
],
"responses": {
"200": {
"description": "OK",
"headers": {}
}
},
"deprecated": false
}
},
"/seller-register/pvt/sellers/{sellerId}/sales-channel/mapping": {
"put": {
"tags": [
"Sales Channel Mapping"
],
"summary": "Upsert Sales Channel Mapping",
"description": "This endpoint allows the marketplace to map its sales channels with a seller's [affiliate](https://help.vtex.com/en/tutorial/configuring-affiliates--tutorials_187). The seller can have multiple sales channels associated with the same marketplace, by creating different affiliates. The mapping enables the seller to segment catalog, prices, inventory, logistics, and payments in the marketplace.",
"operationId": "UpsertMapping",
"parameters": [
{
"$ref": "#/components/parameters/contentType"
},
{
"$ref": "#/components/parameters/accept"
},
{
"$ref": "#/components/parameters/accountName"
},
{
"$ref": "#/components/parameters/environment"
},
{
"$ref": "#/components/parameters/an"
},
{
"$ref": "#/components/parameters/sellerId"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/UpsertMappingRequest"
},
"example": [
{
"marketplaceSalesChannel": 1,
"sellerChannel": "GCB"
},
{
"marketplaceSalesChannel": 2,
"sellerChannel": "DFT"
}
]
}
}
},
"required": true
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"description": "Object representing the mapping configuration between the marketplace's sales channel and the seller's affiliate channel. This configuration allows for associating a marketplace sales channel with a seller's affiliate channel for proper sales channel management.",
"type": "object",
"properties": {
"marketplaceSalesChannel": {
"type": "string",
"description": "Marketplace's sales channel that will be associated to the seller's [affiliate](https://help.vtex.com/en/tutorial/configuring-affiliates--tutorials_187).",
"default": "1"
},
"sellerChannel": {
"type": "string",
"description": "Seller's [affiliate](https://help.vtex.com/en/tutorial/configuring-affiliates--tutorials_187) that will be associated with the marketplace's sales channel. Through the affiliate, the seller determines which of his sales channel will be used for the mapping.",
"default": "GCB"
}
}
},
"title": "UpsertMapping",
"example": [
{
"marketplaceSalesChannel": "1",
"sellerChannel": "GCC"
}
],
"properties": {
"marketplaceSalesChannel": {
"type": "integer",
"description": "Marketplace's sales channel that will be associated to the seller's [affiliate](https://help.vtex.com/en/tutorial/configuring-affiliates--tutorials_187).",
"default": 1
},
"sellerChannel": {
"type": "string",
"description": "Seller's [affiliate](https://help.vtex.com/en/tutorial/configuring-affiliates--tutorials_187) that will be associated with the marketplace's sales channel. Through the affiliate, the seller determines which of his sales channel will be used for the mapping.",
"default": "GCB"
}
}
}
}
}
}
},
"deprecated": false
},
"get": {
"tags": [
"Sales Channel Mapping"
],
"summary": "Get Sales Channel Mapping Data",
"description": "Retrieves information about the mapping between marketplace's sales channels and a specific seller.",
"operationId": "RetrieveMapping",
"parameters": [
{
"$ref": "#/components/parameters/contentType"
},
{
"$ref": "#/components/parameters/accept"
},
{
"$ref": "#/components/parameters/accountName"
},
{
"$ref": "#/components/parameters/environment"
},
{
"$ref": "#/components/parameters/an"
},
{
"$ref": "#/components/parameters/sellerId"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"description": "Object representing the mapping between the marketplace's sales channel and the seller's affiliate channel. This allows for the association and management of sales channels between the marketplace and the seller's affiliate.",
"type": "object",
"properties": {
"marketplaceSalesChannel": {
"type": "string",
"description": "Marketplace's sales channel that will be associated to the seller's [affiliate](https://help.vtex.com/en/tutorial/configuring-affiliates--tutorials_187).",
"default": "1"
},
"sellerChannel": {
"type": "string",
"description": "Seller's [affiliate](https://help.vtex.com/en/tutorial/configuring-affiliates--tutorials_187) that will be associated with the marketplace's sales channel. Through the affiliate, the seller determines which of his sales channel will be used for the mapping.",
"default": "GCB"
}
}
},
"title": "UpsertMapping",
"properties": {
"marketplaceSalesChannel": {
"type": "integer",
"description": "Marketplace's sales channel that will be associated to the seller's [affiliate](https://help.vtex.com/en/tutorial/configuring-affiliates--tutorials_187).",
"default": 1
},
"sellerChannel": {
"type": "string",
"description": "Seller's [affiliate](https://help.vtex.com/en/tutorial/configuring-affiliates--tutorials_187) that will be associated with the marketplace's sales channel. Through the affiliate, the seller determines which of his sales channel will be used for the mapping.",
"default": "GCB"
}
}
},
"example": [
{
"marketplaceSalesChannel": "1",
"sellerChannel": "GCC"
}
]
}
}
}
},
"deprecated": false
}
}
},
"security": [
{
"appKey": [],
"appToken": []
}
],
"components": {
"schemas": {
"UpsertMappingRequest": {
"description": "Request to upsert a mapping between a marketplace's sales channel and a seller's affiliate.",
"required": [
"marketplaceSalesChannel",
"sellerChannel"
],
"type": "object",
"properties": {
"marketplaceSalesChannel": {
"type": "integer",
"description": "The sales channel of the marketplace to be associated with the seller's affiliate. It is linked to the seller's affiliate.",
"example": 1
},
"sellerChannel": {
"type": "string",
"description": "The affiliate of the seller that will be associated with the marketplace's sales channel. Through the affiliate, the seller determines which of his sales channels will be used for the mapping.",
"example": "GCB"
}
},
"example": {
"marketplaceSalesChannel": 1,
"sellerChannel": "GCB"
}
},
"responseSellerCommissionsID": {
"type": "object",
"description": "Object with the category properties and the commission percentage applied to it.",
"properties": {
"categoryId": {
"type": "string",
"description": "Marketplace's Category ID that the product belongs to, configured in the Catalog.",
"example": "51"
},
"categoryName": {
"type": "string",
"description": "Category name with applied commission.",
"example": "Clothes"
},
"categoryFullPath": {
"type": "array",
"description": "Full path to the SKU's category.",
"items": {
"description": "Category level name or identifier.",
"type": "string",
"example": "2.0"
},
"example": [
"2.0",
"Boys",
"Clothes"
]
},
"productCommissionPercentage": {
"type": "number",
"description": "Percentage of the comission applied to the product in decimals.",
"example": 7.75
},
"freightCommissionPercentage": {
"type": "number",
"description": "Percentage of the comission applied to the freight in decimals.",
"example": 2.33
}
}
},
"BulkUpsertSellerCommissionsRequest": {
"description": "Request to bulk upsert (update or insert) seller commission configurations for multiple categories. This includes details such as the category ID, full path of the category, product commission percentage, and freight commission percentage.",
"type": "object",
"required": [
"categoryId",
"categoryFullPath",
"productCommissionPercentage",
"freightCommissionPercentage"
],
"properties": {
"categoryId": {
"type": "string",
"description": "Marketplace's Category ID that the product belongs to, configured in the Catalog.",
"example": "6"
},
"categoryFullPath": {
"type": "string",
"nullable": true,
"description": "Full path to the SKU's category. It should be written as {department}/{category}. For example: if the department is **Appliances** and the category is **Oven**, the full path should be 'Appliances/Oven'.",
"example": "Appliances/Oven"
},
"productCommissionPercentage": {
"type": "number",
"description": "Percentage of the comission applied to the product in decimals.",
"example": 9.85
},
"freightCommissionPercentage": {
"type": "number",
"description": "Percentage of the comission applied to the freight in decimals.",
"example": 2.43
}
},
"example": [
{
"categoryId": "6",
"categoryFullPath": null,
"productCommissionPercentage": 9.85,
"freightCommissionPercentage": 2.43
},
{
"categoryId": "51",
"categoryFullPath": "Appliances/Oven",
"productCommissionPercentage": 7.85,
"freightCommissionPercentage": 3.43
}
]
},
"UpsertSellerCommissionsRequest": {
"description": "Request to upsert seller commission configurations. This includes details such as the category ID, full path of the category, product commission percentage, and freight commission percentage.",
"required": [
"categoryId",
"categoryFullPath",
"productCommissionPercentage",
"freightCommissionPercentage"
],
"type": "object",
"properties": {
"categoryId": {
"type": "string",
"description": "Marketplace's Category ID that the product belongs to, configured in the Catalog.",
"default": "6"
},
"categoryFullPath": {
"type": "string",
"nullable": true,
"description": "Full path to the SKU's category. It should be written as {department}/{category}. For example: if the department is **Appliances** and the category is **Oven**, the full path should be 'Appliances/Oven'.",
"example": "Appliances/Oven"
},
"productCommissionPercentage": {
"type": "number",
"description": "Percentage of the comission applied to the product in decimals.",
"default": 9.85
},
"freightCommissionPercentage": {
"type": "number",
"description": "Percentage of the comission applied to the freight in decimals.",
"default": 2.43
}
},
"example": {
"categoryId": "6",
"categoryFullPath": null,
"productCommissionPercentage": 9.85,
"freightCommissionPercentage": 2.43
}
},
"CreateSellerLeadRequest": {
"description": "Request to create a seller lead. This includes detailed information about the seller, such as their email, name, account name, sales channel, contact email, seller type, account ID, accountable person, acceptance of legal terms, address, and document details.",
"required": [
"sellerEmail",
"sellerName",
"sellerAccountName",
"salesChannel",
"email",
"sellerType",
"accountId",
"accountable",
"hasAcceptedLegalTerms",
"address",
"document"
],
"type": "object",
"properties": {
"sellerEmail": {
"type": "string",
"description": "Seller's contact email.",
"default": "selleremail@email.com"
},
"sellerName": {
"type": "string",
"description": "Seller's store's name.",
"default": "Seller Name"
},
"sellerAccountName": {
"type": "string",
"description": "Name of the seller's account, part of the url of their VTEX Admin.",
"default": "seller123"
},
"salesChannel": {
"type": "string",
"description": "Sales channel (or [trade policy](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV#master-data)) associated to the seller account created.",
"default": "1"
},
"email": {
"description": "The email address associated with the seller or user. It should be in a valid email format.",
"type": "string",
"example": "email@email.com"
},
"sellerType": {
"type": "integer",
"description": "Type of seller, including: \n\n`1`: regular seller \n\n`2`: whitelabel seller.",
"default": 1
},
"accountId": {
"type": "string",
"description": "Marketplace's account ID.",
"default": "5fb38ace-d95e-45ad-970d-ee97cce9fbcd"
},
"document": {
"type": "string",
"description": "Company's legal document code.",
"default": "12345671000"
},
"hasAcceptedLegalTerms": {
"type": "boolean",
"description": "Indicates if the seller has accepted the platform's legal terms and conditions.",
"default": true
},
"address": {
"$ref": "#/components/schemas/address"
},
"accountable": {
"$ref": "#/components/schemas/accountable"
}
},
"example": {
"sellerEmail": "selleremail@email.com",
"sellerName": "Seller Name",
"sellerAccountName": "seller123",
"salesChannel": "1",
"email": "email@email.com",
"sellerType": 1,
"accountId": "5fb38ace-d95e-45ad-970d-ee97cce9fbcd",
"document": "12345671000",
"hasAcceptedLegalTerms": true,
"address": {
"postalcode": "12345678",
"complement": "Appartment 1234",
"street": "VTEX street",
"number": "25",
"neighborhood": "VTEX quarter",
"state": "RJ",
"city": "Rio de Janeiro"
},
"accountable": {
"name": "Jane Smith",
"email": "email@email.com",
"phone": "1234567890"
}
}
},
"responseCreateSellerLead":{
"type": "object",
"description": "Response object for creating a seller lead. It includes details about the created seller, such as their ID, the creation date, and the date of the last update.",
"properties": {
"sellerId": {
"type": "string",
"description": "ID of the created seller.",
"example": "7890123456"
},
"createdAt": {
"type": "string",
"description": "Creation date of the seller.",
"example":"2022-01-01T12:34:56Z"
},
"updatedAt": {
"type": "string",
"description": "Date of the last update of the seller.",
"example": "2023-01-01T12:34:56Z"
}
}
},
"accountable": {
"type": "object",
"description": "Details of the person accountable for the seller's account. This includes their name, email address, and phone number.",
"required": [
"name",
"email",
"phone"
],
"properties": {
"name": {
"type": "string",
"title": "name",
"description": "Name of the person responsible for the seller.",
"default": "Jane Smith"
},
"email": {
"type": "string",
"title": "email",
"description": "Email address of the person responsible for the seller.",
"default": "email@email.com"
},
"phone": {
"type": "string",
"title": "phone",
"description": "Phone number of the person responsible for the seller.",
"default": "1234567890"
}
}
},
"address": {
"type": "object",
"description": "Details of the address associated with the seller. This includes postal code, complement, street, number, neighborhood, state, and city.",
"required": [
"postalcode",
"complement",
"street",
"number",
"neighborhood",
"state",
"city"
],
"properties": {
"postalcode": {
"type": "string",
"title": "postalCode",
"description": "Postal code from the seller's address.",
"default": "12345678"
},
"complement": {
"type": "string",
"title": "complement",
"description": "Seller's address complement.",
"default": "Appartment 1234"
},
"street": {
"type": "string",
"title": "street",
"description": "Street information, from the seller's address.",
"default": "VTEX street"
},
"number": {
"type": "string",
"title": "number",
"description": "Street's number, from the seller's address.",
"default": "25"
},
"neighborhood": {
"type": "string",
"title": "The neighborhood schema",
"description": "Seller's address neighborhood.",
"default": "VTEX quarter"
},
"state": {
"type": "string",
"title": "state",
"description": "State, from the seller's address.",
"default": "RJ"
},
"city": {
"type": "string",
"title": "city",
"description": "City name, from the seller's address.",
"default": "Rio de Janeiro"
}
}
},
"AcceptSellerLeadRequest": {
"description": "Request to accept a seller lead. This includes detailed information about the seller, such as their email, name, account name, sales channel, contact email, seller type, account ID, document details, acceptance of legal terms, address, and accountable party.",
"required": [
"sellerEmail",
"sellerName",
"sellerAccountName",
"salesChannel",
"email",
"sellerType",
"accountId",
"document",
"hasAcceptedLegalTerms",
"address",
"accountable"
],
"type": "object",
"properties": {
"sellerEmail": {
"type": "string",
"description": "Seller's contact email.",
"default": "selleremail@email.com"
},
"sellerName": {
"type": "string",
"description": "Seller's store's name.",
"default": "Seller Name"
},
"sellerAccountName": {
"type": "string",
"description": "Name of the seller's account, part of the url of their VTEX Admin.",
"default": "seller123"
},
"salesChannel": {
"type": "string",
"description": "Sales channel (or [trade policy](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV#master-data)) associated to the seller account created.",
"default": "1"
},
"email": {
"type": "string",
"description": "email of the admin responsible for the seller.",
"default": "seller@email.com"
},
"sellerType": {
"type": "integer",
"description": "Type of seller, including: \n\n`1`: regular seller \n\n`2`: whitelabel seller.",
"default": 1
},
"accountId": {
"type": "string",
"description": "Marketplace's account ID.",
"default": "5fb38ace-d95e-45ad-970d-ee97cce9fbcd"
},
"document": {
"type": "string",
"description": "Company's legal document code.",
"default": "12345671000"
},
"hasAcceptedLegalTerms": {
"type": "boolean",
"description": "Indicates if the seller has accepted the platform's legal terms and conditions.",
"default": true
},
"address": {
"$ref": "#/components/schemas/address"
},
"accountable": {
"$ref": "#/components/schemas/accountable"
}
},
"example": {
"sellerEmail": "selleremail@email.com",
"sellerName": "Seller Name",
"affiliateId": "MKP",
"sellerAccountName": "seller123",
"salesChannel": "1",
"email": "seller@email.com",
"sellerType": 1,
"accountId": "5fb38ace-d95e-45ad-970d-ee97cce9fbcd",
"document": "12345671000",
"hasAcceptedLegalTerms": true,
"address": {
"postalcode": "12345678",
"complement": "Appartment 1234",
"street": "VTEX street",
"number": "25",
"neighborhood": "VTEX quarter",
"state": "RJ",
"city": "Rio de Janeiro"
},
"accountable": {
"name": "Jane Smith",
"email": "email@email.com",
"phone": "1234567890"
}
}
},
"ResendSellerLeadRequestRequest": {
"description": "Request to resend a seller lead. This includes the status of the lead that determines the action to be taken.",
"required": [
"status"
],
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Seller Lead's status. Includes `accepted`, `connected` or `invited`.",
"default": "accepted"
}
},
"example": {
"status": "accepted"
}
},
"UpsertSellerRequest": {
"title": "Configure Seller Account",
"description": "Request to configure or update a seller account. This includes all necessary details for setting up the seller's account, such as ID, name, status, fulfillment settings, payment options, tax information, contact details, commission configuration, policies, and authentication information.",
"required": [
"id",
"name",
"isActive",
"fulfillmentEndpoint",
"allowHybridPayments",
"taxCode",
"email",
"description",
"sellerCommissionConfiguration",
"isBetterScope",
"sellerType",
"availableSalesChannels",
"CSCIdentification",
"account",
"channel",
"salesChannel",
"isVtex",
"score",
"exchangeReturnPolicy",
"deliveryPolicy",
"securityPrivacyPolicy",
"fulfillmentSellerId",
"user",
"password",
"catalogSystemEndpoint",
"trustPolicy"
],
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Seller ID assigned by the marketplace. We recommend filling it in with the seller's account name.",
"default": "seller123"
},
"name": {
"type": "string",
"description": "Name of the seller's store, configured in the seller's environment.",
"default": "Seller Name"
},
"isActive": {
"type": "boolean",
"description": "Whether the seller is active on the marketplace or not.",
"default": true
},
"fulfillmentEndpoint": {
"type": "string",
"description": "URL of the endpoint for fulfillment of seller's orders, which the marketplace will use to communicate with the seller. \n\nFor **external sellers**, please include the URL of the seller's endpoint. External sellers have different endpoint standards. The seller must inform this endpoint to the marketplace so that the marketplace can complete the configuration process. \n\nFor **VTEX Stores**, the field format will be as follows: `https://{SellerName}.vtexcommercestable.com.br/api/fulfillment?&sc={TradePolicyID}`. \n\nThe value `SellerName` corresponds to the store name if the seller is a VTEX store. \n\nThe value `TradePolicyID` corresponds to the [trade policy](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV#master-data) created by the seller in their own VTEX environment. The seller must inform this ID to the marketplace so that the marketplace can complete the configuration process. \n\nThe value `AffiliateID` corresponds to the 3-digit affiliate identification code created by the seller. The seller must inform this ID to the marketplace so that the marketplace can complete the configuration process. \n\nTo configure the [Multilevel Omnichannel Inventory](https://developers.vtex.com/vtex-rest-api/docs/multilevel-omnichannel-inventory) feature, fill in this field with the checkout endpoint following this example: `https://{{sellerAccount}}.vtexcommercestable.com.br/api/checkout?affiliateid={{affiliateId}}&sc={{salesChannel`.",
"default": "http://{SellerName}.vtexcommercestable.com.br/api/fulfillment?&sc={TradePolicyID}"
},
"allowHybridPayments": {
"type": "boolean",
"description": "Flag that allows customers to use gift cards from the seller to buy their products on the marketplace. It identifies purchases made with a gift card so that only the final price (with discounts applied) is paid to the seller.",
"default": false
},
"taxCode": {
"type": "string",
"description": "This code is the Identity Number for the legal entity and is linked to information in its base country.",
"default": "34444"
},
"email": {
"type": "string",
"description": "email of the admin responsible for the seller.",
"default": "seller@email.com"
},
"description": {
"type": "string",
"description": "String describing the seller.",
"default": "Seller A, from the B industry."
},
"sellerCommissionConfiguration": {
"description": "Details of the seller's commission configuration, including the product commission percentage, freight commission percentage, and categories commission configuration.",
"type": "object",
"items": {
"$ref": "#/components/schemas/SellerCommissionConfiguration"
}
},
"isBetterScope": {
"type": "boolean",
"description": "Flag used by the VTEX Checkout to simmulate shopping carts, products and shipping only in sellers with the boolean set as `true`, avoiding performance issues.",
"default": true
},
"sellerType": {
"type": "integer",
"description": "Type of seller, including: \n\n`1`: regular seller \n\n`2`: whitelabel seller.",
"default": 1
},
"availableSalesChannels": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AvailableSalesChannel"
},
"description": "Sales channel (or [trade policy](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV#master-data)) available.",
"default": []
},
"CSCIdentification": {
"type": "string",
"description": "SKU Seller Identification.",
"default": "cscidentification 123"
},
"account": {
"type": "string",
"description": "Seller's account name.",
"default": "partner01"
},
"channel": {
"type": "string",
"description": "Channel's name.",
"default": "channel name"
},
"salesChannel": {
"type": "string",
"description": "Sales channel (or [trade policy](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV)) associated to the seller account created. If no value is specified, the system will automatically use the sales channel configured in the seller's [affiliate](https://help.vtex.com/en/tutorial/configuring-affiliates--tutorials_187) ID.",
"default": "1"
},
"isVtex": {
"type": "boolean",
"description": "Flag determining whether the seller configured is a VTEX store or not.",
"default": true
},
"exchangeReturnPolicy": {
"type": "string",
"description": "Text describing the exchange and return policy previously agreed between the marketplace and the seller.",
"default": "Describe exchange and returns policy"
},
"deliveryPolicy": {
"type": "string",
"description": "Text describing the delivery policy previously agreed between the marketplace and the seller.",
"default": "Describe delivery policy"
},
"securityPrivacyPolicy": {
"type": "string",
"nullable": true,
"description": " Text describing the security policy previously agreed between the marketplace and the seller.",
"default": "Describe privacy and security policy"
},
"fulfillmentSellerId": {
"type": "string",
"description": " Identification code of the seller responsible for fulfilling the order. This is an optional field used when a seller sells SKUs from another seller. If the seller sells their own SKUs, it must be nulled.",
"default": "seller1"
},
"groups": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Groups"
},
"description": "Array of groups attached to the seller. Groups are defined by key-words that group sellers into categories defined by the marketplace when adding a new seller through the [Configure Seller Account](https://developers.vtex.com/vtex-rest-api/reference/sellers#putupsertseller) endpoint. It is possible to filter sellers by group in the Seller Management page in your VTEX Admin. Know more about groups through our [Seller Management](https://help.vtex.com/en/tutorial/gerenciamento-de-sellers-beta--6eEiOISwxuAWJ8w6MtK7iv#groups) documentation."
},
"user": {
"type": "string",
"title": "user",
"description": "Username, if you are using a hub to integrate with the external seller.",
"default": "integrationHubUserName",
"nullable": true
},
"password": {
"type": "string",
"title": "password",
"description": "User password, if you are using a hub to integrate with the external seller.",
"default": "integrationHubPassword",
"nullable": true
},
"catalogSystemEndpoint": {
"type": "string",
"title": "Catalog System Endpoint schema",
"description": "URL of the endpoint of the seller's catalog. This field will only be displayed if the seller type is VTEX Store. The field format will be as follows: `https://{sellerName}.vtexcommercestable.com.br/api/catalog_system/`.",
"default": "https://pedrostore.vtexcommercestable.com.br/api/catalog_system/"
},
"trustPolicy": {
"type": "string",
"title": "Trust Policy",
"description": " the marketplace must first allow VTEX to share clients’ email addresses with the seller. To do so, it is necessary to set 'AllowEmailSharing' as the value for the TrustPolicy field.",
"default": "AllowEmailSharing"
},
"score": {
"type": "number",
"title": "Score",
"description": "Score attributed to this seller.",
"default": 0.0
}
},
"example": {
"id": "testeMARCUS123",
"name": "qamarketplace",
"isActive": true,
"fulfillmentEndpoint": "http://fulfillment.vtexcommerce.com.br/api/fulfillment?an=parceiro01",
"allowHybridPayments": false,
"trustPolicy": "AllowEmailSharing",
"user": "integrationHubUserName",
"password": "integrationHubPassword",
"taxCode": "34444",
"email": "vtexqa1@vtex.com.br",
"description": "Seller A, from the B industry.",
"sellerCommissionConfiguration": {
"productCommissionPercentage": 3.0,
"freightCommissionPercentage": 4.0,
"categoriesCommissionConfiguration": []
},
"isBetterScope": false,
"sellerType": 1,
"availableSalesChannels": [
{
"isSelected": true,
"id": 1,
"name": "Loja Principal"
},
{
"isSelected": true,
"id": 2,
"name": "Terceira"
},
{
"isSelected": true,
"id": 3,
"name": "Marketplaces"
}
],
"CSCIdentification": "SampleCSCIdentification123",
"account": "parceiro01",
"channel": "SampleChannel",
"salesChannel": "SampleSalesChannel",
"isVtex": true,
"score": 0.0,
"exchangeReturnPolicy": "1",
"deliveryPolicy": "3",
"securityPrivacyPolicy": null,
"catalogSystemEndpoint": "https://pedrostore.vtexcommercestable.com.br/api/catalog_system/",
"fulfillmentSellerId": "seller1",
"groups": [
{
"groups": [
{
"id": "8d845239bf1448dc8bc3ed3121837511",
"name": "long tail"
},
{
"id": "b9bcd348ab9c4cec8285ff9485c27a72",
"name": "franchise accounts"
}
]
}
]
}
},
"SellerCommissionConfiguration": {
"title": "Seller Commission Configuration",
"description": "Configuration details for seller commissions. This includes the product commission percentage, freight commission percentage, and categories commission configuration.",
"required": [
"productCommissionPercentage",
"freightCommissionPercentage",
"categoriesCommissionConfiguration"
],
"type": "object",
"properties": {
"productCommissionPercentage": {
"type": "number",
"description": "Percentage of the comission applied to the product in decimals.",
"default": 9.85
},
"freightCommissionPercentage": {
"type": "number",
"description": "Percentage of the comission applied to the freight in decimals.",
"default": 2.43
},
"categoriesCommissionConfiguration": {
"type": "array",
"description": "Array containing the commission configurations for different categories. Each item in the array specifies the category and the commission percentage applied to it.",
"items": {
"type": "object",
"description": "Object representing the commission configuration for a specific category. This includes the category identifier or name and the commission percentage applied to it.",
"properties": {
"category": {
"type": "string",
"description": "Category identifier or name."
},
"commission": {
"type": "number",
"description": "Percentage of the commission applied to the category in decimal format.",
"example": 0.15
}
},
"required": [
"category",
"commission"
]
},
"default": []
}
},
"example": {
"productCommissionPercentage": 3.0,
"freightCommissionPercentage": 4.0,
"categoriesCommissionConfiguration": []
}
},
"AvailableSalesChannel": {
"title": "Available Sales Channel",
"description": "Details of a sales channel available for the product. This includes whether the sales channel is selected, its ID, and its name.",
"required": [
"isSelected",
"id",
"name"
],
"type": "object",
"properties": {
"isSelected": {
"type": "boolean",
"description": "Flag defining if the sales channel (or [trade policy](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV#master-data)) is selected or not.",
"default": true
},
"id": {
"type": "integer",
"description": "Sales Channel's ID.",
"default": 1
},
"name": {
"type": "string",
"description": "Name of the Sales Channel.",
"default": "Main Store"
}
},
"example": {
"isSelected": true,
"id": 1,
"name": "Loja Principal"
}
},
"Groups": {
"title": "groups",
"description": "Array of groups attached to the seller. Groups are defined by key-words that group sellers into categories defined by the marketplace when adding a new seller through the [Configure Seller Account](https://developers.vtex.com/vtex-rest-api/reference/sellers#putupsertseller) endpoint. It is possible to filter sellers by group in the Seller Management page in your VTEX Admin. Know more about groups through our [Seller Management](https://help.vtex.com/en/tutorial/gerenciamento-de-sellers-beta--6eEiOISwxuAWJ8w6MtK7iv#groups) documentation.",
"required": [
"groups"
],
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Group's unique identifier code.",
"default": "8d845239bf1448dc8bc3ed3121837511"
},
"name": {
"type": "string",
"description": "Name of the tag chosen to identify the group.",
"default": "franchise Accounts"
}
},
"example": {
"groups": [
{
"id": "8d845239bf1448dc8bc3ed3121837511",
"name": "long tail"
},
{
"id": "b9bcd348ab9c4cec8285ff9485c27a72",
"name": "franchise accounts"
}
]
}
},
"Sku2": {
"title": "Sku",
"description": "Details of the SKU (Stock Keeping Unit) associated with the product. This includes the SKU ID, EAN ID, reference ID, complete name, short name, active status, main image, and offers.",
"required": [
"SkuId",
"EanId",
"RefId",
"NameComplete",
"Name",
"IsActive",
"MainImage",
"Offers"
],
"type": "object",
"properties": {
"SkuId": {
"type": "string",
"description": "SKU's unique identifier number.",
"default": "1070268"
},
"EanId": {
"type": "string",
"nullable": true,
"description": "EAN's unique identifier number.",
"default": "768655"
},
"RefId": {
"type": "string",
"nullable": true,
"description": "SKU's Reference ID.",
"default": "1234"
},
"NameComplete": {
"type": "string",
"description": "Complete name of the SKU.",
"default": "Name of the Product - 123 Color: Black."
},
"Name": {
"type": "string",
"description": "Summarized name of the SKU.",
"default": "Color: Black"
},
"IsActive": {
"type": "boolean",
"description": "Whether the SKU is active in the sales channel (true), or not (false).",
"default": true
},
"MainImage": {
"type": "object",
"items": {
"$ref": "#/components/schemas/MainImage"
},
"description": "Main image's information."
},
"Offers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Offer"
},
"description": "Array with offers."
}
},
"example": {
"SkuId": "1070268",
"EanId": null,
"RefId": null,
"NameComplete": "Produto Teste 04 - Preto - 40 Cor:Preto",
"Name": "Cor:Preto",
"IsActive": true,
"MainImage": {
"ImageId": "53878805",
"ImageLabel": null,
"ImageTag": "",
"ImagePath": "~/arquivos/ids/53878805-#width#-#height#/image-8b4364782e664d76a6ebc8702008e478.jpg",
"IsMain": true,
"IsZoomSize": true,
"ImageText": "image-8b4364782e664d76a6ebc8702008e478",
"LastModified": "2021-04-06T03:01:30.747"
},
"Offers": [
{
"SellerId": "1",
"SellerSkuId": "1070268",
"OffersPerSalesChannel": [
{
"SaleChannel": 1,
"Price": 0,
"ListPrice": 0,
"PriceWithoutDiscount": 0,
"AvailableQuantity": 0
}
],
"AvailableSalesChannels": null
},
{
"SellerId": "madesacms",
"SellerSkuId": "3298",
"OffersPerSalesChannel": [
{
"SaleChannel": 0,
"Price": 1200,
"ListPrice": 1200,
"PriceWithoutDiscount": 1200,
"AvailableQuantity": 10000000
}
],
"AvailableSalesChannels": null
}
]
}
},
"MainImage": {
"title": "MainImage",
"description": "Details of the main image associated with the product. This includes the image's ID, label, tag, path, and other attributes indicating its main and zoom size status, as well as additional text and last modification date.",
"required": [
"ImageId",
"ImageLabel",
"ImageTag",
"ImagePath",
"IsMain",
"IsZoomSize",
"ImageText",
"LastModified"
],
"type": "object",
"properties": {
"ImageId": {
"type": "string",
"description": "Code identifying the image's file.",
"default": "53878805"
},
"ImageLabel": {
"type": "string",
"nullable": true,
"description": "Image's label.",
"default": "Image 1"
},
"ImageTag": {
"type": "string",
"description": "HTML tag for the selected image.",
"default": "![\"Image](\"~/archives/ids/155411-#width#-#height#/Webp.net-resizeimage.jpg\")
"
},
"ImagePath": {
"type": "string",
"description": "Path for the image's file.",
"default": "~/archives/ids/155411-#width#-#height#/Webp.net-resizeimage.jpg"
},
"IsMain": {
"type": "boolean",
"description": "Whether the image is the main one or not.",
"default": true
},
"IsZoomSize": {
"type": "boolean",
"description": "If zoom can be applied to the image.",
"default": true
},
"ImageText": {
"type": "string",
"description": "Alt text for the image.",
"default": "Image name and description"
},
"LastModified": {
"type": "string",
"description": "Date of the last changed made to the offer.",
"default": "2021-05-06T21:37:24.262529"
}
},
"example": {
"ImageId": "53878805",
"ImageLabel": null,
"ImageTag": "",
"ImagePath": "~/arquivos/ids/53878805-#width#-#height#/image-8b4364782e664d76a6ebc8702008e478.jpg",
"IsMain": true,
"IsZoomSize": true,
"ImageText": "image-8b4364782e664d76a6ebc8702008e478",
"LastModified": "2021-04-06T03:01:30.747"
}
},
"Offer": {
"title": "Offer",
"description": "Details of an offer provided by a seller. This includes the seller's identification, SKU, offers per sales channel, and available sales channels.",
"required": [
"SellerId",
"SellerSkuId",
"OffersPerSalesChannel",
"AvailableSalesChannels"
],
"type": "object",
"properties": {
"SellerId": {
"type": "string",
"description": "ID of the seller in the marketplace. This ID must be created by the marketplace.",
"default": "1"
},
"SellerSkuId": {
"type": "string",
"description": "A string that identifies the SKU in the seller. This is the ID that the marketplace will use for future references to this SKU, such as price and inventory notifications.",
"default": "1070268"
},
"OffersPerSalesChannel": {
"type": "array",
"description": "Each element in the array corresponds to an offer in a specific sales channel.",
"items": {
"$ref": "#/components/schemas/OffersPerSalesChannel"
}
},
"AvailableSalesChannels": {
"type": "string",
"nullable": true,
"description": "The sales channel (or [trade policy](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV#master-data)) ID in which the SKU is available.",
"default": "1"
}
},
"example": {
"SellerId": "1",
"SellerSkuId": "1070268",
"OffersPerSalesChannel": [
{
"SaleChannel": 1,
"Price": 0,
"ListPrice": 0,
"PriceWithoutDiscount": 0,
"AvailableQuantity": 0
}
],
"AvailableSalesChannels": null
}
},
"OffersPerSalesChannel": {
"title": "OffersPerSalesChannel",
"description": "Details of offers available per sales channel. This includes pricing information and available quantity specific to each sales channel.",
"required": [
"SaleChannel",
"Price",
"ListPrice",
"PriceWithoutDiscount",
"AvailableQuantity"
],
"type": "object",
"properties": {
"SaleChannel": {
"type": "integer",
"description": "The sales channel (or [trade policy](https://help.vtex.com/en/tutorial/como-funciona-uma-politica-comercial--6Xef8PZiFm40kg2STrMkMV#master-data)) of the SKU.",
"default": 1
},
"Price": {
"type": "integer",
"description": "SKU's price.",
"default": 1300
},
"ListPrice": {
"type": "integer",
"description": "SKU's suggested selling price.",
"default": 1200
},
"PriceWithoutDiscount": {
"type": "integer",
"description": "SKU's price without discount applied.",
"default": 1400
},
"AvailableQuantity": {
"type": "integer",
"description": "Available SKU stock quantity.",
"default": 30
}
},
"example": {
"SaleChannel": 1,
"Price": 0,
"ListPrice": 0,
"PriceWithoutDiscount": 0,
"AvailableQuantity": 0
}
},
"responseGetMatchedOffersList": {
"type": "array",
"description": "Response with the list of offers available on the Marketplace.",
"items": {
"type": "object",
"description": "Array of SKUs in the offer.",
"properties": {
"LastModified": {
"type": "string",
"description": "Last date the offer was modified.",
"example": "2021-05-06T21:37:24.262529"
},
"ProductId": {
"type": "string",
"description": "A string that identifies the seller's product. This is the ID that the marketplace will use for all references to this product.",
"example": "941947"
},
"CategoryId": {
"type": "integer",
"description": "Offer's Category ID that the product belongs to, configured in the Catalog. It should be the marketplace's category chosen for the offer to be matched with.",
"example": 1563
},
"BrandId": {
"type": "integer",
"description": "Offer's brand ID that the product belongs to, configured in the Catalog. It should be the marketplace's brand chosen for the offer to be matched with.",
"example": 2004291
},
"ProductName": {
"type": "string",
"description": "Name of the offer's product.",
"example": "Name of the Product - 123"
},
"Skus": {
"type": "array",
"description": "A list of SKUs (Stock Keeping Units) associated with the product. Each SKU contains detailed information about specific variants of the product, such as color, size, and other specifications.",
"items": {
"$ref": "#/components/schemas/Sku2"
}
}
}
}
},
"responseGetMatchedOffersDataBySKU": {
"description": "Array of matched offers data by SKU.",
"type": "array",
"items": {
"type": "object",
"description": "Schema for individual offer data.",
"properties": {
"productId": {
"type": "string",
"description": "The unique identifier for the product.",
"example": "1561208"
},
"skuId": {
"type": "string",
"description": "The unique identifier for the product SKU.",
"example": "1559161"
},
"nameComplete": {
"type": "string",
"description": "The complete name of the product.",
"example": "Blusa Cardigan Manga Longa Vestem - Feminina - CINZA G"
},
"mainImage": {
"type": "object",
"description": "Schema for the main product image.",
"required": [
"imagePath"
],
"properties": {
"imagePath": {
"type": "string",
"description": "The file path of the main product image.",
"example": "~/arquivos/ids/8567753-#width#-#height#/image-05b40d3167b5b7ed42285124f6862f12.jpg"
}
}
},
"sellersOffers": {
"type": "array",
"description": "Array of offers from different sellers.",
"items": {
"type": "object",
"description": "Schema for individual seller offer data.",
"properties": {
"sellerId": {
"type": "string",
"description": "The unique identifier for the seller.",
"example": "1"
},
"sellerSkuId": {
"type": "string",
"description": "The unique identifier for the seller's SKU.",
"example": "1559161"
},
"salesChannelOffer": {
"type": "array",
"description": "Array of offers on different sales channels from the same seller.",
"items": {
"type": "object",
"description": "Schema for individual sales channel offer data.",
"properties": {
"salesChannelId": {
"type": "string",
"description": "The unique identifier for the sales channel.",
"example": "1"
},
"salesChannelName": {
"type": "string",
"description": "The name of the sales channel.",
"example": "Principal"
},
"price": {
"type": "number",
"description": "The offer price.",
"example": 0.0
},
"listPrice": {
"type": "number",
"description": "The list price of the product.",
"example": 0.0
},
"priceWithoutDiscount": {
"type": "number",
"description": "The offer price without any discount.",
"example": 0.0
},
"availableQuantity": {
"type": "integer",
"description": "The available quantity of the product.",
"example": 8
}
}
}
}
}
}
}
}
}
},
"responseGetMatchedOffersDataByProductId": {
"type": "array",
"description": "Array of matched offers data by product ID.",
"items": {
"type": "object",
"description": "Schema for individual offer data.",
"properties": {
"productId": {
"type": "string",
"description": "The unique identifier for the product.",
"example": "1561208"
},
"skuId": {
"type": "string",
"description": "The unique identifier for the product SKU.",
"example": "1559161"
},
"nameComplete": {
"type": "string",
"description": "The complete name of the product.",
"example": "Blusa Cardigan Manga Longa Vestem - Feminina - CINZA G"
},
"mainImage": {
"type": "object",
"description": "Schema for the main product image.",
"required": [
"imagePath"
],
"properties": {
"imagePath": {
"type": "string",
"description": "The file path of the main product image.",
"example": "~/arquivos/ids/8567753-#width#-#height#/image-05b40d3167b5b7ed42285124f6862f12.jpg"
}
}
},
"sellersOffers": {
"type": "array",
"description": "Array of offers from different sellers.",
"items": {
"type": "object",
"description": "Schema for individual seller offer data.",
"properties": {
"sellerId": {
"type": "string",
"description": "The unique identifier for the seller.",
"example": "1"
},
"sellerSkuId": {
"type": "string",
"description": "The unique identifier for the seller's SKU.",
"example": "1559161"
},
"salesChannelOffer": {
"type": "object",
"description": "Schema for the offer data on a specific sales channel.",
"properties": {
"salesChannelId": {
"type": "string",
"description": "The unique identifier for the sales channel.",
"example": "1"
},
"salesChannelName": {
"type": "string",
"description": "The name of the sales channel.",
"example": "Principal"
},
"price": {
"type": "number",
"description": "The offer price.",
"example": 0.0
},
"listPrice": {
"type": "number",
"description": "The list price of the product.",
"example": 0.0
},
"priceWithoutDiscount": {
"type": "number",
"description": "The offer price without any discount.",
"example": 0.0
},
"availableQuantity": {
"type": "integer",
"description": "The available quantity of the product.",
"example": 0
}
}
}
}
}
}
}
}
}
},
"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": {
"isBetterScope": {
"name": "isBetterScope",
"in": "query",
"description": "The flag `isBetterScope` is used by the VTEX Checkout to simulate shopping carts, products, and shipping only in sellers with the field set as `true`, avoiding performance issues. When used as a query param, `isBetterScope` filters sellers that have the flag set as `true` or `false`.",
"required": false,
"schema": {
"type": "boolean",
"default": false
}
},
"isConnected": {
"name": "isConnected",
"in": "query",
"description": "Query param that enables results to be filter by whether the seller lead is already connected to the marketplace or not.",
"required": true,
"style": "form",
"explode": true,
"schema": {
"type": "string",
"default": ""
}
},
"search": {
"name": "search",
"in": "query",
"description": "Custom search field, that filters sellers invited by specific marketplace operator's email.",
"required": true,
"style": "form",
"explode": true,
"schema": {
"type": "string",
"default": "user email"
}
},
"status": {
"name": "status",
"in": "query",
"description": "Seller Lead's status. Includes `accepted`, `connected` or `invited`.",
"required": true,
"style": "form",
"explode": true,
"schema": {
"type": "string",
"default": "invited"
}
},
"orderBy": {
"name": "orderBy",
"in": "query",
"description": "Query param determining how data will be ordered in the response, ordering by name or ID in descending our ascending order. Includes the following values: \n\n`namesort` = desc/asc \n\n`idsort` = desc/asc",
"required": true,
"style": "form",
"explode": true,
"schema": {
"type": "string"
}
},
"limit": {
"name": "limit",
"in": "query",
"description": "This field determines the limit used to retrieve the list of sellers. The response includes objects until the value inputted here. ",
"required": true,
"style": "form",
"explode": true,
"schema": {
"type": "integer",
"default": 15
}
},
"offset": {
"name": "offset",
"in": "query",
"description": "This field determines the limit used to retrieve the list of sellers. The response includes objects starting `from` the value inputted here.",
"required": true,
"style": "form",
"explode": true,
"schema": {
"type": "integer",
"default": 0
}
},
"categoryId": {
"name": "categoryId",
"in": "path",
"description": "ID of the category in which the comission was applied",
"required": true,
"style": "simple",
"schema": {
"type": "string",
"default": "6"
}
},
"sellerLeadId": {
"name": "sellerLeadId",
"in": "path",
"description": "ID of the Seller Lead invited to the marketplace.",
"required": true,
"style": "simple",
"schema": {
"type": "string"
}
},
"from": {
"name": "from",
"in": "query",
"description": "The start number of pagination, being `0` the default value.",
"required": false,
"schema": {
"type": "number",
"default": 0
}
},
"to": {
"name": "to",
"in": "query",
"description": "The end number of pagination, being `100` the default value.",
"required": false,
"schema": {
"type": "number",
"default": 100
}
},
"keyword": {
"name": "keyword",
"in": "query",
"description": "Search sellers by a keyword in `sellerId` or `sellerName`.",
"required": false,
"schema": {
"type": "string",
"default": "keyword"
}
},
"integration": {
"name": "integration",
"in": "query",
"description": "Filters sellers by the name of who made the integration, if VTEX or an external hub. The possible values for VTEX integrations are: `vtex-sellerportal`, `vtex-seller` and `vtex-franchise`.",
"required": false,
"schema": {
"type": "string",
"default": "vtex-seller"
}
},
"group": {
"name": "group ",
"in": "query",
"description": "Groups are defined by keywords that group sellers into categories defined by the marketplace.",
"required": false,
"schema": {
"type": "string",
"default": "Group"
}
},
"isActive": {
"name": "isActive",
"in": "query",
"description": "Enables to filter sellers that are active (`true`) or unactive (`false`) in the marketplace.",
"required": false,
"schema": {
"type": "boolean",
"default": false
}
},
"accountName": {
"name": "accountName",
"in": "path",
"required": true,
"description": "Name of the VTEX account that belongs to the marketplace. The notification will be posted into this account.",
"schema": {
"type": "string",
"example": "apiexamples"
}
},
"contentType": {
"name": "Content-Type",
"in": "header",
"description": "Type of the content being sent.",
"required": true,
"style": "simple",
"schema": {
"type": "string",
"default": "application/json"
}
},
"environment": {
"name": "environment",
"in": "path",
"required": true,
"description": "Environment to use. Used as part of the URL.",
"schema": {
"type": "string",
"default": "vtexcommercestable"
}
},
"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"
}
},
"sellerId": {
"name": "sellerId",
"in": "path",
"description": "A string that identifies the seller in the marketplace. This ID must be created by the marketplace and informed to the seller before the integration is built.",
"required": true,
"style": "simple",
"schema": {
"type": "string",
"example": "seller123"
}
},
"skuId": {
"name": "skuId",
"in": "path",
"description": "A string that identifies the seller's SKU that suffered the change. This is the ID that the marketplace will use for all references to this SKU, such as price and inventory notifications.",
"required": true,
"style": "simple",
"schema": {
"type": "string",
"example": "1234"
}
},
"sort": {
"name": "sort",
"in": "query",
"description": "Criteria used to sort the list of offers. For sorting values in ascending order, use `asc`, while for descending order, use `desc`. To fill in the field, insert the sorting criteria, followed by 'asc', or 'desc', separated by a comma. You can sort by the following criteria: \n\n- **price:** sorts offers by price. *Ascending* goes from lowest to highest price, while *Descending* goes from highest to lowest price. \n\n- **name:** sorts offers by *productName*, in alphabetical order. *Ascending* goes from *A* to *Z*, while *Descending* goes from *Z* to *A*. \n\n- **availability:** availability in the sales channel (sc). The default value is 1. \n\nEx. sort=availability,desc \n\nEx. sort=name,asc \n\nEx. price,desc",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "string",
"example": "availability,desc"
}
},
"rows": {
"name": "rows",
"in": "query",
"description": "Number of rows included in the response. Each row corresponds to a single offer. The default amount of rows in the response is 1, and the maximum amount is 50. To have more than one offer listed in the response, please add the `rows` parameter with a number greater than 1.",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "integer",
"example": 20
}
},
"start": {
"name": "start",
"in": "query",
"description": "Number corresponding to the row from which the offer list will begin, used for pagination. Filters the list of offers by retrieving the offers starting from the row defined. The default value is 0, if the param is not included in the call.",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "integer",
"default": 0
}
},
"fq": {
"name": "fq",
"in": "query",
"description": "This filter query can be used to filter offers by the criteria described below. It should be filled in by following the format: `fq={{criteriaName}}:{{criteriaValue}}`. \n\n- **productId:** integer of the product ID \n\n- **productName:** string of the product's name \n\n- **skuId:** integer of the SKU ID \n\n- **eanId:** string of the EAN ID \n\n- **refId:** string of the Ref ID \n\n- **categoryId:** integer of the category ID \n\n- **brandId:** integer of the brand ID \n\n- **sellerId:** string of the seller ID \n\n- **sc:** integer of the sales channel's ID (trade policy in VTEX) \n\nEx: skuId:172 \n\nEx: categoryId:13 \n\nEx. productName:Product example-123",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "string",
"example": "skuId:172"
}
},
"productId": {
"name": "productId",
"in": "path",
"description": "A string that identifies the seller's product. This is the ID that the marketplace will use for all references to this product, such as price and inventory notifications.",
"required": true,
"style": "simple",
"schema": {
"type": "string",
"example": "123456"
}
},
"an": {
"name": "an",
"in": "query",
"description": "Marketplace's account name, the same one inputted on the endpoint's path.",
"required": true,
"style": "form",
"explode": true,
"schema": {
"type": "string",
"default": "apiexamples"
}
},
"sc": {
"name": "sc",
"in": "query",
"description": "Sales channel (or [trade policy](https://help.vtex.com/en/tutorial/how-trade-policies-work--6Xef8PZiFm40kg2STrMkMV)) associated to the seller account created.",
"required": false,
"style": "form",
"explode": true,
"schema": {
"type": "string",
"default": "1"
}
},
"sellerType": {
"name": "sellerType",
"in": "query",
"description": "Filters sellers by their type, which can be regular seller (`1`) or whitelabel seller (`2`).",
"required": false,
"schema": {
"type": "integer",
"default": 1
}
},
"isVtex": {
"name": "isVtex",
"in": "query",
"description": "When set as `true`, the list returned will be of sellers who have a VTEX store configured. When set as `false`, the list will be of sellers who do not have a VTEX store configured.",
"required": false,
"schema": {
"type": "boolean",
"default": false
}
}
}
},
"tags": [
{
"name": "Sellers"
},
{
"name": "Seller Invite"
},
{
"name": "Seller Commissions"
},
{
"name": "Notification"
},
{
"name": "Matched Offers"
},
{
"name": "Sales Channel Mapping"
}
]
}