Marketing and Promotions (promotion)
Campaign Management, bid settings, financial data accounting, and settings for automatic 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
Campaign Management, bid settings, financial data accounting, and settings for automatic 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
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
Authorizations:
query Parameters
startDateTime required | string <RFC3339> Example: startDateTime=2023-09-01T00:00:00Z Period start, format |
endDateTime required | string <RFC3339> Example: endDateTime=2024-08-01T23:59:59Z Period end, format |
allPromo required | boolean Default: false Show promotions:
|
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
- 200
- 400
- 401
- 429
{- "data": {
- "promotions": [
- {
- "id": 123,
- "name": "скидки",
- "startDateTime": "2023-06-05T21:00:00Z",
- "endDateTime": "2023-06-05T21:00:00Z",
- "type": "auto"
}
]
}
}
Promotions Details{{ /api/v1/calendar/promotions/details }}
Returns detailed information about the selected promotions
Authorizations:
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
- 200
- 400
- 401
- 429
{- "data": {
- "promotions": [
- {
- "id": 123,
- "name": "ХИТЫ ГОДА",
- "description": "В акции принимают участие самые популярные товары 2023 года. Карточки товаров будут выделены плашкой «ХИТ ГОДА», чтобы покупатели замечали эти товары среди других. Также они будут размещены под баннерами на главной странице и примут участие в PUSH-уведомлениях. С ценами для вступления в акцию вы можете ознакомиться ниже.",
- "advantages": [
- "Badge",
- "Banner",
- "Top of product listings"
], - "startDateTime": "2023-06-05T21:00:00Z",
- "endDateTime": "2023-06-05T21:00:00Z",
- "inPromoActionLeftovers": 45,
- "inPromoActionTotal": 123,
- "notInPromoActionLeftovers": 3,
- "notInPromoActionTotal": 10,
- "participationPercentage": 10,
- "type": "auto",
- "exceptionProductsCount": 10,
- "ranging": [
- {
- "condition": "productsInPromotion",
- "participationRate": 10,
- "boost": 7
}, - {
- "condition": "calculateProducts",
- "participationRate": 20,
- "boost": 17
}, - {
- "condition": "allProducts",
- "participationRate": 35,
- "boost": 30
}
]
}
]
}
}
Products List 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
Authorizations:
query Parameters
promotionID required | integer Example: promotionID=1 Promotion ID |
inAction required | boolean Default: false Example: inAction=true Participates in the promotion:
|
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
- 200
- 400
- 401
- 422
- 429
{- "data": {
- "nomenclatures": [
- {
- "id": 162579635,
- "inAction": true,
- "price": 1500,
- "currencyCode": "RUB",
- "planPrice": 1000,
- "discount": 15,
- "planDiscount": 34
}
]
}
}
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
Authorizations:
Request Body schema: application/jsonrequired
object |
Responses
Request samples
- Payload
{- "data": {
- "promotionID": 1,
- "uploadNow": true,
- "nomenclatures": [
- 1,
- 3,
- 642
]
}
}
Response samples
- 200
- 400
- 401
- 422
- 429
{- "data": {
- "alreadyExists": false,
- "uploadID": 11
}
}
Campaigns lists{{ /adv/v1/promotion/count }}
Method allows to get campaigns lists grouped by type and status with information about last campaign change date.
Authorizations:
Responses
Response samples
- 200
- 401
- 429
{- "adverts": [
- {
- "type": 4,
- "status": 8,
- "count": 3,
- "advert_list": [
- {
- "advertId": 6485174,
- "changeTime": "2023-05-10T12:12:52.676254+03:00"
}, - {
- "advertId": 6500443,
- "changeTime": "2023-05-10T17:08:46.370656+03:00"
}, - {
- "advertId": 7936341,
- "changeTime": "2023-07-12T15:51:08.367478+03:00"
}
]
}
], - "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.
Authorizations:
query Parameters
status | integer Enum: -1 4 7 8 9 11
|
type | integer Enum: 4 5 6 7 8 9
|
order | string Enum: "create" "change" "id"
|
direction | string Enum: "desc" "asc"
For example: /adv/v1/promotion/adverts?type=6&order=change&direction=asc
|
Request Body schema: application/jsonrequired
List of campaign IDs. A Maximum of of 50.
You can get campaign IDs using the Campaign Lists method.
Responses
Request samples
- Payload
[- 1234567,
- 63453471
]
Response samples
- 200
- 400
- 401
- 422
- 429
[- {
- "endTime": "2100-01-01 00:00:00+03:00",
- "createTime": "2023-05-31 16:57:42.654141+03:00",
- "changeTime": "2023-06-21 22:10:43.074183+03:00",
- "startTime": "2023-07-21 21:17:42.872376+03:00",
- "name": "Носки_Шерстяные",
- "params": [
- {
- "intervals": [
- {
- "begin": 3,
- "end": 5
}
], - "price": 400,
- "subjectId": 201,
- "subjectName": "Носки",
- "nms": [
- {
- "nm": 11111111,
- "active": true
}
], - "active": false
}
], - "dailyBudget": 0,
- "advertId": 12345,
- "status": 9,
- "type": 6,
- "paymentType": "cpm",
- "searchPluseState": false
}
]
Promotional configuration values{{ /adv/v0/config }}
The method provides acceptable values for the main configuration parameters of campaigns
Authorizations:
Responses
Response samples
- 200
- 401
- 429
{- "categories": [
- {
- "id": 760,
- "name": "Автомобильные товары",
- "cpm_min": 112
}
], - "config": [
- {
- "description": "Минимальный бюджет кампании",
- "name": "budget_min",
- "value": "1000"
}, - {
- "description": "Максимальный период в днях, за который можно получить статистику",
- "name": "api_fullstat_day_depth",
- "value": "31"
}, - {
- "description": "Минимальная ставка CPM для автоматической кампании",
- "name": "cpm_min_booster",
- "value": "100"
}, - {
- "description": "Минимальная ставка CPM для аукциона",
- "name": "cpm_min_search_catalog",
- "value": "150"
}, - {
- "description": "Максимальное количество товаров для аукциона",
- "name": "max_nm_count",
- "value": "50"
}, - {
- "description": "Максимальное количество товаров для автоматической кампании",
- "name": "max_auto_nms",
- "value": "100"
}
]
}
Creating automatic campaign{{ /adv/v1/save-ad }}
Creates an automatic campaign.
Authorizations:
Request Body schema: application/jsonrequired
type | integer
|
name | string Campaign name (max. 128 characters) |
subjectId | integer ID of the item for which the campaign is created. |
sum | integer Top-up amount |
btype | integer
|
on_pause | boolean
|
nms | Array of integers WB articles array. |
cpm | integer Bid. |
Responses
Request samples
- Payload
{- "type": 8,
- "name": "Парашюты",
- "subjectId": 270,
- "sum": 500,
- "btype": 1,
- "on_pause": true,
- "nms": [
- 9178363,
- 9178364
], - "cpm": 10
}
Response samples
- 200
- 400
- 401
- 422
- 429
9008917
Create Auction campaign{{ /adv/v2/seacat/save-ad }}
Creates Auction campaign.
Authorizations:
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 of 50 products ( |
Responses
Request samples
- Payload
{- "name": "Телефоны",
- "nms": [
- 146168367,
- 200425104
]
}
Response samples
- 400
- 401
- 429
Нет доступных категорий для рк. Создайте новую кампанию для попадания в текущие категории
Subjects for campaigns{{ /adv/v1/supplier/subjects }}
Returns subjects nomenclatures from which are available for all campaigns
Authorizations:
Responses
Response samples
- 200
- 401
- 429
[- {
- "name": "3D очки",
- "id": 2560,
- "count": 1899
}
]
Nomenclatures for campaigns{{ /adv/v2/supplier/nms }}
Returns nomenclatures that are available for all campaigns.
Authorizations:
Request Body schema: application/json
ID of subjects to get nomenclatures
Responses
Request samples
- Payload
[- 123,
- 456,
- 765,
- 321
]
Response samples
- 200
- 400
- 401
- 429
[- {
- "title": "Плед",
- "nm": 146168367,
- "subjectId": 765
}
]
Campaign bid update{{ /adv/v0/cpm }}
The changed bid will appear in the campaign information within 3 minutes.
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 4 or 6 should be specified for instrument
, depending on whether the rate is to be changed in the catalogue (deprecated campaign type) or in the search (deprecated campaign type).
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:
Request Body schema: application/jsonrequired
advertId required | integer Campaign ID where the bid is changing |
type required | integer Enum: 5 6 7 8 9
|
cpm required | integer New bid value |
param required | integer The parameter for which the change will be made is the value of |
instrument | integer Campaign type for bid change in Auction |
Responses
Request samples
- Payload
{- "advertId": 789,
- "type": 5,
- "cpm": 456,
- "param": 23,
- "instrument": 4
}
Response samples
- 400
- 401
- 422
- 429
Incorrect value for parameter `param`
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.
Authorizations:
query Parameters
id required | integer Campaign ID |
Responses
Response samples
- 400
- 401
- 429
Invalid campaign identifier
{- "error": "Invalid campaign identifier"
}
Rename campaign{{ /adv/v0/rename }}
The method allows to rename a campaign.
Authorizations:
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
- Payload
{- "advertId": 2233344,
- "name": "newnmame"
}
Response samples
- 400
- 401
- 422
- 429
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, 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:
query Parameters
id required | integer Example: id=1234 Campaign ID |
Responses
Response samples
- 400
- 401
- 422
- 429
Incorrect campaign identifier (RC ID)
Pause campaign{{ /adv/v0/pause }}
Campaign in status 9
- active - can be paused
Authorizations:
query Parameters
id required | integer Example: id=1234 Campaign ID |
Responses
Response samples
- 400
- 401
- 422
- 429
Incorrect campaign identifier (RC ID)
Stop campaign{{ /adv/v0/stop }}
The method allows to end campaigns that are in status 9, 11 or 4.
Authorizations:
query Parameters
id required | integer Example: id=1234 Campaign ID |
Responses
Response samples
- 400
- 401
- 422
- 429
Incorrect campaign identifier (RC ID)
Campaign budget{{ /adv/v1/budget }}
The method allows to get information about the budget of a campaign.
Authorizations:
query Parameters
id required | integer Example: id=1 Campaign ID |
Responses
Response samples
- 200
- 400
- 401
- 429
{- "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.
Authorizations:
query Parameters
id required | integer Example: id=1234567 Campaign ID |
Request Body schema: application/jsonrequired
sum | integer Top-up amount |
type | integer
|
return | boolean Response return flag ( |
Responses
Request samples
- Payload
{- "sum": 5000,
- "type": 1,
- "return": true
}
Response samples
- 200
- 400
- 401
- 429
Response when return is true
{- "total": 500
}
Managing the activity of fixed phrases{{ /adv/v1/search/set-plus }}
The method allows to change the activity of fixed phrases. Only for Auction campaigns.
Authorizations:
query Parameters
id required | integer Example: id=1234567 Campaign ID |
fixed | boolean New state ( |
Responses
Response samples
- 401
- 429
{- "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 Auction campaigns.
Sending an empty array removes all fixed phrases and disables fixed phrase activity in the campaign.
Authorizations:
query Parameters
id required | integer Example: id=1234567 Campaign ID |
Request Body schema: application/jsonrequired
pluse | Array of strings Fixed phrase list (max. 100) |
Responses
Request samples
- Payload
{- "pluse": [
- "Phrase 1",
- "Phrase 2"
]
}
Response samples
- 200
- 401
- 429
[ "Фраза 1", "Фраза 2" ]
Setting/removing minus-phrases of phrase matching{{ /adv/v1/search/set-phrase }}
Sets/removes minus-phrases of a phrase match. Only for Auction campaigns.
The Maximum of 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.
Authorizations:
query Parameters
id required | integer Example: id=1234567 Campaign ID |
Request Body schema: application/jsonrequired
phrase | Array of strings Minus-phrases (max. 1000 pcs.) |
Responses
Request samples
- Payload
{- "phrase": [
- "сло",
- "гу"
]
}
Response samples
- 401
- 429
{- "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 }}
Sets/removes minus-phrases of exact match. Only for Auction campaigns.
The Maximum of 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.
Authorizations:
query Parameters
id required | integer Example: id=1234567 Campaign ID |
Request Body schema: application/jsonrequired
strong | Array of strings Minus-phrases (max. 1000 pcs.) |
Responses
Request samples
- Payload
{- "strong": [
- "стоять",
- "лопата"
]
}
Response samples
- 401
- 429
{- "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 Auction campaigns.
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.
Authorizations:
query Parameters
id required | integer Example: id=1234567 Campaign ID |
Request Body schema: application/jsonrequired
excluded | Array of strings Minus-phrases (max. 1000 pcs.) |
Responses
Request samples
- Payload
{- "excluded": [
- "что-то синее",
- "картошечка"
]
}
Response samples
- 401
- 429
{- "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 automatic campaigns{{ /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.
Authorizations:
query Parameters
id required | integer Example: id=1234567 Campaign ID |
Request Body schema: application/jsonrequired
excluded | Array of strings List of phrases (Maximum of 1000 pcs.) |
Responses
Request samples
- Payload
Setting minus phrases
{- "excluded": [
- "first phrase",
- "second phrase"
]
}
Response samples
- 401
- 429
{- "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 nomenclatures for automatic campaign{{ /adv/v1/auto/getnmtoadd }}
The method allows to get the list of nomenclatures available for adding to the campaign.
Authorizations:
query Parameters
id required | integer Example: id=1 Campaign ID |
Responses
Response samples
- 200
- 401
- 429
[ 1111111111, 2222222222, 3333333333, 4444444444 ]
Changing the list of nomenclatures in an automatic campaign{{ /adv/v1/auto/updatenm }}
The method allows you to add and remove nomenclatures.
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:
query Parameters
id required | integer Example: id=1 Campaign ID |
Request Body schema: application/jsonrequired
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
- Payload
{- "add": [
- 11111111,
- 44444444
], - "delete": [
- 55555555
]
}
Response samples
- 400
- 401
- 429
{- "error": "Not found"
}
Media campaigns number{{ /adv/v1/count }}
Method allows you to get the number of the seller's media campaigns.
Authorizations:
Responses
Response samples
- 200
- 401
- 429
{- "all": 6,
- "adverts": [
- {
- "type": 2,
- "status": 7,
- "count": 2
}, - {
- "type": 2,
- "status": 8,
- "count": 4
}
]
}
List of media campaigns{{ /adv/v1/adverts }}
The method allows to get the list of media campaigns of the seller
Authorizations:
query Parameters
status | integer Example: status=1
|
type | integer Example: type=1
|
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
|
direction | string Example: direction=desc
|
Responses
Response samples
- 200
- 401
- 429
[- {
- "advertId": 123456,
- "name": "тост",
- "brand": "goosb",
- "type": 2,
- "status": 8,
- "createTime": "2023-03-25T20:35:57.116943+03:00"
}, - {
- "advertId": 54321,
- "name": "тест",
- "brand": "bobr",
- "type": 1,
- "status": 7,
- "createTime": "2023-07-24T16:48:20.935599+03:00",
- "endTime": "2023-07-25T20:35:50.104978Z"
}
]
Information about media campaign{{ /adv/v1/advert }}
The method allows to get information about a single media campaign
Authorizations:
query Parameters
id required | integer Example: id=23569 Media campaign ID |
Responses
Response samples
- 200
- 401
- 429
{- "advertId": 23569,
- "name": "Реклама денег принеси",
- "brand": "Plank",
- "type": 2,
- "status": 11,
- "createTime": "2023-07-19T11:13:41.195138+03:00",
- "extended": {
- "reason": "Для возобновления показов пополните бюджет медиакампании",
- "expenses": 10000,
- "from": "2023-07-19T12:05:35.847348Z",
- "to": "2123-07-20T08:14:13.079176+03:00",
- "updated_at": "2023-07-21T13:25:31.129766+03:00",
- "price": 0,
- "budget": 0,
- "operation": 1,
- "contract_id": 0
}, - "items": [
- {
- "id": 68080,
- "name": "Унисон",
- "status": 7,
- "place": 2,
- "budget": 650000,
- "daily_limit": 500,
- "category_name": "Главная",
- "cpm": 351,
- "advert_type": 1,
- "created_at": "2023-11-01T15:40:46.86165+03:00",
- "updated_at": "2023-11-08T23:44:33.248229+03:00",
- "date_from": "2023-11-01T16:05:22.286002Z",
- "date_to": "2023-11-09T17:27:32.745869+03:00",
- "nms": [
- 123456,
- 11111111
], - "bottomText1": "string",
- "bottomText2": "string",
- "message": "string",
- "additionalSettings": 1,
- "receiversCount": 1,
- "subject_id": 6945,
- "subject_name": "Бельё",
- "action_name": "Распродажа! Создай себе домашний уют!",
- "show_hours": [
- {
- "From": 7,
- "To": 8
}
], - "Erid": "string"
}
]
}