Seller API Promotion

Synchronization from the database runs every 3 minutes.
The status is changed once per 1 minute. During this interval the last status change action will be saved.
The bid change takes place once in 30 seconds. Within this interval the last action to change the bid will be saved.

Promotion

Promotional configuration values

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

Maximum of 1 request per minute per one seller's account

Authorizations:
HeaderApiKey

Responses

Response Schema: application/json
Array of objects

Response samples

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

Creating automatic campaign

Creates an automatic campaign.
Maximum 1 request per 20 seconds

Authorizations:
HeaderApiKey
Request Body schema: application/json
required
type
integer
Type of automatic campaign:
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 - "Nomenclature 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 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

Response Schema: application/json
string

ID of created campaign

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 Auction campaign

Creates Auction campaign.
Maximum 5 requests per minute

Authorizations:
HeaderApiKey
Request Body schema: application/json
campaignName
string

Campaign name

nms
Array of integers

Nomenclature for this campaign. You can available nomenclatures with Nomenclatures for campaigns method. Maximum 50 products (nm)

Responses

Response Schema: application/json
integer

Campaign ID

Request samples

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

Response samples

Content type
application/json
1234567

Removing a campaign

The method allows to remove campaigns in the status 4 - ready to launch.
5 requests per second are allowed.
After removing, the campaign will be in -1 status for a while.
It takes between 3 and 10 minutes to completely remove a campaign

Authorizations:
HeaderApiKey
query Parameters
id
required
integer

Campaign ID

Responses

Response samples

Content type
application/json

Invalid campaign identifier

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

Campaign rename

The method allows to rename a campaign.
5 requests per second are allowed

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
application/json
Example
"Incorrect campaign identifier (RC ID)"

Campaigns lists

Method allows to get campaigns lists grouped by type and status with information about last campaign change date.
A maximum of 5 requests per second is allowed

Authorizations:
HeaderApiKey

Responses

Response Schema: application/json
Array of objects or null

Campaign data

all
integer

Total number of campaigns with all statuses and types

Response samples

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

Campaigns information

The method allows to retrieve information about campaigns via query parameters, or by a list of campaign IDs.
A maximum of 5 requests per second is allowed

Authorizations:
HeaderApiKey
query Parameters
status
integer
Enum: -1 4 7 8 9 11
Campaign status:
-1 - the campaign is in the process of being deleted
4 - ready to be launched
7 - campaign completed
8 - declined
9 - displays are ongoing
11 - campaign is paused
Campaign in the process of deletion. The status means that the campaign has been deleted and will disappear from the method's response within 3-10 minutes.
type
integer
Enum: 4 5 6 7 8 9
Campaign type:
4 - campaign in catalog (deprecated type)
5 - campaign in content (deprecated type)
6 - campaign in search (deprecated type)
7 - campaign in recommendations on the main page (deprecated type)
8 - automatic campaign
9 - Auction
order
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)

For example: /adv/v1/promotion/adverts?type=6&order=change&direction=asc
Request Body schema: application/json
required
Array
integer

List of campaign IDs. A maximum of 50.

You can get campaign IDs using the Campaign Lists method.

Responses

Response Schema: application/json
Array
Any of
endTime
string

Campaign end date

createTime
string

Campaign create time

changeTime
string

Campaign last update time

startTime
string

Campaign launch date

name
string

Campaign name

Array of objects

Campaign parameters

dailyBudget
integer

Daily budget; 0 if not set

advertId
integer

Campaign ID

status
integer
Campaign status:
-1 - campaign in the process of removing
4 - ready to start
7 - is over
8 - refused
9 - active
11 - paused
Campaign in the process of removing. The status means that the campaign has been deleted and in 3-10 minutes it will disappear from the method response.
type
integer
Type of campaign:
4 - campaign in catalogue (deprecated type)
5 - campaign in content (deprecated type)
6 - campaign in search (deprecated type)
7 - campaign on main page recommendations (deprecated type)
paymentType
string

Payment model:

  • cpm — for displays
  • cpo — for orders
searchPluseState
boolean

Fixed phrase activity:

  • false — inactive
  • true — active

