Search
API docs by Redocly

Marketing and Promotion (promotion)

Promo calendar, campaign management, bid settings, financial data accounting, and settings for with standard and custom bid.

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.

You can test the Promotion methods in the sandbox. Also you can use special methods in the sandbox for managing test balance

Marketing and Promotion

Promo calendar, campaign management, bid settings, financial data accounting, and settings for with standard and custom bid.

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.

You can test the Promotion methods in the sandbox. Also you can use special methods in the sandbox for managing test balance

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 account:
Type Period Limit Interval Burst
Personal 1 s 5 requests 200 ms 5 requests
Service 1 s 5 requests 200 ms 5 requests
Base with secret 1 s 5 requests 200 ms 5 requests
Base 1 h 4 requests 15 min 1 request
Authorizations:
HeaderApiKey

Responses

Response samples

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

Campaigns Information{{ /api/advert/v2/adverts }}

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

The method returns information about campaigns with standard or custom bid via statuses, payment types and IDs.

Request limit per one seller account:
Type Period Limit Interval Burst
Personal 1 s 5 requests 200 ms 5 requests
Service 1 s 5 requests 200 ms 5 requests
Base with secret 1 s 5 requests 200 ms 5 requests
Base 1 h 1 request 1 h 1 request
Authorizations:
HeaderApiKey
query Parameters
ids
string
Example: ids=12345,23456,34567,45678,56789

Campaign IDs, maximum 50

statuses
string
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"

Payment type:

  • cpm — cost per mille
  • cpc — cost per click

Responses

Response samples

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

Creating Campaigns

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

Minimum Bids for Listings{{ /api/advert/v1/bids/min }}

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

Method allows minimum bids for listings in minor currency units — 0.01 of the base unit of the seller account currency — depending on the payment type and placements.

Request limit per one seller account:
Type Period Limit Interval Burst
Personal 1 min 20 requests 3 s 5 requests
Service 1 min 20 requests 3 s 5 requests
Base with secret 1 min 20 requests 3 s 5 requests
Base 1 h 5 requests 12 min 1 request
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 item numbers list

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"

Placements:

  • 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": [
    ]
}

Create Campaign{{ /adv/v2/seacat/save-ad }}

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

The method creates campaign:

  • with custom bid for promo items in search and/or recommendations
  • with standard bid for promo items both in search and recommendations
Request limit per one seller account:
Type Period Limit Interval Burst
Personal 1 min 5 requests 12 s 5 requests
Service 1 min 5 requests 12 s 5 requests
Base with secret 1 min 5 requests 12 s 5 requests
Base 1 h 5 requests 12 min 1 request
Authorizations:
HeaderApiKey
Request Body schema: application/json
name
required
string

Campaign name

nms
Array of integers

Listing for this campaign. You can available listings with listings for campaigns method. Maximum of 50 items (nm)

bid_type
string
Default: "manual"
Enum: "manual" "unified"

Bid type:

  • unified — standard bid
  • manual — custom bid
payment_type
string
Default: "cpm"
Enum: "cpm" "cpc"

Payment type:

  • cpm — cost per mille
  • cpc — cost per click. When creating a campaign with this payment type, a minimum bid is automatically set
placement_types
Array of strings
Default: ["search"]
Items Enum: "search" "recommendations"

Placements:

  • search — search
  • recommendations — recommendations

Specify for campaign with custom bid only

Responses

Request samples

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

Response samples

Content type
application/json
1234567

Subcategories for Campaigns{{ /adv/v1/supplier/subjects }}

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

Returns subcategories listings from which are available for all campaigns

Request limit per one seller account:
Type Period Limit Interval Burst
Personal 12 s 1 request 12 s 5 requests
Service 12 s 1 request 12 s 5 requests
Base with secret 12 s 1 request 12 s 5 requests
Base 1 h 2 requests 30 min 1 request
Authorizations:
HeaderApiKey
query Parameters
payment_type
string
Default: "cpm"

Payment type:

  • cpm — cost per mille
  • cpc — cost per click

Responses

Response samples

Content type
application/json
Example
[
  • {
    }
]

Listings for Campaigns{{ /adv/v2/supplier/nms }}

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

Returns listings that are available for all campaigns.

Request limit per one seller account:
Type Period Limit Interval Burst
Personal 1 min 5 requests 12 s 5 requests
Service 1 min 5 requests 12 s 5 requests
Base with secret 1 min 5 requests 12 s 5 requests
Base 1 h 2 requests 30 min 1 request
Authorizations:
HeaderApiKey
Request Body schema: application/json

ID of subcategories to get listings

