Search
API docs by Redocly

Marketing and Promotions (promotion)

Campaign Management, bid settings, financial data accounting, and settings for with standard and custom bid and media campaigns.

Data synchronization from the database occurs every 3 minutes. Status changes occur every 1 minute. The bid change occurs every 30 seconds. The latest changes are saved within the intervals

Marketing and Promotions

Campaign Management, bid settings, financial data accounting, and settings for with standard and custom bid and media campaigns.

Data synchronization from the database occurs every 3 minutes. Status changes occur every 1 minute. The bid change occurs every 30 seconds. The latest changes are saved within the intervals

Campaigns

To access the methods, use a token for the Promotion category

Campaigns lists{{ /adv/v1/promotion/count }}

Описание метода

Method allows to get campaigns lists grouped by type and status with information about last campaign change date.

Request limit per one seller's account:
Period Limit Interval Burst
1 second 5 requests 200 milliseconds 5 requests
Authorizations:
HeaderApiKey

Responses

Response samples

Content type
application/json
{
  • "adverts": [
    ],
  • "all": 3
}

Campaigns information{{ /adv/v1/promotion/adverts }}

Описание метода

The method allows to retrieve information about campaigns via query parameters, or by a list of campaign IDs.

Use the separate method to get information about campaigns with custom bid.

Request limit per one seller's account:
Period Limit Interval Burst
1 second 5 requests 200 milliseconds 5 requests
Authorizations:
HeaderApiKey
query Parameters
status
integer
Enum: -1 4 7 8 9 11
Campaign status:
-1 — deleted, the deletion process will be completed within 10 minutes
4 — ready to be launched
7 — completed
8 — declined
9 — active
11 — paused
type
integer
Enum: 4 5 6 7 8
Campaign type:
4 — in catalog (deprecated type)
5 — in product card (deprecated type)
6 — in search (deprecated type)
7 — in recommendations on the main page (deprecated type)
8 — standard bid
order
required
string
Enum: "create" "change" "id"
Order:
create — by the time of campaign creation
change — by the time of the last change to the campaign
id — by the campaign identifier
direction
string
Enum: "desc" "asc"
Direction:
desc — from greater to lesser
asc — from lesser to greater
Request Body schema: application/json
required
Array
integer

List of campaign IDs. A Maximum of of 50.

You can get campaign IDs using the Campaign Lists method

Responses

Request samples

Content type
application/json
[
  • 1234567,
  • 63453471
]

Response samples

Content type
application/json
Example
[
  • {
    }
]

Custom bid campaigns information{{ /adv/v0/auction/adverts }}

Описание метода

The method allows to retrieve information about campaigns with custom bid via statuses, payment types and IDs.

Request limit per one seller's account:
Period Limit Interval Burst
1 second 5 requests 200 milliseconds 5 requests
Authorizations:
HeaderApiKey
query Parameters
ids
Array of strings [ 1 .. 50 ] items
Example: ids=12345,23456,34567,45678,56789

Campaign IDs

statuses
Array of strings
Example: statuses=-1,4,8
Campaign statuses:
-1 — deleted, the deletion process will be completed within 10 minutes
4 — ready to be launched
7 — completed
8 — declined
9 — active
11 — paused
payment_type
string
Enum: "cpm" "cpc"
Рayment type:
cpm — cost per mille
cpc — cost per click

Responses

Response samples

Content type
application/json
{
  • "adverts": [
    ]
}

Campaigns Creation

To access the methods, use a token for the Promotion category

Promotional configuration values{{ /adv/v0/config }} Deprecated

Описание метода

The method provides acceptable values for the main configuration parameters of campaigns

Request limit per one seller's account:
Period Limit Interval Burst
1 minute 1 request 1 minute 1 request
Authorizations:
HeaderApiKey

Responses

Response samples

Content type
application/json
{
  • "categories": [
    ],
  • "config": [
    ]
}

Minimum bids for product cards{{ /adv/v0/bids/min }}

Описание метода

Method allows minimum bids for product cards depending on the payment type and campaign display zones.

