The VTEX SKU Bindings API manages the relationships between SKUs in a marketplace and their corresponding seller SKUs. It provides binding, unbinding, and querying operations for marketplace-seller SKU associations, ensuring accurate product matching across the marketplace ecosystem.
openapi: 3.0.0
info:
title: VTex SKU Bindings API
contact: {}
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:
/catalog/pvt/skusellers/{skuId}:
get:
tags:
- SKU Bindings
summary: VTex Get SKU Bindings by SKU ID
description: "Retrieves SKU Bindings details by SKU ID.\r\n\r\n## Response body example\r\n\r\n```json\r\n[\r\n {\r\n \"Id\": 48,\r\n \"SellerId\": \"cosmetics1\",\r\n \"StockKeepingUnitId\": 1,\r\n \"SellerSkuId\": \"42\",\r\n \"IsActive\": true,\r\n \"LastUpdateDate\": \"2020-10-21T19:13:00.657\",\r\n \"SalesPolicy\": 0\r\n }\r\n]\r\n```"
operationId: GetbySkuId
parameters:
- 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: 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: skuId
in: path
description: SKU's unique identifier in the marketplace.
required: true
style: simple
schema:
type: string
example: '1'
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
description: Array containing objects with information about each SKU Binding.
items:
type: object
description: Object with information about an SKU Binding.
properties:
Id:
type: integer
format: int32
description: SKU Binding ID.
SellerId:
type: string
description: ID that identifies the seller in the marketplace. It can be the same as the seller name or a unique number. Check the **Sellers management** section in the Admin to get the correct ID.
StockKeepingUnitId:
type: integer
format: int32
description: SKU ID in the VTEX marketplace.
SellerSkuId:
type: string
description: SKU seller ID.
IsActive:
type: boolean
description: Defines if the SKU binding is active.
LastUpdateDate:
type: string
description: Date when the SKU binding was updated for the last time, in UTC format.
SalesPolicy:
type: integer
format: int32
description: Sales policy ID.
example:
- Id: 48
SellerId: cosmetics1
StockKeepingUnitId: 1
SellerSkuId: '42'
IsActive: true
LastUpdateDate: '2020-10-21T19:13:00.657'
SalesPolicy: 0
deprecated: false
/sku-binding/pvt/skuseller/admin:
get:
tags:
- SKU Bindings
summary: VTex Get SKU Bindings information
description: "Retrieves SKU Bindings administrative information using optional query params `sellerId`, `skuId`, `sellerSkuId` and `IsActive` to filter results and `size` to restrict the amount of results. \r\n\r\n > ℹ This path is an updated version of `/api/catalog_system/pvt/skuseller/admin`.\r\n\r\n## Response body example\r\n\r\n```json\r\n[\r\n {\r\n \"IsPersisted\": true,\r\n \"IsRemoved\": false,\r\n \"SkuSellerId\": 1,\r\n \"UpdateDate\": \"2019-12-04T01:56:00.673Z\",\r\n \"RequestedUpdateDate\": null,\r\n \"SellerStockKeepingUnitId\": \"12\",\r\n \"SellerId\": \"cosmetics1\",\r\n \"StockKeepingUnitId\": 25,\r\n \"IsActive\": true\r\n }\r\n]\r\n```"
operationId: Getpagedadmin
parameters:
- name: sellerId
in: query
description: ID that identifies the seller in the marketplace. It can be the same as the seller name or a unique number. Check the **Sellers management** section in the Admin to get the correct ID.
required: false
style: form
explode: true
schema:
type: string
example: vtxkfj7352
- name: skuId
in: query
description: SKU's unique identifier in the marketplace.
required: false
style: form
explode: true
schema:
type: string
example: '1'
- name: sellerSkuId
in: query
description: SKU ID in the seller's store.
required: false
style: form
explode: true
schema:
type: string
example: '71'
- name: isActive
in: query
description: Defines if the SKU binding is active.
required: false
style: form
explode: true
schema:
type: boolean
example: true
- name: size
in: query
description: Amount of results.
required: false
style: form
explode: true
schema:
type: string
example: '1'
- 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: 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
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
IsPersisted:
type: boolean
description: Defines if the seller is persisted.
IsRemoved:
type: boolean
description: Defines if the seller is removed.
SkuSellerId:
type: integer
format: int32
description: SKU Binding ID.
UpdateDate:
type: string
description: Date when the SKU binding was updated for the last time, in UTC format.
RequestedUpdateDate:
type: string
description: Date when an SKU binding update was requested for the last time, in UTC format.
nullable: true
SellerStockKeepingUnitId:
type: string
description: SKU ID in the seller's store.
SellerId:
type: string
description: ID that identifies the seller in the marketplace. It can be the same as the seller name or a unique number. Check the **Sellers management** section in the Admin to get the correct ID.
StockKeepingUnitId:
type: integer
format: int32
description: SKU ID in the VTEX marketplace.
IsActive:
type: boolean
description: Defines if the SKU binding is active.
example:
- IsPersisted: true
IsRemoved: false
SkuSellerId: 102
UpdateDate: '2021-04-12T20:06:59.413Z'
RequestedUpdateDate:
SellerStockKeepingUnitId: '71'
SellerId: vtxkfj7352
StockKeepingUnitId: 1
IsActive: true
deprecated: false
/sku-binding/pvt/skuseller/{sellerId}/{sellerSkuId}:
get:
tags:
- SKU Bindings
summary: VTex Get details of a seller's SKU
description: "Retrieves the details of a seller's SKU given a seller ID and the SKU ID in the seller's store. \r\n\r\n > ℹ This path is an updated version of `/api/catalog_system/pvt/skuseller/{sellerId}/{sellerSkuId}`.\r\n\r\n## Response body example\r\n\r\n```json\r\n{\r\n \"IsPersisted\": true,\r\n \"IsRemoved\": false,\r\n \"SkuSellerId\": 102,\r\n \"UpdateDate\": \"2021-04-12T20:06:59.413Z\",\r\n \"RequestedUpdateDate\": null,\r\n \"SellerStockKeepingUnitId\": \"71\",\r\n \"SellerId\": \"vtxkfj7352\",\r\n \"StockKeepingUnitId\": 1,\r\n \"IsActive\": true\r\n}\r\n```"
operationId: GetSKUseller
parameters:
- 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: 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: sellerId
in: path
description: ID that identifies the seller in the marketplace. It can be the same as the seller name or a unique number. Check the **Sellers management** section in the Admin to get the correct ID.
required: true
style: simple
schema:
type: string
example: '101'
- name: sellerSkuId
in: path
description: SKU ID in the seller's store.
required: true
style: simple
schema:
type: string
example: '1'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
required:
- IsPersisted
- IsRemoved
- SkuSellerId
- SellerId
- StockKeepingUnitId
- SellerStockKeepingUnitId
- IsActive
- UpdateDate
- RequestedUpdateDate
properties:
IsPersisted:
type: boolean
description: Defines if the seller is persisted.
IsRemoved:
type: boolean
description: Defines if the seller is removed.
SkuSellerId:
type: integer
format: int32
description: SKU ID in the seller's store.
UpdateDate:
type: string
description: Date when the SKU binding was updated for the last time, in UTC format.
RequestedUpdateDate:
type: string
description: Date when an SKU binding update was requested for the last time, in UTC format.
nullable: true
SellerStockKeepingUnitId:
type: string
description: SKU seller ID.
SellerId:
type: string
description: ID that identifies the seller in the marketplace. It can be the same as the seller name or a unique number. Check the **Sellers management** section in the Admin to get the correct ID.
StockKeepingUnitId:
type: integer
format: int32
description: SKU ID in the VTEX marketplace.
IsActive:
type: boolean
description: Defines if the SKU binding is active.
example:
IsPersisted: true
IsRemoved: false
SkuSellerId: 799
UpdateDate: '2018-10-11T04:52:42.1'
RequestedUpdateDate:
SellerStockKeepingUnitId: '502'
SellerId: myseller
StockKeepingUnitId: 50
IsActive: true
deprecated: false
put:
tags:
- SKU Bindings
summary: VTex Bind a seller's SKU to another SKU
description: "Associates a seller's SKU to another marketplace SKU.\r\n\r\n > ℹ This path is an updated version of `/api/catalog_system/pvt/skuseller/{sellerId}/{sellerSkuId}`.\r\n\r\n## Request body example\r\n\r\n```json\r\n{\r\n \"StockKeepingUnitId\": 1\r\n}\r\n```"
operationId: Bindtoanothersku
parameters:
- 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: 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: sellerId
in: path
description: ID that identifies the seller in the marketplace. It can be the same as the seller name or a unique number. Check the **Sellers management** section in the Admin to get the correct ID.
required: true
style: simple
schema:
type: string
example: '101'
- name: sellerSkuId
in: path
description: SKU ID in the seller's store.
required: true
style: simple
schema:
type: string
example: '1'
requestBody:
description: Request body
content:
application/json:
schema:
required:
- StockKeepingUnitId
type: object
properties:
StockKeepingUnitId:
type: integer
format: int32
description: SKU ID in the marketplace.
example: 1
responses:
'204':
description: No Content
deprecated: false
/sku-binding/pvt/skuseller/list/bysellerId/{sellerId}:
get:
tags:
- SKU Bindings
summary: VTex Get all SKU Bindings by Seller ID
description: "Retrieves a list of SKU Bindings given a specific Seller ID. \r\n\r\n > ℹ This path is an updated version of `/api/catalog_system/pvt/skuseller/list/bysellerId/{sellerId}`.\r\n\r\n## Response body example\r\n\r\n```json\r\n[\r\n {\r\n \"SellerStockKeepingUnitId\": \"24\",\r\n \"FreightCommissionPercentage\": null,\r\n \"ProductCommissionPercentage\": null,\r\n \"SellerId\": \"vtxkfj7352\",\r\n \"StockKeepingUnitId\": 121,\r\n \"IsActive\": true\r\n }\r\n]\r\n```"
operationId: GetallbySellerId
parameters:
- 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: 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: sellerId
in: path
description: ID that identifies the seller in the marketplace. It can be the same as the seller name or a unique number. Check the **Sellers management** section in the Admin to get the correct ID.
required: true
style: simple
schema:
type: string
example: vtxkfj7352
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
type: object
properties:
SellerStockKeepingUnitId:
type: string
description: SKU ID in the seller's store.
FreightCommissionPercentage:
type: number
description: The percentage that must be filled in as agreed between the marketplace and the seller.
nullable: true
ProductCommissionPercentage:
type: number
description: 'The percentage that must be filled in as agreed between the marketplace and the seller. If there is no such commission, please fill in the field with the value: `0.00`.'
nullable: true
SellerId:
type: string
description: ID that identifies the seller in the marketplace. It can be the same as the seller name or a unique number. Check the **Sellers management** section in the Admin to get the correct ID.
StockKeepingUnitId:
type: integer
format: int32
description: SKU ID in the marketplace.
IsActive:
type: boolean
description: Defines if the SKU binding is active.
example:
SellerStockKeepingUnitId: '24'
FreightCommissionPercentage:
ProductCommissionPercentage:
SellerId: vtxkfj7352
StockKeepingUnitId: 121
IsActive: true
deprecated: false
/sku-binding/pvt/skuseller/paged/sellerid/{sellerId}:
get:
tags:
- SKU Bindings
summary: VTex Get paged SKU Bindings by Seller ID
description: "Retrieves a paged list of SKU Bindings given a specific Seller ID. \r\n\r\n > ℹ This path is an updated version of `/api/catalog_system/pvt/skuseller/paged/sellerid/{sellerId}`.\r\n\r\n## Response body example\r\n\r\n```json\r\n[\r\n {\r\n \"SellerId\": \"vtxkfj7352\",\r\n \"StockKeepingUnitId\": 121,\r\n \"SellerStockKeepingUnitId\": \"24\",\r\n \"IsActive\": true,\r\n \"FreightCommissionPercentage\": null,\r\n \"ProductCommissionPercentage\": null\r\n },\r\n {\r\n \"SellerId\": \"vtxkfj7352\",\r\n \"StockKeepingUnitId\": 14,\r\n \"SellerStockKeepingUnitId\": \"60\",\r\n \"IsActive\": true,\r\n \"FreightCommissionPercentage\": null,\r\n \"ProductCommissionPercentage\": null\r\n }\r\n]\r\n```"
operationId: GetpagedbySellerId
parameters:
- name: page
in: query
description: Page number.
required: true
style: form
explode: true
schema:
type: string
example: '1'
- name: size
in: query
description: Amount of results per page.
required: true
style: form
explode: true
schema:
type: string
example: '2'
- 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: 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: sellerId
in: path
description: ID that identifies the seller in the marketplace. It can be the same as the seller name or a unique number. Check the **Sellers management** section in the Admin to get the correct ID.
required: true
style: simple
schema:
type: string
example: vtxkfj7352
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
type: object
properties:
SellerId:
type: string
description: ID that identifies the seller in the marketplace. It can be the same as the seller name or a unique number. Check the **Sellers management** section in the Admin to get the correct ID.
StockKeepingUnitId:
type: integer
format: int32
description: SKU ID in the marketplace.
SellerStockKeepingUnitId:
type: string
description: SKU ID in the seller's store.
IsActive:
type: boolean
description: Defines if the SKU binding is active.
FreightCommissionPercentage:
type: number
description: The percentage that must be filled in as agreed between the marketplace and the seller.
nullable: true
ProductCommissionPercentage:
type: number
description: 'The percentage that must be filled in as agreed between the marketplace and the seller. If there is no such commission, please fill in the field with the value: `0.00`.'
nullable: true
example:
SellerId: vtxkfj7352
StockKeepingUnitId: 121
SellerStockKeepingUnitId: '24'
IsActive: true
FreightCommissionPercentage:
ProductCommissionPercentage:
example:
- SellerId: vtxkfj7352
StockKeepingUnitId: 121
SellerStockKeepingUnitId: '24'
IsActive: true
FreightCommissionPercentage:
ProductCommissionPercentage:
- SellerId: vtxkfj7352
StockKeepingUnitId: 14
SellerStockKeepingUnitId: '60'
IsActive: true
FreightCommissionPercentage:
ProductCommissionPercentage:
deprecated: false
/sku-binding/pvt/skuseller/changenotification/{skuId}:
post:
tags:
- SKU Bindings
summary: VTex Change Notification with SKU ID
description: "The seller is responsible for suggesting new SKUs to be sold in the VTEX marketplace and also for informing the marketplace about changes in their SKUs that already exist in the marketplace. Both actions start with a catalog notification, which is made by this request.\n\nWith this notification, the seller is telling the marketplace that something has changed about a specific SKU, like price or inventory, or that this is a new SKU that the seller would like to offer to the marketplace.\n\nThe body of the request should be empty.\r\n\r\n > ℹ This path is an updated version of `/api/catalog_system/pvt/skuseller/changenotification/{skuId}`."
operationId: ChangeNotification
parameters:
- 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: 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: skuId
in: path
description: A string that identifies the SKU in the marketplace. This is the ID that the marketplace will use to look for the SKU whose change the seller wants to inform. If the marketplace finds this ID, it responds with status code `200`. Otherwise, it responds with status code `404`.
required: true
style: simple
schema:
type: string
example: '10'
responses:
'200':
description: OK
'400':
description: Bad Request
'403':
description: Forbidden
'404':
description: Not found
'429':
description: Too many requests
deprecated: false
/sku-binding/pvt/skuseller/changenotification/{sellerId}/{sellerSkuId}:
post:
tags:
- SKU Bindings
summary: VTex Change Notification with Seller ID and Seller SKU ID
description: "The seller is responsible for suggesting new SKUs to be sold in the VTEX marketplace and also for informing the marketplace about changes in their SKUs that already exist in the marketplace. Both actions start with a catalog notification, which is made by this request.\n\nWith this notification, the seller is telling the marketplace that something has changed about a specific SKU, like price or inventory, or that this is a new SKU that the seller would like to offer to the marketplace.\n\nThere are two information expected by the marketplace in this request: the `sellerId`, which identifies the seller, and the `sellerSkuId`, which identifies the binding of the seller with the SKU.\n\nBoth information are passed through the request URL. The body of the request should be empty.\r\n > ℹ This path is an updated version of `/api/catalog_system/pvt/skuseller/changenotification/{sellerId}/{sellerSkuId}`.\r\n\r\n## Example\r\n\r\nLet's say your seller has the ID `123` in the marketplace and you want to inform the marketplace that has been a change in the SKU with ID `700`.\r\n\r\nIn this case, you would have to replace the `sellerId` parameter with the value `123` and the `skuId` parameter with the value `700`. The URL of the request would be the following.\r\n\r\n```\r\nhttps://{{accountName}}.vtexcommercestable.com.br/api/sku-binding/pvt/skuseller/changenotification/123/700\r\n```\r\n\r\n## Response codes\r\n\r\nThe following response codes are possible for this request.\r\n* 200: the SKU whose ID was informed in the URL already exists in the marketplace and was found. The marketplace can now proceed with a fulfillment simulation in order to get updated information about this SKU's inventory and price.\r\n* 403: Failure in the authentication.\r\n* 404: the SKU was not found in the marketplace. The body of the response, in this case, should follow this format: \"Seller StockKeepingUnit `{{skuId}}` not found for this seller id `{{sellerId}}`. This means that the seller can now proceed with sending an offer to the marketplace in order to suggest that this SKU is sold there.\r\n* 429: Failure due to too many requests."
parameters:
- 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: 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: sellerId
in: path
description: ID that identifies the seller in the marketplace. It can be the same as the seller name or a unique number. Check the **Sellers management** section in the Admin to get the correct ID.
required: true
style: simple
schema:
type: string
example: '101'
- name: sellerSkuId
in: path
description: ID of the binding of the seller with the SKU.
required: true
style: simple
schema:
type: string
example: '1'
responses:
'200':
description: OK
'400':
description: Bad Request
'403':
description: Forbidden
'404':
description: Not found
'429':
description: Too many requests
deprecated: false
/sku-binding/pvt/skuseller/insertion:
post:
tags:
- SKU Bindings
summary: VTex Insert SKU Binding
description: "Creates an SKU Binding, associating a seller's SKU with a marketplace's SKU.\r\n\r\n > ℹ This path is an updated version of `/api/catalog_system/pvt/skuseller/insertion`."
operationId: InsertSKUBinding
parameters:
- 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: 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
requestBody:
description: Request body
content:
application/json:
schema:
required:
- StockKeepingUnitId
- IsActive
- SellerId
- SellerStockKeepingUnitId
type: object
properties:
StockKeepingUnitId:
type: integer
format: int32
description: SKU ID in the marketplace.
IsActive:
type: boolean
description: Defines if the SKU binding is active.
SellerId:
type: string
description: ID that identifies the seller in the marketplace. It can be the same as the seller name or a unique number. Check the **Sellers management** section in the Admin to get the correct ID.
SellerStockKeepingUnitId:
type: string
description: SKU seller ID.
example:
StockKeepingUnitId: 1
IsActive: true
SellerId: vtxkfj7352
SellerStockKeepingUnitId: '71'
required: true
responses:
'200':
description: OK
'400':
description: Bad Request
'409':
description: Conflict
deprecated: false
/sku-binding/pvt/skuseller/activate/{sellerId}/{skuSellerId}:
post:
tags:
- SKU Bindings
summary: VTex Activate SKU Binding
description: "Changes the status of an SKU Binding to active, setting `isActive` to `true`.\r\n\r\n > ℹ This path is an updated version of `/api/catalog_system/pvt/skuseller/activate/{sellerId}/{skuSellerId}`."
operationId: ActivateSKUBinding
parameters:
- 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: Accept
in: header
description: HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.
required: true
style
# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vtex/refs/heads/main/openapi/vtex-sku-bindings-openapi-original.yml