The VTEX Suggestions API manages product suggestions from sellers to marketplace operators. It handles the proposal and approval workflow for sellers suggesting new products or modifications to existing marketplace catalog items, streamlining catalog expansion in multi-seller environments.
openapi: 3.0.0
info:
title: VTex Suggestions
description: "\r\nThe **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"
contact: {}
version: '1.0'
servers:
- url: https://api.vtex.com/{accountName}
description: Suggestions Server URL.
variables:
accountName:
description: Name of the VTEX account. Used as part of the URL.
default: apiexamples
paths:
/suggestions/configuration/autoapproval/toggle:
get:
tags:
- SKU Approval Settings
summary: VTex Get autoApprove Status in Account Settings
description: |-
This endpoint can be used to check whether the autoapprove setting is active or not, for a specific seller.
If the response is `true`, the autoapprove setting is active. If the response is `false`, it is inactive.
operationId: GetautoApprovevaluefromconfig
parameters:
- name: sellerId
in: query
description: A string that identifies the seller in the marketplace. This ID must be created by the marketplace.
required: true
style: form
schema:
type: string
default: seller123
- name: accountName
in: path
required: true
description: Name of the VTEX account that belongs to the marketplace. All data extracted, and changes added will be posted into this account.
schema:
type: string
default: apiexamples
- 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
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
Enabled:
type: boolean
description: If the auto-approve setting is active for a given seller (`true`) or not (`false`).
example:
Enabled: false
deprecated: false
put:
tags:
- SKU Approval Settings
summary: VTex Activate autoApprove in Marketplace's Account
description: |-
This endpoint enables the autoapprove rule to a marketplace's whole Received SKUs module. Once enabling the rule, received SKUs will be automatically approved on your store, regardless of the seller.
For the autoapprove rule to work as expected, the approval [Matcher score](https://help.vtex.com/en/tutorial/entendendo-a-pontuacao-do-vtex-matcher--tutorials_424) should be set up as 80 (default value), but you can configure a different number through the field `Score` in [Save Account's Approval Settings](https://developers.vtex.com/vtex-rest-api/reference/saveaccountconfig).
operationId: Saveautoapproveforaccount
parameters:
- name: accountName
in: path
required: true
description: Name of the VTEX account that belongs to the marketplace. All data extracted, and changes added will be posted into this account.
schema:
type: string
default: apiexamples
- 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
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SaveautoapproveforaccountRequest'
example:
Enabled: true
required: true
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
type: object
properties:
Enabled:
type: boolean
description: If the auto-approve setting is active (`true`) or not (`false`).
example:
Enabled: false
deprecated: false
/suggestions/configuration:
get:
tags:
- SKU Approval Settings
summary: VTex Get Account's Approval Settings
description: |-
This endpoint retrieves the current approval settings of a marketplace's Received SKUs module. Its response includes:
- `Score`: Matcher scores for approving and rejecting SKUs received from sellers.
- `Matchers`: All Matchers configured on the marketplace, and their respective details.
- `SpecificationsMapping`: Mapping of product and SKU specifications, per seller.
- `MatchFlux`: This field determines the type of approval configuration applied to SKUs received from a seller.
The possible values include:
-`default`, where the Matcher reviews the SKU, and approves it based on its score.
-`manual`, for manual approvals through the Received SKU UI, or Match API.
-`autoApprove`, for every SKU received from a given seller to be approved automatically, regardless of their Matcher Score.
operationId: Getaccountconfig
parameters:
- name: accountName
in: path
required: true
description: Name of the VTEX account that belongs to the marketplace. All data extracted, and changes added will be posted into this account.
schema:
type: string
default: apiexamples
- 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
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
type: object
properties:
Score:
type: object
description: Matcher scores for approving and rejecting SKUs received from sellers.
Matchers:
type: array
description: All Matchers configured on the marketplace, and their respective details.
Rules:
type: object
description: Items and products.
SpecificationsMapping:
type: array
description: Mapping of product and SKU specifications, per seller.
MatchFlux:
type: string
description: This field determines the type of approval configuration applied to SKUs received from a seller.
example:
Score:
Approve: 80
Reject: 30
Matchers:
- MatcherId: vtex-matcher
hook-base-address: http://portal.vtexinternal.com/api/ssm/hooks
IsActive: true
UpdatesNotificationEndpoint:
Description:
Rules:
Item: []
Product: []
SpecificationsMapping: []
MatchFlux: Default
deprecated: false
put:
tags:
- SKU Approval Settings
summary: VTex Save Account's Approval Settings
description: |-
Marketplaces use this endpoint to create or update approval settings on their Received SKUs module.
The request includes all the details necessary to implement the chosen approval settings.
operationId: Saveaccountconfig
parameters:
- name: accountName
in: path
required: true
description: Name of the VTEX account that belongs to the marketplace. All data extracted, and changes added will be posted into this account.
schema:
type: string
default: apiexamples
- 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
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SaveaccountconfigRequest'
required: true
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
type: object
example:
Score:
Approve: 80
Reject: 30
Matchers:
- MatcherId: vtex-matcher
hook-base-address: http://simple-suggestion-matcher.vtex.com.br
IsActive: true
UpdatesNotificationEndpoint: notification.endpoint
Description: Note
Rules:
Item:
- 1
Product:
- Shirt
SpecificationsMapping:
- SellerId: Store1
Mapping:
Yellow: Light yellow
MatchFlux: AutoApprove
properties:
Score:
type: object
description: '[Matcher''s rates](https://help.vtex.com/en/tutorial/understanding-vtex-matcher-scoring) to approve or reject [received SKUs](https://help.vtex.com/en/tutorial/cataloging-received-skus--tutorials_396) sent by sellers.'
properties:
Approve:
type: integer
description: Score to approve SKUs sent by sellers.
Reject:
type: integer
description: Score to reject SKUs sent by sellers.
example:
Approve: 80
Reject: 30
Matchers:
type: array
description: '[Matchers](https://help.vtex.com/en/tutorial/understanding-vtex-matcher-scoring) configurations for approving and rejecting [received SKUs](https://help.vtex.com/en/tutorial/cataloging-received-skus--tutorials_396) sent by sellers.'
properties:
MatcherId:
type: string
description: Identifies the matching entity. It can be either [VTEX's matcher](https://help.vtex.com/en/tutorial/understanding-vtex-matcher-scoring), or an external matcher.
hook-base-address:
type: string
description: The given Matcher's URL.
IsActive:
type: boolean
description: Whether the matcher is active in the account (`true`), or not (`false`).
UpdatesNotificationEndpoint:
type: string
description: The [received SKUs](https://help.vtex.com/en/tutorial/cataloging-received-skus--tutorials_396) module calls this endpoint for matcher's suggestions updates.
Description:
type: string
description: The note inserted on the request body.
Rules:
type: object
description: Items and products that belong to sellers.
properties:
Item:
type: array
description: SKUs' ID.
items:
type: integer
description: SKU ID.
Product:
type: array
description: Product's name.
items:
type: string
description: Product name.
SpecificationsMapping:
type: array
description: This attribute maps product and SKU's specifications between the marketplace and the seller.
properties:
SellerId:
type: string
description: The Seller ID.
Mapping:
type: object
description: The attributes and values mapped between the marketplace and the seller.
MatchFlux:
type: string
description: |-
Type of approval configuration that apply to received SKUs sent by sellers. The possible values are:
`default`: the matcher approves the SKU.
`manual`: manual SKU's approvals.
`AutoApprove`: automatic SKU's approvals.
deprecated: false
/suggestions/configuration/account/config:
get:
tags:
- SKU Approval Settings
summary: VTex Get Account's Matcher Settings
description: |-
This endpoint will be used by the marketplace to query the matcher's current approval settings on their incoming SKUs module. If the account has no matcher configured, the response will be `404 Not Found`.
For account approval configuration information, with response including specification information, see [Get Account Approval Settings](https://developers.vtex.com/docs/api-reference/marketplace-apis- suggestions#get-/suggestions /configuration) terminal.
The [VTEX matcher](https://help.vtex.com/pt/tutorial/entendendo-a-punctuacao-do-vtex-matcher--tutorials_424) is a tool used by marketplaces to evaluate SKUs corresponding to information from an advertisement of the seller, with those of items already present in the marketplace catalog.
operationId: Getmatchconfig
parameters:
- name: accountName
in: path
required: true
description: Name of the VTEX account that belongs to the marketplace. All data extracted, and changes added will be posted into this account.
schema:
type: string
default: apiexamples
- 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
responses:
'200':
description: OK
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/responseGetAccountsMatcherSettings'
example:
score:
approve: 85
pending: 31
reject: 30
matchers:
- matcherId: example-matcher
hook-base-address: http://portal.vtexinternal.com.br/api/u90/hooks
isActive: true
updatesNotificationEndpoint:
description:
rules:
item: []
product: []
specificationsMapping: []
matchFlux: Default
deprecated: false
/suggestions/configuration/seller/{sellerId}:
get:
tags:
- SKU Approval Settings
summary: VTex Get Seller's Approval Settings
description: |-
This endpoint retrieves the current Received SKUs approval settings applied to a specific seller. Its response includes:
- `sellerId`: A string that identifies the seller in the marketplace.
- `accountId`: Marketplace’s account ID.
- `accountName`: Marketplace’s account name.
- `mapping`: Mapping of SKU and product Specifications.
- `matchFlux`: This field determines the type of approval configuration applied to SKUs received from a seller.
The possible values include:
-`default`, where the Matcher reviews the SKU, and approves it based on its score.
-`manual`, for manual approvals through the Received SKU UI and Match API.
-`autoApprove`, for every SKU received from a given seller to be approved automatically , regardless of the Matcher Score.
operationId: Getselleraccountconfig
parameters:
- name: accountName
in: path
required: true
description: Name of the VTEX account that belongs to the marketplace. All data extracted, and changes added will be posted into this account.
schema:
type: string
default: apiexamples
- 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: 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
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/responseGetSellersApprovalSettings'
example:
sellerId: sellerexample
accountId: d74dau71f-325a-4463-bd53-ae8b0453186ca
accountName: marketplaceexample
mapping:
defaultColor: white /black
searchColor: color1, color2
color1: black
color2: white
color: black
size: EUR44
matchFlux: default
deprecated: false
put:
tags:
- SKU Approval Settings
summary: VTex Save Seller's Approval Settings
description: |-
Marketplaces use this endpoint to create or update approval settings to a specific seller, on the Received SKUs module.
The request includes all the details necessary to implement the chosen approval settings.
operationId: Putselleraccountconfig
parameters:
- name: accountName
in: path
required: true
description: Name of the VTEX account that belongs to the marketplace. All data extracted, and changes added will be posted into this account.
schema:
type: string
default: apiexamples
- 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: 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
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PutselleraccountconfigRequest'
example:
sellerId: 1a
mapping:
matchFlux: Default
required: true
responses:
'200':
description: OK
headers: {}
deprecated: false
/suggestions/configuration/autoapproval/toggle/seller/{sellerId}:
put:
tags:
- SKU Approval Settings
summary: VTex Activate autoApprove Setting for a Seller
description: This endpoint enables the auto approve setting to received SKUs from a specific seller. Be aware that once enabling the rule through this request, all received SKUs from that seller will be automatically approved on your store, regardless of the Matcher Score.
operationId: Saveautoapproveforaccountseller
parameters:
- name: accountName
in: path
required: true
description: Name of the VTEX account that belongs to the marketplace. All data extracted, and changes added will be posted into this account.
schema:
type: string
default: apiexamples
- 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: 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
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SaveautoapproveforaccountsellerRequest'
example:
Enabled: true
required: true
responses:
'200':
description: OK
headers: {}
deprecated: false
/suggestions:
get:
tags:
- Get Suggestions
summary: VTex Get all SKU suggestions
description: |-
This endpoint retrieves a list of all SKUs sent by the seller for the Marketplace's approval. Marketplace operators should use this endpoint whenever they want to check the full list of received SKUs and their information.
Note that all the information sent by the seller will be in the [content] object. All remaining information in this endpoint's response is given by the Matcher.
Matcher rates received SKUs by correlating the data sent by sellers, to existing fields in the marketplace. The calculation of these scores determines whether the product has been:
`Approved`: score equal to or greater than 80 points.
`Pending`: from 31 to 79 points.
`Denied`: from 0 to 30 points.
Note that if the autoApprove setting is enabled, the SKUs will be approved, regardless of the Score.
operationId: Getsuggestions
parameters:
- name: accountName
in: path
required: true
description: Name of the VTEX account. Used as part of the URL
schema:
type: string
default: apiexamples
- name: q
in: query
description: This field allows you to customize your search. You can fill in this query param if you want to narrow down your search using the available filters on Received SKU modules.
required: false
style: form
explode: true
schema:
type: string
example: ''
- name: type
in: query
description: This field allows users to filter SKU suggestions, by searching only the new suggestions that were just sent, and suggestions that have already been sent, but were updated. Possible values for this field include `new` and `update`.
required: false
style: form
explode: true
schema:
type: string
example: new
- name: seller
in: query
description: A string that identifies the seller in the marketplace. This ID must be created by the marketplace and informed to the seller so it can call this endpoint.
required: false
style: form
explode: true
schema:
type: string
example: ''
- name: status
in: query
description: 'Narrow down you search, filtering by status. Values allowed on this field include: `accepted`, `pending` and `denied.`'
required: false
style: form
explode: true
schema:
type: string
example: accepted
- name: hasmapping
in: query
description: This field allows you to filter SKUs that have mapping or not. Insert `true` to filter SKUs that have mapping, or `false` to retrieve SKUs that aren't mapped.
required: false
style: form
explode: true
schema:
type: string
example: 'true'
- name: matcherid
in: query
description: Identifies the matching entity. It can be either VTEX's matcher, or an external matcher developed by partners, for example. The `matcherId`'s value can be obtained through the [Get SKU Suggestion by ID](https://developers.vtex.com/vtex-rest-api/reference/getsuggestion) endpoint.
required: false
style: form
explode: true
schema:
type: string
default: vtex-matcher
- name: _from
in: query
description: Define your pagination range, by adding the pagination starting value. Values should be bigger than 0, with a maximum of 50 records per page.
required: false
style: form
explode: true
schema:
type: integer
format: int32
minimum: 1
default: 1
- name: _to
in: query
description: Define your pagination range, by adding the pagination ending value. Values should be bigger tha
# --- truncated at 32 KB (86 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vtex/refs/heads/main/openapi/vtex-suggestions-openapi-original.yml