Request limit per one seller's account:
Period Limit Interval Burst
1 minute 20 requests 3 seconds 5 requests
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
advert_id
required
integer <int64>

Campaign ID

nm_ids
required
Array of integers <int64> [ 1 .. 100 ] characters [ items <int64 > ]

WB articles array

payment_type
required
string
Enum: "cpm" "cpc"

Payment type:

  • cpm — per mille
  • cpc — per click
placement_types
required
Array of strings
Items Enum: "combined" "search" "recommendation"

Display zones:

  • search — search
  • recommendation — recommendation
  • combined — search and recommendation

Responses

Request samples

Content type
application/json
{
  • "advert_id": 98765432,
  • "nm_ids": [
    ],
  • "payment_type": "cpm",
  • "placement_types": [
    ]
}

Response samples

Content type
application/json
{
  • "bids": [
    ]
}

Creating campaign with standard bid{{ /adv/v1/save-ad }}

Описание метода

Creates an campaign with standard bid.

Request limit per one seller's account:
Period Limit Interval Burst
20 seconds 1 request 20 seconds 5 requests
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
type
integer
Type of campaign with standard bid:
8
name
string

Campaign name (max. 128 characters)

subjectId
integer

ID of the item for which the campaign is created.
Seller's existing IDs can be received by "Content / View — "Product cards list" method, response field is subjectID.

sum
integer

Top-up amount

btype
integer
Type of write-off.
0 — Account
1 — Balance
3 — Bonuses
on_pause
boolean
After creating campaign:
true — Will be suspended.
The campaign launch will be available within 3 minutes after the campaign is created.
false — Will be launched
nms
Array of integers

WB articles array.
Maximum of 100 articles

cpm
integer

Bid.
If a bid is specified that is less than the allowed size, the bid of the minimum allowed size will be automatically set.

Responses

Request samples

Content type
application/json
{
  • "type": 8,
  • "name": "Парашюты",
  • "subjectId": 270,
  • "sum": 500,
  • "btype": 1,
  • "on_pause": true,
  • "nms": [
    ],
  • "cpm": 10
}

Response samples

Content type
application/json
"9008917"

Create campaign with custom bid{{ /adv/v2/seacat/save-ad }}

Описание метода

Creates with custom bid campaign.

Request limit per one seller's account:
Period Limit Interval Burst
1 minute 5 requests 12 seconds 5 requests
Authorizations:
HeaderApiKey
Request Body schema: application/json
name
string

Campaign name

nms
Array of integers

Product card for this campaign. You can available product cards with product cards for campaigns method. Maximum of 50 products (nm)

Responses

Request samples

Content type
application/json
{
  • "name": "Телефоны",
  • "nms": [
    ]
}

Response samples

Content type
text/plain
Нет доступных категорий для рк. Создайте новую кампанию для попадания в текущие категории

Subjects for campaigns{{ /adv/v1/supplier/subjects }}

Описание метода

Returns subjects product cards from which are available for all campaigns

Request limit per one seller's account:
Period Limit Interval Burst
12 seconds 1 request 12 seconds 5 requests
Authorizations:
HeaderApiKey

Responses

Response samples

Content type
application/json
Example
[
  • {
    }
]

Product cards for campaigns{{ /adv/v2/supplier/nms }}

Описание метода

Returns product cards that are available for all campaigns.

Request limit per one seller's account:
Period Limit Interval Burst
1 minute 5 requests 12 seconds 5 requests
Authorizations:
HeaderApiKey
Request Body schema: application/json

ID of subjects to get product cards

Array
integer

Responses

Request samples

Content type
application/json
[
  • 123,
  • 456,
  • 765,
  • 321
]

Response samples

Content type
application/json
[
  • {
    }
]

Campaigns Management

To access the methods, use a token for the Promotion category

Delete campaign{{ /adv/v0/delete }}

Описание метода

The method allows to delete campaigns in the status 4 — ready to launch.

After deleting, the campaign will be in -1 status for a while.

It takes between 3 and 10 minutes to completely delete the campaign.