Request samples

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

Response samples

Content type
application/json
Example
[
  • {
    }
]

Campaign bid update

The changed bid will appear in the campaign information within 3 minutes.
A maximum of 300 requests per minute is allowed.

Important! If the rate to be set is less than the allowable rate, the status code 422 (Rate size not changed) will be returned.
Information about changes to the minimum rate is published in the News section, on the Seller Portal.

Important! The procedure for filling in the parameters type, instrument, param when changing the rate for a campaign with type 9 (Auction):


For 'type' it is necessary to specify the value 9 (always).


A value of 6 (deprecated campaign type) should be specified for 'instrument'.


For 'param' it is necessary to specify the value of the id field from the subject structure response of the "Information about campaign" method

Authorizations:
HeaderApiKey
Request Body schema: application/json
required
advertId
required
integer

Campaign ID where the bid is changing

type
required
integer
Enum: 5 6 7 8 9
Campaign type to change the price:
5 - campaign in content (deprecated type)
6 - campaign in search (deprecated type)
7 - campaign on main page recommendations (deprecated type)
8 - automatic campaign
9 - Auction campaign
cpm
required
integer

New bid value

param
required
integer

The parameter for which the change will be made is the value of subjectId (for search and recommendation campaigns), setId (for product card campaigns), or menuId (for catalog campaigns).
For automated campaigns, this parameter is not required.

instrument
integer

Campaign type for bid change in 4 - catalog (deprecated type), 6 - search (deprecated type)

Responses

Request samples

Content type
application/json
{
  • "advertId": 789,
  • "type": 5,
  • "cpm": 456,
  • "param": 23,
  • "instrument": 4
}

Response samples

Content type
application/json
Example
"Incorrect value for parameter `param`"

Campaign activity

Launch campaign

The method allows to run campaigns that are in statuses 4 - ready to launch or 11 - paused campaign.
5 requests per second are allowed.
To run an ad campaign with status 11, it must have a replenished budget.

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
Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1234

Campaign ID

Responses

Response samples

Content type
application/json
Example
"Incorrect campaign identifier (RC ID)"

Pause campaign

Campaign in status "9 - active" - can be paused with GET /api/v0/pause?id=***.
5 requests per second are allowed

Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1234

Campaign ID

Responses

Response samples

Content type
application/json
Example
"Incorrect campaign identifier (RC ID)"

Complete campaign

The method allows to end campaigns that are in status 9, 11 or 4.
5 requests per second are allowed

Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1234

Campaign ID

Responses

Response samples

Content type
application/json
Example
"Incorrect campaign identifier (RC ID)"

Finances

Balance

The method allows to get information about the seller's net, balance and bonuses.
1 requests per second is allowed

Authorizations:
HeaderApiKey

Responses

Response Schema: application/json
balance
integer

Account, russian ruble

net
integer

Balance, russian ruble

bonus
integer

Bonuses, russian ruble

Response samples

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

Campaign budget

The method allows to get information about the budget of a campaign.
4 requests per second are allowed

Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1

Campaign ID

Responses

Response Schema: application/json
cash
integer

The field is not used. The value is always equal to 0.

netting
integer

The field is not used. The value is always equal to 0.

total
integer

Campaign budget, RUB

Response samples

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

Top-up of the campaign budget

The method allows to top up the budget of the campaign.
Allowed 1 request per second.

Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1234567

Campaign ID

Request Body schema: application/json
required
sum
integer

Top-up amount

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

Response Schema: application/json
One of
total
integer

Amount of the updated budget

Request samples

Content type
application/json
{
  • "sum": 500,
  • "type": 1,
  • "return": true
}

Response samples

Content type
application/json

Response when return is true

{
  • "total": 500
}

Receiving costs history

The method allows to get a costs history.
Allowed 1 request per second.

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 Schema: application/json
Array
updNum
integer

Billing document number (if any)

updTime
string <time-date>

Time of charge-off

updSum
integer

Amount invoiced

advertId
integer

Campaign ID

campName
string

Campaign name

advertType
integer

Type of campaign