Array
integer

Responses

Request samples

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

Response samples

Content type
application/json
[
  • {
    }
]

Campaign 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 account:
Type Period Limit Interval Burst
Personal 1 s 5 requests 200 ms 5 requests
Service 1 s 5 requests 200 ms 5 requests
Base with secret 1 s 5 requests 200 ms 5 requests
Base 1 h 5 requests 12 min 1 request
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 account:
Type Period Limit Interval Burst
Personal 1 s 5 requests 200 ms 5 requests
Service 1 s 5 requests 200 ms 5 requests
Base with secret 1 s 5 requests 200 ms 5 requests
Base 1 h 2 requests 30 min 1 request
Authorizations:
HeaderApiKey
Request Body schema: application/json
advertId
required
integer

ID of the campaign where the name is changing

name
required
string

New name (max 100 characters)

Responses

Request samples

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

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 a campaign, check its budget. If the budget is insufficient, replenish it.

Request limit per one seller account:
Type Period Limit Interval Burst
Personal 1 s 5 requests 200 ms 5 requests
Service 1 s 5 requests 200 ms 5 requests
Base with secret 1 s 5 requests 200 ms 5 requests
Base 1 h 5 requests 12 min 1 request
Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1234

Campaign ID

Responses

Response samples

Content type
application/json
Example

Incorrect campaign ID

{
  • "error": "Invalid Advert: invalid advert"
}

Pause Campaign{{ /adv/v0/pause }}

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

Campaign in status 9 — active — can be paused

Request limit per one seller account:
Type Period Limit Interval Burst
Personal 1 s 5 requests 200 ms 5 requests
Service 1 s 5 requests 200 ms 5 requests
Base with secret 1 s 5 requests 200 ms 5 requests
Base 1 h 5 requests 12 min 1 request
Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1234

Campaign ID

Responses

Response samples

Content type
application/json
Example

Incorrect campaign ID

{
  • "error": "Invalid Advert: invalid advert"
}

Stop Campaign{{ /adv/v0/stop }}

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

The method allows to end campaigns in statuses:

  • 9 — active
  • 11 — paused
Request limit per one seller account:
Type Period Limit Interval Burst
Personal 1 s 5 requests 200 ms 5 requests
Service 1 s 5 requests 200 ms 5 requests
Base with secret 1 s 5 requests 200 ms 5 requests
Base 1 h 5 requests 12 min 1 request
Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1234

Campaign ID

Responses

Response samples

Content type
application/json
Example

Incorrect campaign ID

{
  • "error": "Invalid Advert: invalid advert"
}

Changing Placements in Campaigns with Custom Bid{{ /adv/v0/auction/placements }}

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

The method allows you to change placements in campaigns with custom bid and per mille payment model — cpm.

For campaigns in statuses 4, 9 and 11.

Request limit per one seller account:
Type Period Limit Interval Burst
Personal 1 s 1 request 1 s 1 request
Service 1 s 1 request 1 s 1 request
Base with secret 1 s 1 request 1 s 1 request
Base 1 h 2 requests 30 min 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
Example
{
  • "detail": "can not deserialize response body",
  • "origin": "camp-api-public-cache",
  • "request_id": "9a929a81ea9dc1601fcc4be81f32c1cb",
  • "status": 400,
  • "title": "invalid payload"
}

Changing Campaigns Bids{{ /api/advert/v1/bids }}

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

The method changes the bids of listings by WB item numbers in campaigns:

  • with standard bid
  • with custom bid
  • with a cpc payment model — per click

For campaigns in statuses 4, 9 and 11.

Specify the placement in the request parameter placement:

  • combined — in search and recommendations for campaigns with standard bid
  • search or recommendations — in search or recommendations for campaigns with custom bid
Request limit per one seller account:
Type Period Limit Interval Burst
Personal 1 s 5 requests 200 ms 5 requests
Service 1 s 5 requests 200 ms 5 requests
Base with secret 1 s 5 requests 200 ms 5 requests
Base 1 h 2 requests 30 min 1 request
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": [
    ],
  • "currency": "RUB"
}

Changing the Listings in Campaigns{{ /adv/v0/auction/nms }}

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

The method allows you to add and remove listings in campaigns.

For campaigns in statuses 4, 9 and 11.

The current minimum bid is set for the added items.

Request limit per one seller account:
Type Period Limit Interval Burst
Personal 1 s 1 request 1 s 1 request
Service 1 s 1 request 1 s 1 request
Base with secret 1 s 1 request 1 s 1 request
Base 1 h 2 requests 30 min 1 request
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
required
Array of objects <= 20 items