Request limit per one seller's account:
Period Limit Interval Burst
1 second 5 requests 200 milliseconds 5 requests
Authorizations:
HeaderApiKey
query Parameters
id
required
integer

Campaign ID

Responses

Response samples

Content type
application/json

Invalid campaign identifier

{
  • "error": "Invalid campaign identifier"
}

Rename campaign{{ /adv/v0/rename }}

Описание метода

The method allows to rename a campaign.

Request limit per one seller's account:
Period Limit Interval Burst
1 second 5 requests 200 milliseconds 5 requests
Authorizations:
HeaderApiKey
Request Body schema: application/json
advertId
required
integer

ID of the campaign that has the name change

name
required
string

New name (max 100 characters)

Responses

Request samples

Content type
application/json
{
  • "advertId": 2233344,
  • "name": "newnmame"
}

Response samples

Content type
text/plain
Example
Incorrect campaign identifier (RC ID)

Launch campaign{{ /adv/v0/start }}

Описание метода

The method allows to run campaigns that are in statuses 4 — ready to launch or 11 — paused campaign.

To run an ad campaign with status 11, check its budget. If the budget is insufficient, replenish it.

To run a campaign with status 4, it is necessary to do following (the order of actions does not matter):
1. After creating a campaign in the WB. Promotion cabinet click the `Apply changes` button.
2. Set the budget.
Request limit per one seller's account:
Period Limit Interval Burst
1 second 5 requests 200 milliseconds 5 requests
Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1234

Campaign ID

Responses

Response samples

Content type
text/plain
Example
Incorrect campaign identifier (RC ID)

Pause campaign{{ /adv/v0/pause }}

Описание метода

Campaign in status 9 — active — can be paused

Request limit per one seller's account:
Period Limit Interval Burst
1 second 5 requests 200 milliseconds 5 requests
Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1234

Campaign ID

Responses

Response samples

Content type
text/plain
Example
Incorrect campaign identifier (RC ID)

Stop campaign{{ /adv/v0/stop }}

Описание метода

The method allows to end campaigns that are in status 9, 11 or 4.

Request limit per one seller's account:
Period Limit Interval Burst
1 second 5 requests 200 milliseconds 5 requests
Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1234

Campaign ID

Responses

Response samples

Content type
text/plain
Example
Incorrect campaign identifier (RC ID)

Changing bids{{ /adv/v0/bids }}

Описание метода

The method changes the bids of product cards by WB articles in campaigns with standard bid.

For campaigns in statuses 4, 9 and 11.

Use the separate method to change bids in the campaigns with custom bid.

Minimum allowable bids can be found in the response of the method for getting minimum bids for product cards.

Request limit per one seller's account:
Period Limit Interval Burst
1 second 5 requests 200 milliseconds 5 requests
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
required
Array of objects (V0AdvertMultibid) <= 20 items

Responses

Request samples

Content type
application/json
{
  • "bids": [
    ]
}

Response samples

Content type
application/json
Example

Duplicate campaign ID.
The position of the campaign in the bids array of the request is indicated in .bids[n]

{
  • "errors": [
    ],
  • "request_id": "2c991dcab0fe971e8c0321c340a8c7fd",
  • "status": 400,
  • "title": "invalid payload",
  • "type": "Bad Request"
}

Changing placements in campaigns with custom bid{{ /adv/v0/auction/placements }}

Описание метода

The method allows you to change placements in campaigns with custom bid.

For campaigns in statuses 4, 9 and 11.

Request limit per one seller's account:
Period Limit Interval Burst
1 second 1 request 1 second 1 request
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
required
Array of objects <= 50 items

Placements in campaigns

Responses

Request samples

Content type
application/json
{
  • "placements": [
    ]
}

Response samples

Content type
application/json
{
  • "detail": "can not deserialize response body",
  • "origin": "camp-api-public-cache",
  • "request_id": "9a929a81ea9dc1601fcc4be81f32c1cb",
  • "status": 400,
  • "title": "invalid payload"
}