paymentType
string
Source of charge-off:
Balance
Bonuses
Money account
advertStatus
integer
Campaign status:
4 - ready to run
7 - is over
8 - refused
9 - active
11 - paused

Response samples

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

Receiving the history of account top-ups

The method allows you to get a history of top-ups.
Allowed 1 request per second.

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 Schema: application/json
Array
id
integer

Payment ID

date
string <time-date>

Payment date

sum
integer

Payment amount

type
integer
Type of charge-off source:
0 - Account
1 - Balance
3 - Card
statusId
integer
Status:
0 - error
1 - processed
cardStatus
string
Transaction status (when paying by card):
success - success
fail - not success
pending - waiting for response
unknown - unknown

Response samples

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

Managing parameters of Auction campaign

Managing the activity of fixed phrases

The method allows to change the activity of fixed phrases in search campaigns. Only for Auction campaigns.

Maximum 1 request per 500 milliseconds.

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
"Некорректный запрос"

Setting/deleting fixed phrases

The method allows to set and delete fixed phrases.Only for Auction campaigns.

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

Maximum 1 request per 500 milliseconds.

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

Response Schema: application/json
Array
string

Request samples

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

Response samples

Content type
application/json
[
  • "Phrase 1",
  • "Phrase 2"
]

Setting/removing minus-phrases of phrase matching

Sets/removes minus-phrases of a phrase match. Only for Auction campaigns.

The maximum allowed number of minus-phrases in a campaign is 1000 pcs.
Posting an empty array removes all minus-phrase of phrase matching from the campaign.

Maximum 2 requests per second.

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
"Некорректный запрос"

Setting/removing minus of exact match phrases

Sets/removes minus-phrases of exact match. Only for Auction campaigns.

The maximum allowed number of minus-phrases in a campaign is 1000 pcs.
Sending an empty array removes all minus-phrases of the exact match from the ad campaign.

Maximum 2 requests per second.

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
"Некорректный запрос"

Setting/removing minus phrases from search

Sets/removes minus-phrases for search. Only for Auction campaigns.

The maximum allowed number of minus-phrases in a campaign is 1000 pcs.
Sending an empty array removes all minus-phrases from the Search ad campaign.

Maximum 2 requests per second.

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
"Некорректный запрос"

Managing parameters of auto campaign

List of nomenclatures for automatic campaign

The method allows to get the list of nomenclatures available for adding to the campaign.
A maximum of 1 requests per second is allowed

Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1

Campaign ID

Responses

Response Schema: application/json
Array
integer

Response samples

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

Changing the list of nomenclatures in an automatic campaign

The method allows you to add and remove nomenclatures.
A maximum of 1 requests per second is allowed.
Important: It is possible to add only those nomenclatures that will be returned in the method response "List of nomenclatures in an automatic campaign".
You cannot delete a one single nomenclature 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

Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1

Campaign ID

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

The nomenclatures that need to be added

delete
Array of integers

The nomenclatures that need to be deleted

Responses

Request samples

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

Response samples

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

Setting/removing minus-phrases for automatic campaigns

The method allows to set or remove minus phrases.
1 request per 6 seconds is allowed.
Sending an empty array removes all minus phrases from the campaign

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 1000 pcs.)

Responses

Request samples

Content type
application/json
Example

Setting minus phrases

{
  • "excluded": [
    ]
}

Response samples

Content type
application/json
"Некорректный запрос"

Dictionaries

To get information on product cards, use the content methods Nomenclature list and Nomenclatures in trash. They are available with the Promotion token.

Subjects for campaigns

Returns subjects nomenclatures from which are available for all campaigns. Maximum 1 request per 12 seconds.

Authorizations:
HeaderApiKey

Responses

Response Schema: application/json
Array
id
integer

Subject ID

name
string

Subject

count
integer

Number of WB Articles (nmId) in this subject

Response samples

Content type
application/json
Example
[
  • {
    }
]

Nomenclatures for campaigns

Returns nomenclatures that are available for all campaigns.

Maximum 5 requests per minute

Authorizations:
HeaderApiKey
Request Body schema: application/json

ID of subjects to get nomenclatures

Array
integer

Responses

Response Schema: application/json
Array
title
string

