Create a campaign (campaigns/create)
Using this method, you can create a new campaign.
  1. Campaign is sent for verification and its status changes to moderation.
  2. After the verification, the campaign status changes to one of the following (reported by the moderator):
    • verified — everything is in order, you can start the campaign (campaigns/start) or it will start on schedule (if campaignStart is set).
    • declined — you need to make changes: send the campaigns/update request with new data and the same partnerCampaignId.
  3. Campaign starts: status changes to started.

For campaigns with promo codes (campaignType=codeOnline or campaignType=codeOffline): the campaign will not start if it does not have promo codes, and it will stop once it runs out of promo codes (pin-required status). In this case, you need to upload more promo codes (using the method campaigns/add-pins).

When you re-create a campaign by calling campaigns/update with the same partnerCampaignId, it updates this campaign’s data, stops it, and sends it for verification.
Request
Address for sending the request
POST https://yoomoney.ru/api/offerwall/v1/campaigns/create
Parameters
ParameterTypeDescription
partnerCampaignId
int
Campaign ID. Unique for the aggregator or store system.
Required parameter
categoryId
int
ID of the category of your products for this campaign according to the YooMoney reference guide. You can get the guide by calling categories/get.
Required parameter
campaignType
enum
Campaign type (method of obtaining the bonus). Possible values:
  • codeOnline — user receives a promo code for an online order (you can redirect them to the desired website using acceptUrl);
  • codeOffline — user receives a promo code that must be shown at the checkout in a retail outlet;
  • promo — user must use the special tracking link to visit the online store (set in the acceptUrl parameter).
Required parameter
campaignStart
datetime
Start date of the campaign. If not specified:
  • aggregator’s campaign starts at the moment of uploading,
  • store’s campaign awaits verification.
Optional parameter
campaignEnd
datetime
Date when the campaign stops being shown to users. If not specified, you can stop the campaign by calling the campaigns/stop method.
Optional parameter
offerDuration
int
Period (in hours) during which the user can redeem the saved offer. By default, it’s 2 weeks (366 hours). You can set a different period in the offerEnd parameter.

After the campaign ends (if you set a deadline in campaignEnd), the issued offers will be valid for another two weeks or within the period specified in offerDuration. The store needs to take this into account and give bonuses to users.

Optional parameter
pinType
enum
Type of promo code. Possible values:
  • one-off — single-use, meaning every user is provided with a unique code. The set of promo codes is uploaded in the campaigns/add-pins request;
  • reusable — reusable, all buyers will get the same code, for example YooMoney. Such code must be set in the couponCode parameter.
Required if campaignType=codeOnline or campaignType=codeOffline
pinDisplayType
string
Ways to display the promo code. Possible values:
  • text — a string unique to the store (any 255 numbers, letters, and characters, suitable for any promo codes);
  • ean_13 — promo code is displayed as a barcode (13 digits).
Required if campaignType=codeOnline or campaignType=codeOffline
couponCode
string
Promo code value. It will provide the user with a store discount.
Specified for campaigns with promo codes. Specified for products with reusable promo codes.
Required if:
  • campaignType=codeOnline or campaignType=codeOffline;
  • pinType=reusable (reusable).
acceptUrl
string
Tracking link that the user can follow to get a bonus (used instead of the promo code or with it).
By default, the YooMoney service adds the click ID (clickId) you need to analyze to the link. You can add template parameters to the link. How to form a link
Required if campaignType=promo or campaignType=codeOnline
merchantDomain
string
The address of the store’s website without http, www, and /.
Example: example.com
Required parameter
merchantLogoSvg
varchar (300)
Link to the store’s logo:
  • SVG format;
  • round logo;
  • size: 80 X 80 px;
  • viewBox attribute is specified;
  • maximum 100 KB.
Used for displaying on web pages.
Required parameter
merchantLogoPng
varchar (300)
Link to the store’s logo on transparent background:
  • PNG format;
  • round logo;
  • 240 X 240 px;
  • maximum 100 KB.
Used for displaying on web pages.
Required parameter
merchantName
varchar (300)
Store name.
Required parameter
backgroundColor
varchar (30)
Background color in #HEX format (not white nor light).
Required parameter
backgroundImage
string
Background image:
  • JPG or PNG format;
  • size: 500 X 500 px;
  • maximum 300 KB.
If the field is empty, the background image will be selected to match the category of this offer.
Optional parameter
fontColor
varchar (30)
Font color in #HEX format (contrast to the background).
Required parameter
description
varchar (90)
Campaign description in Russian.
Example: Скидка на товары для детей в магазине «Солнышко»
Required parameter
conditions
varchar (512)
Conditions for getting the bonus in Russian.
Example: Промокод действует 10 дней при заказе от 4000 рублей на сайте example.com. Его можно использовать один раз.
Required parameter
discountType
varchar (30)
Type of discount or bonus. Possible values:
  • text — bonus, gift, or special offer (text value is specified in discount_amount);
  • fix — fixed amount (numeric value is specified in discount_amount);
  • percent — discount in percentage (numeric value is specified in discount_amount).