Changing bids in campaigns with custom bid{{ /adv/v0/auction/bids }}

Описание метода

The method changes the bids of product cards by WB articles in various placements in campaigns with custom bid.

For campaigns in statuses 4, 9 and 11.

Request limit per one seller's account:
Period Limit Interval Burst
1 second 5 requests 200 milliseconds 5 requests
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
required
Array of objects <= 50 items

Bids in campaigns

Responses

Request samples

Content type
application/json
{
  • "bids": [
    ]
}

Response samples

Content type
application/json
{
  • "bids": [
    ]
}

Campaigns Parameters

To access the methods, use a token for the Promotion category

Managing the activity of fixed phrases{{ /adv/v1/search/set-plus }}

Описание метода

The method allows to change the activity of fixed phrases. Only for campaigns with custom bid.

Request limit per one seller's account:
Period Limit Interval Burst
500 milliseconds 1 request 500 milliseconds 5 requests
Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1234567

Campaign ID

fixed
boolean

New state (false — make inactive, true — make active)

Responses

Response samples

Content type
application/json
{
  • "title": "unauthorized",
  • "detail": "token problem; token is malformed: could not base64 decode signature: illegal base64 data at input byte 84",
  • "code": "07e4668e--a53a3d31f8b0-[UK-oWaVDUqNrKG]; 03bce=277; 84bd353bf-75",
  • "requestId": "7b80742415072fe8b6b7f7761f1d1211",
  • "origin": "s2s-api-auth-catalog",
  • "status": 401,
  • "statusText": "Unauthorized",
  • "timestamp": "2024-09-30T06:52:38Z"
}

Setting/deleting fixed phrases{{ /adv/v1/search/set-plus }}

Описание метода

The method allows to set and delete fixed phrases.Only for campaigns with custom bid.

Sending an empty array removes all fixed phrases and disables fixed phrase activity in the campaign.

Request limit per one seller's account:
Period Limit Interval Burst
500 milliseconds 1 request 500 milliseconds 5 requests
Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1234567

Campaign ID

Request Body schema: application/json
required
pluse
Array of strings

Fixed phrase list (max. 100)

Responses

Request samples

Content type
application/json
{
  • "pluse": [
    ]
}

Response samples

Content type
application/json
[
  • "Фраза 1",
  • "Фраза 2"
]

Setting/removing minus-phrases of phrase matching{{ /adv/v1/search/set-phrase }} Deprecated

Описание метода

The method will be disabled on September 30

Request limit per one seller's account:
Period Limit Interval Burst
1 second 2 requests 500 milliseconds 2 requests
Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1234567

Campaign ID

Request Body schema: application/json
required
phrase
Array of strings

Minus-phrases (max. 1000 pcs)

Responses

Request samples

Content type
application/json
{
  • "phrase": [
    ]
}

Response samples

Content type
application/json
{
  • "title": "unauthorized",
  • "detail": "token problem; token is malformed: could not base64 decode signature: illegal base64 data at input byte 84",
  • "code": "07e4668e--a53a3d31f8b0-[UK-oWaVDUqNrKG]; 03bce=277; 84bd353bf-75",
  • "requestId": "7b80742415072fe8b6b7f7761f1d1211",
  • "origin": "s2s-api-auth-catalog",
  • "status": 401,
  • "statusText": "Unauthorized",
  • "timestamp": "2024-09-30T06:52:38Z"
}

Setting/removing minus of exact match phrases{{ /adv/v1/search/set-strong }} Deprecated

Описание метода

The method will be disabled on September 30

Request limit per one seller's account:
Period Limit Interval Burst
1 second 2 requests 500 milliseconds 2 requests
Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1234567

Campaign ID

Request Body schema: application/json
required
strong
Array of strings

Minus-phrases (max. 1000 pcs)

Responses

Request samples

Content type
application/json
{
  • "strong": [
    ]
}

Response samples

