v46

latestOpenAPI 3.0.0raw.githubusercontent.com2026-04-201720164.6 KB

Match received SKUs

Match multiple received SKUs

Allows a marketplace to bulk approve, deny, or associate up to 25 received SKUs from sellers.

Through the actionName attribute, you can select the operation you want to apply to the received SKU. Actions include:

newproduct: Match the SKU as a new product.
skuassociation: Associate the received SKU to an existing SKU.
productassociation: Associate the received SKU to an existing product.
deny: Deny the received SKU.

Permissions

Any user or API key must have at least one of the appropriate License Manager resources to be able to successfully run this request. Otherwise, they will receive a status code 403 error. These are the applicable resources for this endpoint:

Product	Category	Resource
Channels	UI resources	Save suggestion rules
Suggestion	Suggestion resources	Main

There are no applicable predefined roles for this resource list. You must create a custom role and add at least one of the resources above in order to use this endpoint.

To learn more about machine authentication at VTEX, see Authentication overview.

❗ To prevent integrations from having excessive permissions, consider the best practices for managing API keys when assigning License Manager roles to integrations.

put/suggestions/matches/action/{actionName}

Path parameters

accountNamestring required

Example:apiexamples

Name of the VTEX account. Used as part of the URL

actionName'newproduct' | 'skuassociation' | 'productassociation' | 'deny' required

Example:newproduct

Operation to apply to received SKUs. Possible values include:

newproduct: match the SKU as a new product.
skuassociation: associate the received SKU to an existing SKU.
productassociation: associate the received SKU to an existing product.
deny: deny the received SKU.

Headers

Content-Typestring required

Describes the type of the content being sent.

Acceptstring required

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

Request body

itemIdstring required

This field can be used to link any string that identifies that SKU. Its most common use is the seller's SKU ID.

versionIdstring required

Whenever an SKU Suggestion is updated or changed, a new version of the original one is created. All versions are logged, so you can search for previous our current states of SKU suggestions. This field is the versionId associated to the version you choose to search for. You can get this field's value through the Get SKU Suggestion by ID. through the latestVersionId field.

matchIdstring required

Whenever an SKU suggestion is matched, it is associated to a unique ID. Fill in this field with the matchId you wish to filter by. The matchId's value can be obtained through the Get SKU Suggestion by ID endpoint.

matcherIdstring required

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

categoryIdinteger nullable required

Marketplace's Category ID that the product belongs to, configured in the Catalog. It should be the category chosen for the received SKU to be matched with. The categoryId is already mapped through the Get SKU Suggestion by ID. You can choose to keep the same suggested categoryID, or overwrite it with another value in this request. This field is nulled when the inserted value is 0.

brandIdinteger nullable

Marketplace's Brand ID that the product belongs to, configured in the Catalog. It should be the brand chosen for the received SKU to be matched with. The brandId is already mapped through the Get SKU Suggestion by ID. This field is nulled when the inserted value is 0, and is mandatory for the newproduct action.

skuRefstring nullable

Fill in this field on your request when the matched item is an SKU. This field is mandatory for the skuassociation action.

productRefstring nullable

Fill in this field on your request when the matched item is a product. This field is mandatory for the productassociation action.

sellerIdstring required

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.

Example request

[
  {
    "itemId": "1234567",
    "versionId": "v.2",
    "matchId": "vtex-matcher",
    "matcherId": "vtex-matcher",
    "categoryId": 12,
    "brandId": 1234567,
    "skuRef": "123 sku ref",
    "productRef": "123 product ref",
    "sellerId": "seller123"
  }
]

Response

matchIdstring

Unique identifier for the match operation, which can be used for tracking and auditing purposes.

matcherIdstring

Identifier for the matcher entity that performed the match. It can represent VTEX's internal matcher or an external matcher service.

sellerIdstring

Unique identifier of the seller who owns the SKU being matched.

itemIdstring

Unique identifier of the item (SKU) that was processed during the match operation.

isSuccessboolean

Indicates whether the match operation was successful. A value of true means the operation succeeded, while false indicates a failure.