Required parameter
discountAmount
varchar (30)
Size of the discount or the bonus description. If discountType=text, the copy must be in Russian.
Required parameter
discountCurrency
CurrencyCode
Currency code of the discount. Default value: 643 (Russian ruble).
For a discount of a certain amount (discountType=fix), you can set a different value: 840 (US dollar).
Optional parameter
campaignFee
varchar (30)
Amount of YooMoney’s remuneration for this campaign. Amount in rubles or dollars.
You must specify either of the parameters: amount of remuneration (campaignFee), or its minimum and maximum (campaignFeeMin and campaignFeeMax).
campaignFeeMin
varchar (30)
Minimum amount of YooMoney’s remuneration.
Optional parameter
campaignFeeMax
varchar (30)
Maximum amount of YooMoney’s remuneration.
Optional parameter
feeType
varchar (30)
Amount of YooMoney’s remuneration for this campaign. Possible values:
  • percent — percentage of the cost of the paid order;
  • fix — fixed.
Required parameter
feeCurrency
CurrencyCode
Currency code of YooMoney’s remuneration.
  • 643 — is the Russian ruble (set by default if no value is specified);
  • 840 — is the US dollar.
Optional parameter
supportedPlatforms
varchar (300)
Your offers will be displayed only on certain platforms. Possible values:
  • mobile — offers are displayed only on tablets and smartphones;
  • desktop — offers are displayed only on desktop computers.
Optional parameter
cashbackType
enum
For companies offering cashback: the type of cashback sent to the user’s wallet. Possible values:
  • bonus — user receives cashback in bonuses;
  • money — user receives cashback as money.
Optional parameter
cashbackConfirmTime
long
For companies offering cashback: the timeframe for redeeming the offer and crediting cashback (campaigns/redeem method). Number of days, integer.
Optional parameter
The discount amount is described by three variables: discountType, discountAmount, and discountCurrency. For instance:
  • 10% off: discount_type=percent, discount_amount=10;
  • 500 ruble discount: discount_type=fix, discount_amount=500; currency=643;
  • a gift for a purchase: discount_type=text, discount_amount="Подарок".
Example of a request body
JSON
{
    "backgroundColor": "#ffffff",
    "campaignEnd": "2017-12-31T23:59:59+03:30",
    "campaignType": "code",
    "campaignFee": "1000",
    "categoryId": 39,
    "conditions": "Бонус действует 10 дней при заказе от 4000 рублей на сайте example.com",
    "description": "Скидка на деньги на сайте ЮMoney",
    "discountAmount": "100",
    "discountCurrency": 643,
    "discountType": "text",
    "feeType": "fix",
    "fontColor": "#000000",
    "merchantDomain": "example.com",
    "merchantLogoPng": "https://example.com/i/logo.png",
    "merchantLogoSvg": "https://example.com/i/logo.svg",
    "merchantName": "Магазин",
    "partnerCampaignId": 20,
    "pinType": "one-off"
 }
Request example
cURL
curl -X POST \
 --header 'Content-Type: application/json' \
 --header 'Accept: application/json' \
 --header 'Authorization: Bearer <access token>' -d '{
    "backgroundColor": "#ffffff",
    "campaignEnd": "2017-12-31T23:59:59+03:30",
    "campaignType": "code",
    "campaignFee": "1000",
    "categoryId": 39,
    "conditions": "Бонус действует 10 дней при заказе от 4000 рублей на сайте example.com",
    "description": "Скидка на деньги на сайте ЮMoney",
    "discountAmount": "100",
    "discountCurrency": 643,
    "discountType": "text",
    "feeType": "fix",
    "fontColor": "#000000",
    "merchantDomain": "example.com",
    "merchantLogoPng": "https://example.com/i/logo.png",
    "merchantLogoSvg": "https://example.com/i/logo.svg",
    "merchantName": "Магазин",
    "partnerCampaignId": 20,
    "pinType": "one-off"
  }' 'https://yoomoney.ru/api/offerwall/v1/campaigns/create'
Response
Parameters
ParameterTypeDescription
ymCampaignIdintUnique ID of the campaign in the YooMoney service. Used in all subsequent requests.
campaignStatus
enum
Campaign status. Possible values:
  • moderation — in verification;
  • declined — declined (did not pass verification, updates required);
  • pin-required — ran out of promo codes (new uploads required);
  • started — campaign has been launched;
  • paused — campaign has been stopped;
  • finished — campaign has been archived.
Errors
Error codeValueDescription
incorrectDataIncorrect dataRequest contained invalid data.
repeatCampaignDataRepeated valueA campaign with the same partnerCampaignId but a different discount amount already exists.
Example of a response body
JSON
{
  "status": "success",
  "result": {
    "ymCampaignId": 34,
    "campaignStatus": "moderation"
  }
}