Content type
application/json
{
  • "title": "unauthorized",
  • "detail": "token problem; token is malformed: could not base64 decode signature: illegal base64 data at input byte 84",
  • "code": "07e4668e--a53a3d31f8b0-[UK-oWaVDUqNrKG]; 03bce=277; 84bd353bf-75",
  • "requestId": "7b80742415072fe8b6b7f7761f1d1211",
  • "origin": "s2s-api-auth-catalog",
  • "status": 401,
  • "statusText": "Unauthorized",
  • "timestamp": "2024-09-30T06:52:38Z"
}

Setting/removing minus phrases from search{{ /adv/v1/search/set-excluded }}

Описание метода

Sets/removes minus-phrases for search. Only for campaigns with custom bid.
The Maximum of allowed number of minus-phrases in a campaign is 1000 pcs.
Sending an empty array removes all minus-phrases from the Search ad campaign.

Request limit per one seller's account:
Period Limit Interval Burst
1 second 2 requests 500 milliseconds 2 requests
Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1234567

Campaign ID

Request Body schema: application/json
required
excluded
Array of strings

Minus-phrases (max. 1000 pcs)

Responses

Request samples

Content type
application/json
{
  • "excluded": [
    ]
}

Response samples

Content type
application/json
{
  • "title": "unauthorized",
  • "detail": "token problem; token is malformed: could not base64 decode signature: illegal base64 data at input byte 84",
  • "code": "07e4668e--a53a3d31f8b0-[UK-oWaVDUqNrKG]; 03bce=277; 84bd353bf-75",
  • "requestId": "7b80742415072fe8b6b7f7761f1d1211",
  • "origin": "s2s-api-auth-catalog",
  • "status": 401,
  • "statusText": "Unauthorized",
  • "timestamp": "2024-09-30T06:52:38Z"
}

Setting/removing minus-phrases for campaigns with standard bid{{ /adv/v1/auto/set-excluded }}

Описание метода

The method allows to set or remove minus phrases.
Sending an empty array removes all minus phrases from the campaign.

Request limit per one seller's account:
Period Limit Interval Burst
6 seconds 1 request 6 seconds 5 requests
Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1234567

Campaign ID

Request Body schema: application/json
required
excluded
Array of strings

List of phrases (Maximum of 1000 pcs)

Responses

Request samples

Content type
application/json
Example

Setting minus phrases

{
  • "excluded": [
    ]
}

Response samples

Content type
application/json
{
  • "title": "unauthorized",
  • "detail": "token problem; token is malformed: could not base64 decode signature: illegal base64 data at input byte 84",
  • "code": "07e4668e--a53a3d31f8b0-[UK-oWaVDUqNrKG]; 03bce=277; 84bd353bf-75",
  • "requestId": "7b80742415072fe8b6b7f7761f1d1211",
  • "origin": "s2s-api-auth-catalog",
  • "status": 401,
  • "statusText": "Unauthorized",
  • "timestamp": "2024-09-30T06:52:38Z"
}

List of product cards for campaign with standard bid{{ /adv/v1/auto/getnmtoadd }}

Описание метода

The method allows to get the list of product cards available for adding to the campaign.

Request limit per one seller's account:
Period Limit Interval Burst
1 second 1 request 1 second 5 requests
Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1

Campaign ID

Responses

Response samples

Content type
application/json
[
  • 1111111111,
  • 2222222222,
  • 3333333333,
  • 4444444444
]

Changing the list of product cards in an campaign with standard bid{{ /adv/v1/auto/updatenm }}

Описание метода

The method allows you to add and remove product cards.

It is possible to add only those product cards that will be returned in the method response List of product cards in an campaign with standard bid.
You cannot delete a one single product card from a campaign.

There is no validation by the delete parameter.

If you receive a response with a status code of 200 and no change has occurred, check the request for documentation compliance

Request limit per one seller's account:
Period Limit Interval Burst
1 minute 60 requests 1 second 5 requests
Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1

Campaign ID

Request Body schema: application/json
required
add
Array of integers

The product cards that need to be added

delete
Array of integers

The product cards that need to be deleted

Responses

Request samples

Content type
application/json
{
  • "add": [
    ],
  • "delete": [
    ]
}

Response samples