Listings in campaigns

Responses

Request samples

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

Response samples

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

Recommended bids for items and search clusters{{ /api/advert/v0/bids/recommendations }}

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

The method returns recommended bids for items and search clusters of the campaign. You can use this method for campaigns with cpm — for impressions, and cpc — for clicks payment models.

Request limit per one seller account:
Type Period Limit Interval Burst
Personal 1 min 5 requests 12 s 5 requests
Service 1 min 5 requests 12 s 5 requests
Base with secret 1 min 5 requests 12 s 5 requests
Base 1 h 20 requests 3 min 1 request
Authorizations:
HeaderApiKey
query Parameters
nmId
required
integer <int64>
Example: nmId=123456789

WB item number

advertId
required
integer <int64>
Example: advertId=987654321

Campaign ID

Responses

Response samples

Content type
application/json
Example
{
  • "advertId": 987654321,
  • "base": {
    },
  • "nmId": 123456789,
  • "normQueries": [
    ],
  • "paymentType": "cpm"
}

Promotion Configuration Values{{ /api/advert/v1/config }}

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

The method returns the currency, currency codes of the seller account and the allowed bid increments for the method POST /api/advert/v1/normquery/bids.

Method is available by Personal token, Service token
Request limit per one seller account:
Period Limit Interval Burst
1 min 1 request 1 min 10 requests
Authorizations:
HeaderApiKey

Responses

Response samples

Content type
application/json
{
  • "cpcStep": 500,
  • "cpmStep": 100000,
  • "currency": "UZS",
  • "currencyCode": 860,
  • "minTopUp": 10000
}

Search Clusters

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

Search Clusters

Request cluster is a grouped list of requests that buyers use to search for items on WB. The cluster includes:

  • synonyms
  • requests in different genders
  • requests with typos
  • different word forms
  • phrases with similar meanings

For example, the men t-shirt cluster will also include requests like mren t-shirt, men t-shirts with sleeves, man t-shirts, and other similar phrases.

To get clusters that have already had impressions, use the search clusters statistics method.

You can set or delete bids for campaigns with custom bids. You can specify the seller account currency and bid steps in the response of the GET /api/advert/v1/config method. Bids are individual for each search cluster.

Exclusions

Set minus phrases to exclude request clusters from campaigns. The item will not be promoted for minus phrases.

List of Search Clusters Bids{{ /adv/v0/normquery/get-bids }}

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

The method returns a list of search clusters with bids by:

  • campaign IDs
  • WB item numbers
    Request limit per one seller account:
Type Period Limit Interval Burst
Personal 1 s 5 requests 200 ms 10 requests
Service 1 s 5 requests 200 ms 10 requests
Base with secret 1 s 5 requests 200 ms 10 requests
Base 1 h 5 requests 12 min 1 request
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
required
Array of objects <= 100 items

Responses

Request samples

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

Response samples

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

Set Bids for Search Clusters in the Currency of the Seller Account{{ /api/advert/v1/normquery/bids }}

Описание метода
Method is available by Personal token, Service token

The method sets bids for search clusters in the currency of the seller account.
You can use this method only for campaigns with manual bids and cpm payment model — per impressions.

Request limit per one seller account:
Type Period Limit Interval Burst
Personal 1 s 2 requests 500 ms 4 requests
Service 1 s 2 requests 500 ms 4 requests
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
required
Array of objects <= 100 items

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "success": [
    ],
  • "failed": [
    ]
}

Set Bids for Search Clusters{{ /adv/v0/normquery/bids }}

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

The method sets the bids for search clusters.
You can use this method only for campaigns with:

  • custom bid
  • a cpm payment model — per impressions
Request limit per one seller account:
Type Period Limit Interval Burst
Personal 1 s 2 requests 500 ms 4 requests
Service 1 s 2 requests 500 ms 4 requests
Base with secret 1 s 2 requests 500 ms 4 requests
Base 1 h 5 requests 12 min 1 request
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
required
Array of objects <= 100 items

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "detail": "invalid payment_type value",
  • "origin": "camp-api-public-cache",
  • "request_id": "7e5cb1f106cc6e85b5b29eb2e8815da2",
  • "status": 400,
  • "title": "invalid payload"
}

Delete Bids from Search Clusters{{ /adv/v0/normquery/bids }}

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

The method deletes the bids from search clusters.
You can use this method only for campaigns with:

  • custom bid
  • a cpm payment model — per impressions
