Seller Opt-in for Promotions

Promotions

The Seller Opt-in Promotions feature allows sellers to choose whether they want to participate in promotions on the marketplace.

Adding or removing sellers is not available through the Admin interface. These actions must be performed exclusively via the Promotions and Taxes API.

Creating promotions

You can create promotions manually in the VTEX Admin or via the API.

Via Admin

In the VTEX Admin, go to Promotions.
Click Create Promotion in the top right corner of the page.
Choose the desired type of promotion.
Complete the promotion details and, in the Sellers field, select the Participating option.
Click Create.

After creating the promotion, you must configure seller participation using the API.

Via API

Use the Create or Update Promotion or Tax endpoint to configure promotions with opt-in.

To avoid conflicts with the previous seller association model, make sure to set idSeller and idSellerIsInclusive to null.

Example request body with defined sellers:


_33{
_33  "idSeller": null,
_33  "idSellerIsInclusive": null,
_33  "optIn": {
_33    "sellers": [
_33      "seller-id-1",
_33      "seller-id-2"
_33    ]
_33  },
_33
_33  "name": "MY PROMOTION",
_33  "idCalculatorConfiguration": "",
_33  "type": "combo",
_33  "origin": "Marketplace",
_33  "isActive": true,
_33  "beginDateUtc": "2025-05-29T00:00:00.000Z",
_33  "endDateUtc": "2025-05-29T00:30:00.000Z",
_33  "newOffset": -3,
_33  "isFeatured": false,
_33  "listSku1BuyTogether": [ { "id": "1", "name": "t-shirt size P" } ],
_33  "listSku2BuyTogether": [ { "id": "8", "name": "t-shirt size M" } ],
_33  "percentualDiscountValueList1": 10,
_33  "percentualDiscountValueList2": 10,
_33  "minimumQuantityBuyTogether": 1,
_33  "maxUsage": 0,
_33  "maxUsagePerClient": 0,
_33  "cumulative": false,
_33  "accumulateWithManualPrice": false,
_33  "idSeller": null,
_33  "idSellerIsInclusive": null,
_33  "idsSalesChannel": [],
_33  "areSalesChannelIdsExclusive": true
_33}

Example request body without initially defined sellers:


_30{
_30  "idSeller": null,
_30  "idSellerIsInclusive": null,
_30  "optIn": {
_30    "sellers": []
_30  },
_30
_30  "name": "MY PROMOTION",
_30  "idCalculatorConfiguration": "",
_30  "type": "combo",
_30  "origin": "Marketplace",
_30  "isActive": true,
_30  "beginDateUtc": "2025-05-29T00:00:00.000Z",
_30  "endDateUtc": "2025-05-29T00:30:00.000Z",
_30  "newOffset": -3,
_30  "isFeatured": false,
_30  "listSku1BuyTogether": [ { "id": "1", "name": "t-shirt size P" } ],
_30  "listSku2BuyTogether": [ { "id": "8", "name": "t-shirt size M" } ],
_30  "percentualDiscountValueList1": 10,
_30  "percentualDiscountValueList2": 10,
_30  "minimumQuantityBuyTogether": 1,
_30  "maxUsage": 0,
_30  "maxUsagePerClient": 0,
_30  "cumulative": false,
_30  "accumulateWithManualPrice": false,
_30  "idSeller": null,
_30  "idSellerIsInclusive": null,
_30  "idsSalesChannel": [],
_30  "areSalesChannelIdsExclusive": true
_30}

If you send invalid IDs, the promotion will still be created, but it won't take effect, as it will be associated with non-existent participating sellers.

Querying participating sellers

You can query participating sellers manually in the VTEX Admin or via the API.

Via Admin participating sellers

In the VTEX Admin, go to Promotions.
Click the name of the promotion you created.
In the Sellers field, view the list of participating sellers.

{"base64":" ","img":{"width":1191,"height":485,"type":"png","mime":"image/png","wUnits":"px","hUnits":"px","length":38442,"url":"https://images.ctfassets.net/alneenqid6w5/1YlZUUvrgcYERRM3IeJ8T2/2b2d3df08f40e071f57585c4e3af2e2b/sellers-participantes-en.png"}}

Via API participating sellers

Use the Get promotion or tax by ID endpoint to query promotion details, including the opt-in configuration.

GET https://{accountName}.{environment}.com/api/rnb/pvt/calculatorconfiguration/{idCalculatorConfiguration}

Example response for a promotion without opt-in:


_10{
_10  "optIn": null
_10}

Example response for a promotion with opt-in and defined sellers:


_10{
_10  "optIn": {
_10    "sellers": ["seller-id-1", "seller-id-2"]
_10  }
_10}

Example response for a promotion with opt-in and no defined sellers:


_10{
_10  "optIn": {
_10    "sellers": []
_10  }
_10}

Adding or removing participating sellers via API

To add or remove sellers in an opt-in promotion, use the Seller Opt-in or Opt-out endpoint.

POST


_10'/api/rnb/pvt/calculatorConfiguration/{promotionId}/seller-opt?an={accountName}'
_10--header 'if-Match: {lastUpdate}'
_10--data '{
_10  "sellerIds": [{sellerIds}],
_10  "operation": "{operation}"
_10}'

Field	Required	Type	Description
promotionId	true	string	ID of the promotion
accountName	true	string	Account that owns the promotion
sellerIds	true	string[]	List of seller IDs
lastUpdate	true	DateTime	Date and time of the promotion's last modification. Must match the current value, otherwise, the request will fail.
operation	true	OptOperation - OptIn - OptOut	Operation to be performed.

To add participating sellers, include their IDs in the request body.

Example request body:


_10{
_10  "sellerIds": [
_10    "seller-id-1",
_10    "seller-id-2"
_10  ],
_10  "operation": "OptIn"
_10}

To remove a participating seller, send a new request with the ID of the seller you want to remove.

Example request body:


_10{
_10  "sellerIds": [
_10    "seller-id-2"
_10  ],
_10  "operation": "OptOut"
_10}

Example response body:


_10{
_10  "lastModified": "2025-01-28T17:50:13+00:00"
_10}

Response codes:

Code	Description
200	Opt-in executed successfully.
400	Returned if the IdSellerIsInclusive field of the promotion is set to false.
401	Returned if the user doesn’t have the "Manage External Seller Promotions" permission.
412	Returned if the if-Match header value doesn't match the promotion's lastModified field, causing the request to fail.
404	Returned if no non-archived promotion with the specified ID is found.