Product name

nm
integer

WB article (nmId)

subjectId
integer

Subject ID

Request samples

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

Response samples

Content type
application/json
[
  • {
    }
]

Statistics

Campaigns statistics

Returns campaign statistics.
Maximum 1 request per minute.
Data will be returned for campaigns with statuses 7, 9, and 11.
Important. In the request, you can either pass the dates parameter or the interval parameter, but not both.
You can send a request with only the campaign ID. In this case, data for the last 24 hours will be returned, but not for the entire campaign period.

Authorizations:
HeaderApiKey
Request Body schema: application/json
required
One of
[ 1 .. 100 ] items
Array ([ 1 .. 100 ] items)
id
integer

Campaign ID

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

Dates for which information needs to be provided.

Responses

Response Schema: application/json
One of
Array
dates
Array of strings <date> [ items <date > ]

Dates for which information is to be provided.

views
integer

Number of views.
For all days, across all WB articles and platforms.

clicks
integer

Number of clicks.
For all days, across all WB articles and platforms.

ctr
number

Clickability metric.
The ratio of clicks to displays. Expressed as a percentage
For all days, across all WB articles and platforms.

cpc
number

Average cost per click, ₽.
For all days, across all WB articles and platforms.

sum
number

Expenses, ₽.
For all days, across all WB articles and platforms.

atbs
integer

Number of products added to the basket.
For all days, across all WB articles and platforms.

orders
integer

Orders number.
For all days, across all WB articles and platforms.

cr
integer

CR(conversion rate) is the ratio of the number of orders to the total number of visits to the campaign.
For all days, across all WB articles and platforms.

shks
integer

Number of ordered products, pcs.
For all days, across all WB articles and platforms.

sum_price
number

Orders amount, ₽
For all days, across all WB articles and platforms.

Array of objects (Days)

Statistics by days

Array of objects (BoosterStats)

Statistics on the average position of the product on search results pages and catalog pages (for automatic campaigns).

advertId
integer

Campaign ID

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

[
  • {
    }
]

Statistics of an automatic campaign by phrase clusters

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.

Maximum — 4 requests per second.

Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1234

Campaign ID

Responses

Response Schema: application/json
excluded
Array of strings

Exclusions (negative phrases) for products from the campaign. These are phrases that you set using the "Set/Delete Negative Phrases" method or in the personal account, in the campaign settings.

Array of objects

Key phrases clusters

Response samples

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

Campaign statistics by key phrases

The method allows to get search campaign statistics by key phrases.
4 requests per second is allowed.
The information updates approximately every half hour

Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=1

Campaign ID

Responses

Response Schema: application/json
object

Key phrase information block

Array of objects

An array of statistics.
The first element of the array with keyword: "Total by campaign" contains summary information for all keyword phrases.
Each following element of the array contains information on a separate key phrase.
The 60 keyword phrases with the most number of views are displayed.

Response samples

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

Statistics on keywords for Automatic campaigns and Auctions

Returns statistics on keywords for each day the campaign was active.
Data can be retrieved for a maximum of 7 days.
Information is updated every hour.
Maximum 4 requests per second

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 Schema: application/json
required
Array of objects (V0KeywordsStatistics)

Response samples

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

Media

Public API for managing media campaigns

Get media campaigns

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

Authorizations:
HeaderApiKey

Responses

Response Schema: application/json
all
integer

Total number of media campaigns with all statuses and types

object

Response samples

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

List of media campaigns

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

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 — approved
5 — scheduled
6 — running
7 — completed
8 — refused
9 — paused by seller
10 — paused due to daily limit
11 — paused due to budget limit
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 Schema: application/json
Array
advertId
integer

Media campaign ID

name
string

Media campaign name

brand
string

Brand name

type
integer
Media campaign type:
1 — daily basis
2 — views basis
status
integer
Media campaign status:
1 — template
2 — moderation
3 — rejected (with the possibility to resubmit for moderation)
4 — approved
5 — scheduled
6 — running
7 — completed
8 — refused
9 — paused by seller
10 — paused due to daily limit
11 — paused due to budget limit
createTime
string <date-time>

