CreateInvoice (Live)

Generates an invoice for one or more campaigns in HTML format.

When calling this method, specify one or more campaigns and the amounts to pay that should be shown in the invoice. The method returns the URL of the invoice. Only the user who the method was called on behalf of can access the invoice (the user must log in on Yandex).

Attention.

Direct advertisers can generate an invoice only when the campaign has been approved by a moderator (see the campaign parameter StatusModerate).

Recommendations and restrictions

Attention. All campaigns specified in the same method call must be of the same type. More information about campaign types

We recommend generating invoices using as few calls of the CreateInvoice method per day as possible. This recommendation is aimed at improving the performance of the Yandex Direct API. In terms of productivity, it is better to generate one invoice for several campaigns at once than to generate separate invoices by calling the method multiple times.

Restrictions on method calls:

Exceeding these limits results in the error 56.

Currency restrictions

Attention. There is no provision for creating a single invoice for multiple campaigns in different currencies.

All campaigns specified in the same method call must be in the same currency.

Payment amounts (the Sum parameter) should be specified in the campaign currency (by setting the corresponding value for the Currency parameter). All amounts must be specified in the same currency.

New in the Live 4 version

The Currency input parameter is required.

Added the Currency input parameter.

Input data

The input data structure in JSON is shown below.

Attention. It is mandatory to include the finance_token and operation_num parameters in the request. For more information, see the Accessing finance methods.
{
   "method": "CreateInvoice",
   "finance_token": (string),
   "operation_num": (int),
   "param": {
      /* CreateInvoiceInfo */
      "Payments": [
         {  /* PayCampElement */
            "CampaignID": (int),
            "Sum": (float),
            "Currency": (string)
         }
         ...
      ]
   }
}

Parameters are described below.

Parameter Description Required
CreateInvoiceInfo object
Payments Array of PayCampElement objects. Each object specifies the campaign and the amount to be displayed in the payment invoice. Yes
PayCampElement object
CampaignID The campaign ID. Yes
Sum

The payment amount in the currency specified in the Currency parameter. When creating an invoice, the amount is rounded mathematically to the second decimal place (for all currencies, including the tenge).

The value in the real currency must include the client's VAT.

To get the minimum acceptable value, use the Dictionaries.get method for version 5 of the API and specify the dictionary name Currencies in the request.

Yes
Currency

The currency that the amount is shown in.

Acceptable values: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. The value must match the campaign currency; otherwise, an error is returned with code 245.

Yes
Parameter Description Required
CreateInvoiceInfo object
Payments Array of PayCampElement objects. Each object specifies the campaign and the amount to be displayed in the payment invoice. Yes
PayCampElement object
CampaignID The campaign ID. Yes
Sum

The payment amount in the currency specified in the Currency parameter. When creating an invoice, the amount is rounded mathematically to the second decimal place (for all currencies, including the tenge).

The value in the real currency must include the client's VAT.

To get the minimum acceptable value, use the Dictionaries.get method for version 5 of the API and specify the dictionary name Currencies in the request.

Yes
Currency

The currency that the amount is shown in.

Acceptable values: RUB, CHF, EUR, KZT, TRY, UAH, USD, BYN. The value must match the campaign currency; otherwise, an error is returned with code 245.

Yes

Output data

If successful, the method returns the URL for the invoice, as shown below. If unsuccessful, an error message is returned.

{
   "data": "https://passport.yandex.ru/passport?mode=subscribe&from=balance&retpath=http%3A%2F%2Fbalance.yandex.ru%2Fpaypreview.xml%3Frequest_id%3D14062489%26ref_service_id%3D7%26ui_type%3Dstd"
}

Examples of input data

Python

{
   'Payments': [
      {'CampaignID': 3193279, 'Sum': 50000.0, 'Currency': 'RUB'},
      {'CampaignID': 3193244, 'Sum': 1200.0, 'Currency': 'RUB'}
   ]
}

PHP

array(
   'Payments' => array(
      array('CampaignID' => 3193279, 'Sum' => 50000.0, 'Currency' => 'RUB'),
      array('CampaignID' => 3193244, 'Sum' => 1200.0, 'Currency' => 'RUB')
   )
)

Perl

{
   'Payments' => [
      {'CampaignID' => 3193279, 'Sum' => 50000.0, 'Currency' => 'RUB'},
      {'CampaignID' => 3193279, 'Sum' => 1200.0, 'Currency' => 'RUB'}
   ]
}