Content type
application/json
{
  • "error": "Not found"
}

Changing the list of product cards in campaigns with custom bid{{ /adv/v0/auction/nms }}

Описание метода

The method allows you to add and remove product cards in campaigns with custom bid.

For campaigns in statuses 4, 9 and 11.

The current minimum bid is set for the added products.

Request limit per one seller's account:
Period Limit Interval Burst
1 second 1 request 1 second 1 request
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
required
Array of objects <= 20 items

Product cards in campaigns

Responses

Request samples

Content type
application/json
{
  • "nms": [
    ]
}

Response samples

Content type
application/json
{
  • "nms": [
    ]
}

Finance

To access the methods, use a token for the Promotion category

Balance{{ /adv/v1/balance }}

Описание метода

The method allows to get information about the seller's net, balance and bonuses

Request limit per one seller's account:
Period Limit Interval Burst
1 second 1 request 1 second 5 requests
Authorizations:
HeaderApiKey

Responses

Response samples

Content type
application/json
{
  • "balance": 11083,
  • "net": 0,
  • "bonus": 15187,
  • "cashbacks": [
    ]
}

Campaign budget{{ /adv/v1/budget }}

Описание метода

The method allows to get information about the budget of a campaign.

Request limit per one seller's account:
Period Limit Interval Burst
1 second 4 requests 250 milliseconds 4 requests
Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1

Campaign ID

Responses

Response samples

Content type
application/json
{
  • "cash": 0,
  • "netting": 0,
  • "total": 500
}

Top-up of the campaign budget{{ /adv/v1/budget/deposit }}

Описание метода

The method allows to top up the budget of the campaign.

Request limit per one seller's account:
Period Limit Interval Burst
1 second 1 request 1 second 5 requests
Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1234567

Campaign ID

Request Body schema: application/json
required
sum
integer

Budget top-up amount

cashback_sum
integer

Top-up budget sum paid with promo bonuses.
You can top up only a certain percentage of the amount, indicated in the percent field of the response from the method for getting balance.
Promo bonuses are only applicable to these top-up sources:

  • 0 — account
  • 1 — balance sheet
cashback_percent
integer

The percentage of the top-up amount that can be paid with promo bonuses. You need to specify the value of the percent field from the response for the method for getting [balance]
If you specified cashback_sum, the cashback_percent parameter becomes required

type
integer
Type of top-up source:
0 — Account
1 — Balance
3 — Bonuses
return
boolean

Response return flag (true means updated campaign budget size will be returned in the response, false or empty means nothing will be returned).

Responses

Request samples

Content type
application/json
{
  • "sum": 5000,
  • "cashback_sum": 1000,
  • "cashback_percent": 50,
  • "type": 1,
  • "return": true
}

Response samples

Content type
application/json

Response when return is true

{
  • "total": 7289
}

Receiving costs history{{ /adv/v1/upd }}

Описание метода

The method allows to get a costs history

Request limit per one seller's account:
Period Limit Interval Burst
1 second 1 request 1 second 5 requests
Authorizations:
HeaderApiKey
query Parameters
from
required
string <date>
Example: from=2023-07-31

Beginning of the interval

to
required
string <date>
Example: to=2023-08-02

End of interval.
(Minimum interval is 1 day, maximum is 31)

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Receiving the history of account top-ups{{ /adv/v1/payments }}

Описание метода

The method allows you to get a history of top-ups.

Request limit per one seller's account:
Period Limit Interval Burst
1 second 1 request 1 second 5 requests
Authorizations:
HeaderApiKey
query Parameters
from
string <date>
Example: from=2023-07-31

Beginning of the interval

to
string <date>
Example: to=2023-08-02

End of interval.
(Minimum interval is 1 day, maximum is 31)

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Media

To access the methods, use a token for the Promotion category

Media campaigns number{{ /adv/v1/count }}

Описание метода

Method allows you to get the number of the seller's media campaigns.

Request limit per one seller's account:
Period Limit Interval Burst
1 second 10 requests 100 milliseconds 10 requests
Authorizations:
HeaderApiKey

