Create a campaign (campaigns/create)

Using this method, you can create a new campaign.

Campaign is sent for verification and its status changes to moderation.
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.
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

Parameter	Type	Description
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). More about the campaign creation scenarios 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. Examples of logos 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. Examples of logos 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

Parameter	Type	Description
ymCampaignId	int	Unique 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. All campaign statuses

Errors

Error code	Value	Description
incorrectData	Incorrect data	Request contained invalid data.
repeatCampaignData	Repeated value	A 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"
  }
}