Time of media campaign creation

endTime
string <date-time>

Time of completion of the media campaign (if any)

Response samples

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

Information about media campaign

The method allows to get information about a single media campaign

Authorizations:
HeaderApiKey
query Parameters
id
required
integer
Example: id=23569

Media campaign ID

Responses

Response Schema: application/json
advertId
integer

Media campaign ID

name
string

Media campaign name

brand
string

Brand name

type
integer
Media campaign type:
1 — daily basis
2 — views basis
status
integer
Media campaign status:
1 — template
2 — moderation
3 — rejected (with the possibility to resubmit for moderation)
4 — approved
5 — scheduled
6 — running
7 — completed
8 — refused
9 — paused by seller
10 — paused due to daily limit
11 — paused due to budget limit
createTime
string <date-time>

Time of media campaign creation

object
Array of objects

Banner information.
The response may not contain all fields, it depends on your media campaign configuration.

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

Media campaign activity

Stop media campaign

The method concludes the media campaign - it changes its status to 7.
A maximum of 10 requests per minute is allowed.

Statuses in which a media campaign can be concluded:
1 — template
3 — rejected (with the possibility to resubmit for moderation)
4 — approved
5 — scheduled
6 — running
8 — refused
9 — paused by seller
10 — paused due to daily limit
11 — paused due to budget limit
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
advert_id
required
integer

Media campaign ID

reason
string

Description of the reason for conclusion

Responses

Request samples

Content type
application/json
{
  • "advert_id": 123456,
  • "reason": "Description of the reason for conclusion"
}

Response samples

Content type
application/json
"Changing status is not possible"

Pause media campaign

Method allows to pause media campaign.
Transfers the paused media campaign to status 9.
A maximum of 10 requests per minute is allowed.
Important: the media campaign can be paused no more than 10 times a day. The day is counted from midnight Moscow time.

Statuses in which the media campaign can be paused:
4 — approved
5 — scheduled
6 — running
10 — paused due to daily limit
11 — paused due to budget limit
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
advert_id
required
integer

Media campaign ID

reason
string

Description of the pausing reason

Responses

Request samples

Content type
application/json
{
  • "advert_id": 123456,
  • "reason": "Описание причины приостановки"
}

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"
}

Launch media campaign

Method allows to run paused media campaigns.
After the campaign is launched, it will remain in status 4 for 2-5 minutes, after which the status will be updated to reflect the current configuration of the media campaign.
A maximum of 10 requests per minute is allowed.

Statuses in which the media campaign can be launched:
9 - paused by the seller
11 - paused due to budget limit
Authorizations:
HeaderApiKey
Request Body schema: application/json
required
advert_id
required
integer

Media campaign ID

reason
string

Description of the starting reason

Responses

Request samples

Content type
application/json
{
  • "advert_id": 123456,
  • "reason": "Причина запуска"
}

Response samples

Content type
application/json
Example
"Campaign not found"

Media campaign statistics

Media campaign statistics

The method allows to get statistics of media campaigns.

Authorizations:
HeaderApiKey
Request Body schema: application/json
required
One of
[ 1 .. 100 ] items
Array ([ 1 .. 100 ] items)
id
integer

Campaign ID

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

Dates for which information needs to be provided.

Responses

Response Schema: application/json
Array
One of
object

Requested time range

Array of objects (StatsBlok1)

Statistics data

Request samples

Content type
application/json
Example

Request with dates

[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
Example

Response for interval queries

[
  • {
    }
]

Media campaign bids

Change banner bid

The method allows you to change the banner bid in the items structure.
Changes are only possible for campaigns in one of the following statuses: 4, 5, 6, 9, 10, 11.
A maximum of 10 requests per minute is allowed

Authorizations:
HeaderApiKey
Request Body schema: application/json
required
advert_id
required
integer

Media campaign ID

item_id
required
integer

Banner ID

cpm
required
string

New bid

Responses

Request samples

Content type
application/json
{
  • "advert_id": 80474,
  • "item_id": 41573,
  • "cpm": 300
}

Response samples

Content type
application/json
Example
"\"Error in getting items: {x}\", Error details"