Responses

Response samples

Content type
application/json
{
  • "all": 6,
  • "adverts": {
    }
}

List of media campaigns{{ /adv/v1/adverts }}

Описание метода

The method allows to get the list of media campaigns of the seller

Request limit per one seller's account:
Period Limit Interval Burst
1 second 10 requests 100 milliseconds 10 requests
Authorizations:
HeaderApiKey
query Parameters
status
integer
Example: status=1
Media campaign status:
1 — template
2 — moderation
3 — rejected (with the possibility to resubmit for moderation)
4 — ready for launch
5 — scheduled
6 — running
7 — completed
8 — declined
9 — paused by seller
10 — paused due to daily limit
11 — paused
type
integer
Example: type=1
Media campaign type:
1 — daily basis
2 — views basis
limit
integer
Example: limit=1

Number of campaigns in the response

offset
integer
Example: offset=1

Offset relative to the first media campaign

order
string
Example: order=id
The order in which the response is displayed:
create — by time of media campaign creation
id — by ID of media campaign creation
direction
string
Example: direction=desc
Sorting order:
desc — upward
asc — smaller to larger

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Information about media campaign{{ /adv/v1/advert }}

Описание метода

The method allows to get information about a media campaign

Request limit per one seller's account:
Period Limit Interval Burst
1 second 10 requests 100 milliseconds 10 requests
Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=23569

Media campaign ID

Responses

Response samples

Content type
application/json
{
  • "advertId": 23569,
  • "name": "Реклама денег принеси",
  • "brand": "Plank",
  • "type": 2,
  • "status": 11,
  • "createTime": "2023-07-19T11:13:41.195138+03:00",
  • "extended": {
    },
  • "items": [
    ]
}

Statistics

To access the methods, use a token for the Promotion category

Campaigns statistics{{ /adv/v2/fullstats }} Deprecated

Описание метода

The method will be disabled on September 30. Use the current method.

Request limit per one seller's account:
Period Limit Interval Burst
1 minute 1 request 1 minute 5 requests
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
Array
One of
id
required
integer

Campaign ID

dates
required
Array of strings <date> [ items <date > ]

Dates for which information needs to be provided

Responses

Request samples

Content type
application/json
Example

Request with dates