Request limit per one seller account:
Type Period Limit Interval Burst
Personal 1 s 5 requests 200 ms 10 requests
Service 1 s 5 requests 200 ms 10 requests
Base with secret 1 s 5 requests 200 ms 10 requests
Base 1 h 5 requests 12 min 1 request
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
required
Array of objects <= 100 items

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "detail": "invalid payment_type value",
  • "origin": "camp-api-public-cache",
  • "request_id": "7e5cb1f106cc6e85b5b29eb2e8815da2",
  • "status": 400,
  • "title": "invalid payload"
}

List of Campaign Minus Phrases{{ /adv/v0/normquery/get-minus }}

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

The method returns a list of minus phrases by:

  • campaign IDs
  • WB item numbers
Request limit per one seller account:
Type Period Limit Interval Burst
Personal 1 s 5 requests 200 ms 10 requests
Service 1 s 5 requests 200 ms 10 requests
Base with secret 1 s 5 requests 200 ms 10 requests
Base 1 h 5 requests 12 min 1 request
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
required
Array of objects <= 100 items

Responses

Request samples

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

Response samples

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

Setting and Deleting Minus Phrases{{ /adv/v0/normquery/set-minus }}

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

The method sets and deletes the minus phrases in campaigns with standard and custom bid.

Sending an empty array deletes all minus phrases
Request limit per one seller account:
Type Period Limit Interval Burst
Personal 1 s 5 requests 200 ms 10 requests
Service 1 s 5 requests 200 ms 10 requests
Base with secret 1 s 5 requests 200 ms 10 requests
Base 1 h 5 requests 12 min 1 request
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
advert_id
required
integer

Campaign ID

nm_id
required
integer

WB item number

norm_queries
required
Array of strings <= 1000 items

Responses

Request samples

Content type
application/json
{
  • "advert_id": 1825035,
  • "nm_id": 983512347,
  • "norm_queries": [
    ]
}

Response samples

Content type
application/json
{
  • "detail": "invalid payment_type value",
  • "origin": "camp-api-public-cache",
  • "request_id": "7e5cb1f106cc6e85b5b29eb2e8815da2",
  • "status": 400,
  • "title": "invalid payload"
}

Active and Inactive Search Cluster Lists{{ /adv/v0/normquery/list }}

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

Returns lists of active and inactive search clusters with at least 100 views.

Request limit per one seller account:
Type Period Limit Interval Burst
Personal 1 s 5 requests 200 ms 10 requests
Service 1 s 5 requests 200 ms 10 requests
Base with secret 1 s 5 requests 200 ms 10 requests
Base 1 h 5 requests 12 min 1 request
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
required
Array of objects <= 100 items

Responses

Request samples

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

Response samples

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

Finances

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

Balance{{ /adv/v1/balance }}

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

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

Request limit per one seller account:
Type Period Limit Interval Burst
Personal 1 s 1 request 1 s 5 requests
Service 1 s 1 request 1 s 5 requests
Base with secret 1 s 1 request 1 s 5 requests
Base 1 h 2 requests 30 min 1 request
Authorizations:
HeaderApiKey

Responses

Response samples

Content type
application/json
{
  • "balance": 11083,
  • "net": 0,
  • "currency": "RUB",
  • "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 account:
Type Period Limit Interval Burst
Personal 1 s 4 requests 250 ms 4 requests
Service 1 s 4 requests 250 ms 4 requests
Base with secret 1 s 4 requests 250 ms 4 requests
Base 1 h 4 requests 15 min 1 request
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,
  • "currency": "RUB"
}

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

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

The method tops up the campaign budget.
To launch the campaign after topping up the budget, use the Launch campaign method.

Request limit per one seller account:
Type Period Limit Interval Burst
Personal 1 s 1 request 1 s 5 requests
Service 1 s 1 request 1 s 5 requests
Base with secret 1 s 1 request 1 s 5 requests
Base 1 h 5 requests 12 min 1 request
Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1234567

Campaign ID

Request Body schema: application/json
required
sum
integer

Budget top-up amount in the base units of the seller account currency

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": true

{
  • "total": 7289,
  • "currency": "RUB"
}

Receiving Costs History{{ /adv/v1/upd }}

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

The method allows to get a costs history

Request limit per one seller account:
Type Period Limit Interval Burst
Personal 1 s 1 request 1 s 5 requests
Service 1 s 1 request 1 s 5 requests
Base with secret 1 s 1 request 1 s 5 requests
Base 1 h 1 request 1 h 1 request
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 account:
Type Period Limit Interval Burst
Personal 1 s 1 request 1 s 5 requests
Service 1 s 1 request 1 s 5 requests
Base with secret 1 s 1 request 1 s 5 requests
Base 1 h 1 request 1 h 1 request
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
[
  • {
    },
  • {
    }
]