[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
Example

Response for a request with the field date

[
  • {
    }
]

Campaigns statistics{{ /adv/v3/fullstats }}

Описание метода

The method generates statistics for campaigns, regardless of their type.

The maximum period in a request is 31 days.

For campaigns in statuses 7, 9 and 11.

Request limit per one seller's account:
Period Limit Interval Burst
1 minute 1 request 1 minute 1 request
Authorizations:
HeaderApiKey
query Parameters
ids
required
Array of strings [ 1 .. 100 ] items
Example: ids=22161678,28449281,28155229

Campaign IDs

beginDate
required
string <date>
Example: beginDate=2025-09-07

Start date for the interval

endDate
required
string <date>
Example: endDate=2025-09-08

End date for the interval

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Statistics of an campaign with standard bid by phrase clusters{{ /adv/v2/auto/stat-words }}

Описание метода

Returns clusters of key phrases (sets of similar ones) for which products were shown in the campaign, and the number of displays for them. Only those phrases for which products were shown at least once are included in the method's response.

Information is updated every 15 minutes.

Request limit per one seller's account:
Period Limit Interval Burst
1 second 4 requests 250 milliseconds 4 requests
Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1234

Campaign ID

Responses

Response samples

Content type
application/json
{
  • "excluded": [
    ],
  • "clusters": [
    ]
}

Statistics on keywords for campaign with custom bid{{ /adv/v1/stat/words }}

Описание метода

The method allows to get statistics on keywords for campaign with custom bid.
The information updates approximately every half hour.

Request limit per one seller's account:
Period Limit Interval Burst
1 second 4 requests 250 milliseconds 4 requests
Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1

Campaign ID

Responses

Response samples

Content type
application/json
{
  • "words": {
    },
  • "stat": [
    ]
}

Statistics on keywords{{ /adv/v0/stats/keywords }}

Описание метода

Returns statistics on keywords for each day the campaign was active. It is applicable for campaigns with a standard and custom bid.
Data can be retrieved for a maximum of 7 days in one request.
Information is updated every hour.

Request limit per one seller's account:
Period Limit Interval Burst
1 second 4 requests 250 milliseconds 4 requests
Authorizations:
HeaderApiKey
query Parameters
advert_id
required
integer
Example: advert_id=123456789

Campaign ID

from
required
string <date>
Example: from=2024-08-10

Period start

to
required
string <date>
Example: to=2024-08-12

Period end

Responses

Response samples

Content type
application/json
{
  • "keywords": [
    ]
}

Media campaign statistics{{ /adv/v1/stats }}

Описание метода

The method allows to get statistics of WB Media campaigns

Request limit per one seller's account:
Period Limit Interval Burst
1 second 10 requests 100 milliseconds 10 requests
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
Array ([ 1 .. 100 ] items)
One of
id
required
integer

Campaign ID

dates
required
Array of strings <date> [ items <date > ]

Dates for which information needs to be provided

Responses

Request samples

Content type
application/json
Example

Request with dates

[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
Example

Response for interval queries

[
  • {
    }
]

Promotions Calendar

To access the methods, use a token for the Prices and Discounts category

Using these methods, you can obtain information about promotions and participate in them.

Promotions List{{ /api/v1/calendar/promotions }}

Описание метода

Returns a promotions list with dates and times of occurrence

Request limit per one seller's account for all methods in the Promotions Calendar category:
Period Limit Interval Burst
6 seconds 10 requests 600 milliseconds 5 requests
Authorizations:
HeaderApiKey
query Parameters
startDateTime
required
string <RFC3339>
Example: startDateTime=2023-09-01T00:00:00Z

Period start, format YYYY-MM-DDTHH:MM:SSZ

endDateTime
required
string <RFC3339>
Example: endDateTime=2024-08-01T23:59:59Z

Period end, format YYYY-MM-DDTHH:MM:SSZ

allPromo
required
boolean
Default: false

Show promotions:

  • false — available for participating
  • true — all promotion
limit
integer <uint> [ 1 .. 1000 ]
Example: limit=10

Number of requested promotions

offset
integer <uint> >= 0
Example: offset=0

From which element to start outputting data

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Promotions Details{{ /api/v1/calendar/promotions/details }}

Описание метода

Returns detailed information about the selected promotions

Request limit per one seller's account for all methods in the Promotions Calendar category:
Period Limit Interval Burst
6 seconds 10 requests 600 milliseconds 5 requests
Authorizations:
HeaderApiKey
query Parameters
promotionIDs
required
string [ 1 .. 100 ] items unique
Example: promotionIDs=1&promotionIDs=3&promotionIDs=64

IDs of the promotions for which information should be returned

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

List of Products for Participating in the Promotion{{ /api/v1/calendar/promotions/nomenclatures }}

Описание метода

Returns a list of products suitable for participation in the promotion.

Not applicable for auto promotions

Request limit per one seller's account for all methods in the Promotions Calendar category:
Period Limit Interval Burst
6 seconds 10 requests 600 milliseconds 5 requests
Authorizations:
HeaderApiKey
query Parameters
promotionID
required
integer
Example: promotionID=1

Promotion ID

inAction
required
boolean
Default: false
Example: inAction=true

Participates in the promotion:

  • true — yes
  • false — no
limit
integer <uint> [ 1 .. 1000 ]
Example: limit=10

Number of requested products

offset
integer <uint> >= 0
Example: offset=0

From which element to start outputting data

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Add Product to the Promotion{{ /api/v1/calendar/promotions/upload }}

Описание метода

Creates a product upload for the promotion.
The upload status can be checked using separate methods.

Not applicable for auto promotions

Request limit per one seller's account for all methods in the Promotions Calendar category:
Period Limit Interval Burst
6 seconds 10 requests 600 milliseconds 5 requests
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
{
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "data": {
    }
}