Statistics

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

Search Clusters Statistics{{ /adv/v0/normquery/stats }}

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

The method returns statistics for search clusters over a specified period.
You can use this method only for campaigns with a cpm payment model — for impressions.

Request limit per one seller account:
Type Period Limit Interval Burst
Personal 1 min 10 requests 6 s 20 requests
Service 1 min 10 requests 6 s 20 requests
Base with secret 1 min 10 requests 6 s 20 requests
Base 1 h 5 requests 12 min 1 request
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
from
required
string <date>

Period start date

to
required
string <date>

Period end date

required
Array of objects <= 100 items

Responses

Request samples

Content type
application/json
{
  • "from": "2025-10-07",
  • "to": "2025-10-08",
  • "items": [
    ]
}

Response samples

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

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.

In the sandbox statistics for campaigns are available for the last 30 days. Data is generated only for campaigns in the 9 status, type 8, 9 times per day

Request limit per one seller account:
Type Period Limit Interval Burst
Personal 1 min 3 requests 20 s 1 request
Service 1 min 3 requests 20 s 1 request
Base with secret 1 min 3 requests 20 s 1 request
Base 1 h 1 request 1 h 1 request
Authorizations:
HeaderApiKey
query Parameters
ids
required
string
Example: ids=22161678,28449281,28155229

Campaign IDs, maximum 50 values

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
[
  • {
    },
  • {
    }
]

Daily Search Clusters Statistics{{ /adv/v1/normquery/stats }}

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

Returns statistics (views, clicks, add-to-cart, orders, CTR, CPC, CPM, etc.) by search clusters for the specified period detailed by day.

You can use this method for campaigns with cpm — for impressions, and cpc — for clicks payment models.

Request limit per one seller account:
Type Period Limit Interval Burst
Personal 1 min 10 requests 6 s 20 requests
Service 1 min 10 requests 6 s 20 requests
Base with secret 1 min 10 requests 6 s 20 requests
Base 1 h 2 requests 30 min 1 request
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
from
required
string <date>

Period start date

to
required
string <date>

Period end date

required
Array of objects <= 100 items

Responses

Request samples

Content type
application/json
{
  • "from": "2026-01-01",
  • "to": "2026-01-30",
  • "items": [
    ]
}

Response samples

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

Promo Calendar

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

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

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

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

Returns a promos list with dates and times of occurrence

Request limit per one seller account for all methods in the Promo Calendar category:
Type Period Limit Interval Burst
Personal 6 s 10 requests 600 ms 5 requests
Service 6 s 10 requests 600 ms 5 requests
Base with secret 6 s 10 requests 600 ms 5 requests
Base 1 h 1 request 1 h 1 request
Authorizations:
HeaderApiKey
query Parameters
startDateTime
required
string <date-time>
Example: startDateTime=2023-09-01T00:00:00Z

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

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

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

allPromo
required
boolean
Default: false

Show promos:

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

Number of requested promos

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

From which element to start outputting data

Responses

Response samples

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

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

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

Returns detailed information about the selected promos

Request limit per one seller account for all methods in the Promo Calendar category:
Type Period Limit Interval Burst
Personal 6 s 10 requests 600 ms 5 requests
Service 6 s 10 requests 600 ms 5 requests
Base with secret 6 s 10 requests 600 ms 5 requests
Base 1 h 1 request 1 h 1 request
Authorizations:
HeaderApiKey
query Parameters
promotionIDs
required
Array of integers [ 1 .. 100 ] items unique
Example: promotionIDs=1&promotionIDs=3&promotionIDs=64

IDs of the promos for which information should be returned

Responses

Response samples

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

List of Items for Participating in the Promo{{ /api/v1/calendar/promotions/nomenclatures }}

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

Returns a list of items suitable for participation in the promo.

Not applicable for auto promos

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

Promo ID

inAction
required
boolean
Default: false
Example: inAction=true

Participates in the promo:

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

Number of requested items

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

From which element to start outputting data

Responses

Response samples

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

Add Item to the Promo{{ /api/v1/calendar/promotions/upload }}

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

Creates a item upload for the promo.
The upload status can be checked using separate methods.

Not applicable for auto promos

Request limit per one seller account for all methods in the Promo Calendar category:
Type Period Limit Interval Burst
Personal 6 s 10 requests 600 ms 5 requests
Service 6 s 10 requests 600 ms 5 requests
Base with secret 6 s 10 requests 600 ms 5 requests
Base 1 h 1 request 1 h 1 request
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
object

Request data

Responses

Request samples

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

Response samples

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