Yandex.Market Partner API. Developer`s guide

Transcription

Yandex.Market Partner API
Developer's guide
14.10.2016
Yandex.Market Partner API. Developer's guide. Version 2.0
Document build date: 14.10.2016.
This volume is a part of Yandex technical documentation.
Yandex helpdesk site: http://help.yandex.ru
© 2008—2016 Yandex LLC. All rights reserved.
Copyright Disclaimer
Yandex (and its applicable licensor) has exclusive rights for all results of intellectual activity and equated to them means of individualization, used for development, support,
and usage of the service Yandex.Market Partner API. It may include, but not limited to, computer programs (software), databases, images, texts, other works and inventions,
utility models, trademarks, service marks, and commercial denominations. The copyright is protected under provision of Part 4 of the Russian Civil Code and international laws.
You may use Yandex.Market Partner API or its components only within credentials granted by the Terms of Use of Yandex.Market Partner API or within an appropriate
Agreement.
Any infringements of exclusive rights of the copyright owner are punishable under civil, administrative or criminal Russian laws.
Contact information
Yandex LLC
http://www.yandex.com
Phone: +7 495 739 7000
Email: [email protected]
Headquarters: 16 L'va Tolstogo St., Moscow, Russia 119021
Contents
Introduction .......................................................................................................................................................................................... 5
Overview .............................................................................................................................................................................................. 5
Requests to Yandex.Market .............................................................................................................................................................. 7
Authentication .............................................................................................................................................................................. 7
Method calls ................................................................................................................................................................................. 8
Input data format .......................................................................................................................................................................... 8
Response format ........................................................................................................................................................................... 9
Error messages ............................................................................................................................................................................. 9
Restrictions for requests ............................................................................................................................................................. 13
Versions ..................................................................................................................................................................................... 14
Debugging the API .................................................................................................................................................................... 17
Requests to the merchant ................................................................................................................................................................ 18
Authentication ............................................................................................................................................................................ 18
SSL certificate ............................................................................................................................................................................ 18
Request method .......................................................................................................................................................................... 20
Data format in the request and response .................................................................................................................................... 20
Error messages ........................................................................................................................................................................... 21
Versions ..................................................................................................................................................................................... 21
Debugging the API .................................................................................................................................................................... 21
Verification tests ........................................................................................................................................................................ 25
API methods ..................................................................................................................................................................................... 28
Basic methods ........................................................................................................................................................................... 28
User campaigns .................................................................................................................................................................. 29
Information about a campaign ........................................................................................................................................... 32
Logins associated with a campaign .................................................................................................................................... 35
Campaigns accessible by login .......................................................................................................................................... 36
Campaign settings .............................................................................................................................................................. 39
Placement settings .................................................................................................................................................................... 42
Campaign region ................................................................................................................................................................ 42
Assortment ................................................................................................................................................................................ 46
Product offers in a campaign ............................................................................................................................................. 46
List of the campaign's price lists ........................................................................................................................................ 52
Price list information .......................................................................................................................................................... 55
Price list category ............................................................................................................................................................... 57
Campaign categories .......................................................................................................................................................... 61
Product modifications .............................................................................................................................................................. 66
Information about a product modification ......................................................................................................................... 66
Search for product modifications ....................................................................................................................................... 69
Information about multiple modifications ......................................................................................................................... 74
List of offers for a modification ......................................................................................................................................... 79
List of offers for multiple modifications ............................................................................................................................ 83
Managing bids .......................................................................................................................................................................... 91
Information about bids ....................................................................................................................................................... 92
Setting bids for offers ......................................................................................................................................................... 96
Bid recommendations ...................................................................................................................................................... 103
Setting recommended bids ............................................................................................................................................... 114
Bid settings ....................................................................................................................................................................... 122
Finances .................................................................................................................................................................................. 124
Campaign balance and forecast of expenditures .............................................................................................................. 124
Statistics .................................................................................................................................................................................. 126
Basic statistics .................................................................................................................................................................. 126
Statistics for product offers .............................................................................................................................................. 131
Developer's guide
Contents 4
Geobase ................................................................................................................................................................................... 137
Search for region .............................................................................................................................................................. 137
Region information .......................................................................................................................................................... 140
Information about child regions ....................................................................................................................................... 143
Market Ordering program .................................................................................................................................................... 149
Request for product information ...................................................................................................................................... 149
Passing an order and request to accept order ................................................................................................................... 157
Notification of changes to the order status ...................................................................................................................... 164
Changing the order status ................................................................................................................................................. 172
Changing conditions for order delivery ........................................................................................................................... 175
Information about a requested order ................................................................................................................................ 180
Information about requested orders ................................................................................................................................. 188
Practical usage ................................................................................................................................................................................ 198
Setting recommended bids on a selection of products ............................................................................................................. 198
Questions on partner API ................................................................................................................................................................. 200
Index ................................................................................................................................................................................................ 201
Developer's guide
Developer's guide
Introduction
This document describes the programming interface for the Yandex.Market partner interface (further referred
to as the Yandex.Market Partner API, or the Partner API).
The Partner API provides automated data exchange with the Yandex.Market partner interface. External
applications can use the API to get information about campaigns, product offers, and orders, as well as to manage
campaigns, bids for product offers, and orders.
Sections in this document:
•
Overview — An overview of the Yandex.Market Partner API, how to get access to the API, and how to call
the methods.
•
API methods — Detailed descriptions of methods, input data, and output data.
•
Practical usage — How to perform various tasks using the Yandex.Market Partner API.
This document is intended for developers of applications that interact with the Yandex.Market partner interface.
It is assumed that readers are familiar with Yandex.Market features and terminology, as well as with
the Yandex.Market partner interface.
To illustrate the features of the Partner API, examples of requests and responses are provided. These examples
use sample data for demonstration purposes.
Overview
The purpose of the Partner API is to provide an interface for third-party automated systems to interact with
the features of the Yandex.Market partner interface.
To get information from the partner interface or use its functions, a shop sends requests to the Yandex.Market
Partner API with input data. In response, the Partner API returns the necessary data or result of executing
a function.
In order to send requests to the Yandex.Market Partner API, you must first get an access token.
To send current information in response to a request from Yandex.Market, a shop must be able to automatically
return the necessary data. A shop has to implement this feature only if it participates in the Market Ordering
program.
In order to get requests from the Yandex.Market API, a shop must develop an application that interacts with
the API for the Market Ordering program over the HTTPS protocol, which requires that the shop uses an SSL
certificate.
The Yandex.Market Partner API is built on REST principles.
Resources
A resource is an integral part of the system that can be accessed using the Partner API. All actions are performed
using HTTP requests sent to resource URLs:
•
Read the contents and current state of the resource (GET methods).
•
Change the contents and state and write it to the resource (PUT methods).
•
Delete the resource (DELETE methods).
•
Perform special actions, such as adding new items to a list (POST methods).
Each resource has its own unique URL. For example, to get information about a campaign, you need to send
a GET request to the campaign's URL; to set bids for product offers, you need to send a PUT request with the bid
values to the URL of the bid resource.
Developer's guide
5
Developer's guide
For descriptions of methods and the resources they use, along with examples of requests and responses, see the
section API methods. For steps to follow when using several methods to complete certain tasks, see the section
Practical usage.
See also
Method calls
Representational State Transfer (Wikipedia)
Developer's guide
6
Requests to Yandex.Market 7
Requests to Yandex.Market
Authentication
The Yandex.Market API uses access tokens issued by the Yandex OAuth server to authenticate users.
An access token must be passed in every request. If an API method is called without an access token, or a request
passes an invalid token, the Yandex.Market server returns the HTTP status 401 Unauthorized.
To get an access token, you must register the application on the OAuth server. During registration, the application
is assigned a unique identifier (the client_id parameter on the OAuth server).
Note:
The generated access token can also be used for the Yandex.Direct API.
An access token that was obtained earlier for use with the Yandex.Direct API is not valid for the Yandex.Market
Partner API. If you want to use the same login and token for the Yandex.Direct API and the Yandex.Market
Partner API, you must generate an access token for this login anew.
In requests to the Yandex.Market Partner API, you must specify the user login (in the oauth_login
parameter), the access token (in the oauth_token parameter), and the application identifier (in the
oauth_client_id parameter).
There are several ways to pass authentication data in the request (the methods are shown in order of priority):
•
In the HTTP Authorization header:
Authorization: OAuth oauth_token="access_token",
oauth_client_id="application_id", oauth_login="user_login"
•
In the parameters of the request URL:
...&oauth_token=access_token&oauth_client_id=application_id&oauth_login=user_
login
Note:
Since authentication data must be specified in all requests, these parameters are omitted from the examples
for the purpose of simplifying documentation of the API methods.
For more information about authentication, refer to the document OAuth authentication.Developer's guide. This
document also contains recommendations for client application developers.
The flow for getting a token for developing and debugging an application is covered in the section Manually
obtaining a debugging token.
See also
Method calls
Developer's guide
Method calls
Requests to the Yandex.Market Partner API are passed over the HTTPS protocol; the timeout is 10 seconds
and Keep-Alive is not supported.
The request is made in the following format:
<method_type> https://api.partner.market.yandex.ru/v<API_version>/
<resource>.<response_format>?<parameters>
where
•
<API_version> is the number of the current API version. At the moment, the current version is 2.
•
<method_type> is GET, POST, PUT or DELETE.
•
<resource> is the URL of the resource to perform the action on. Resource names are provided in the
descriptions of the corresponding methods.
•
<response_format> is an optional part of the request that determines how the response is given.
The response format can be set in the HTTP Accept header. Possible response formats: XML and JSON.
By default, data is passed in XML format. The description of each method provides examples of requests
and responses.
•
<parameters> is both mandatory and optional request parameters that are not part of the resource URL.
Note:
For each method in the HTTP Authorization header or URL request parameters, you must pass
authentication data: the user login (oauth_login), the access token (oauth_token), and the application
identifier (oauth_client_id).
If an error occurs, request processing is terminated and an error message is returned. A list of errors
and descriptions is provided in the section Error messages.
See also
Authentication
Input data format
Response format
Error messages
Restrictions for requests
Versions
API methods
Input data format
Input data structures for POST and PUT methods are passed in the request body.
The following input data formats are acceptable:
•
XML (by default)
•
JSON
The input data format is set in the HTTP Content-Type header. Acceptable header values:
•
application/xml
•
application/json
Developer's guide
If the request does not specify the Content-Type header, Yandex.Market automatically detects the data
format. The service returns the HTTP 400 Bad Request status in the following cases:
•
The data passed is not valid for either XML or JSON.
•
The data structure contains errors.
•
The Content-Type header is set to XML format, but a valid data structure in JSON format was passed
(or the opposite).
See also
Method calls
Description of the JSON format
Response format
The Yandex.Market Partner API returns responses in UTF-8 encoding. Responses can be in either JSON or XML
format.
To set the response format, specify the desired format in the request URL after the method name. For example,
the result for the following request will contain data about user campaigns in XML format:
GET https://api.partner.market.yandex.ru/v2/campaigns.xml
You can also set the response format when calling methods by using the HTTP Accept header. Acceptable
header values:
•
application/xml
•
application/json
Sample request to get recommended bids for product offers:
POST
https://api.partner.market.yandex.ru/v2/campaigns/10003/bids/recommended?
position=5
Host api.partner.market.yandex.ru
Accept application/json
Content-Type application/json
{"offerNames":[
"Tefal 539625",
"Clatronic CM 3372"
]}
If the format is not specified, the response is returned in XML format by default.
When calling DELETE methods, the format of the result must be specified in order to guarantee compatibility
with the libraries being used for working with data.
See also
Method calls
Error messages
If an error occurs, request processing is terminated, and the server returns the HTTP response code appropriate
to the error. In addition to the error code, the response includes a short description of the error.
Developer's guide
The error message is returned in the format that is specified in the request URL after the method name or in
the HTTP Accept header.
The error description is passed in the error parameter. This parameter contains the error code (the code
parameter) and a short description of the error (the message parameter).
Error descriptions
Code Name
Explanation
200
OK
Request completed successfully.
400
Bad Request
Invalid request.
401
Unauthorized
Authentication data was not specified in the request.
403
Forbidden
Invalid authentication data specified in the request, or access to the requested resource
is forbidden.
404
Not Found
The requested resource was not found.
405
Method Not Allowed
The requested method is not supported for the specified resource.
415
Unsupported Media Type The method does not support the requested content type.
420
Enhance Your Calm
Exceeded limits on access to the resource.
500
Internal Server Error
Internal server error. Try calling the method again later. If the error persists, please contact
the technical support service for the Yandex.Market partner interface.
503
Service Unavailable
The server is temporarily unavailable due to high loads. Try calling the method again later.
Short error description in the response
•
For 400 Bad Request errors:
Description
Explanation
Possible solution
Unexpected end of
content
Request body ends
unexpectedly.
Check whether the data passed in the request
body is formatted correctly.
JSON: {message}
Error in the formatting of JSON
data.
body is formatted correctly for JSON.
XML: {message}
Error in the formatting of XML
data.
body is formatted correctly for XML.
The request is too big
Exceeded the size limit
for HTTP requests.
Decrease the size of the request by reducing
the amount of data passed.
Invalid status:
'status'.
An incorrect status
was indicated.
Check the correctness of the status being
passed for filtering by status.
Too long time period.
Maximum
is 'maxPeriod' days.
The specified range of dates
is too long. The maximum range
is 'maxPeriod'.
Shorten the range of dates for filtering
by date.
Missing field.
A mandatory parameter
was omitted.
Set the value for the mandatory parameter.
Value/Length of field
(value) must
be between min and
max [exclusively].
The value (length) of the
parameter must be between
the 'min' and 'max' values
and not equal to them.
Check the correctness of the parameter
value.
Value/Length of field
(value) must
be greater/less than
[or equal to] limit.
The value of the parameter
(length) must be equal to or
greater than (less than) the value
indicated in 'limit'.
value.
Value of field must
match the pattern:
'regExp'.
The parameter value must match
the regular expression.
value.
Value of field has too
high scale: 'price'.
The parameter is too precise.
Set parameter values with fewer decimal
points.
Developer's guide
Description
Explanation
Possible solution
Collection of field
must not be empty.
The parameter must not be
empty.
Specify at least one item for the parameter.
Other short descriptions that can be found in messages about this error are provided in the descriptions of the
corresponding resources.
•
•
For the 401 Unauthorized error:
Description
Explanation
Possible solution
Unsupported
authorization type
specified
in Authorization
header
The authorization type passed
in the HTTP
Authorization header
is not supported.
Check that authentication data is correct.
Authorization header
has invalid syntax
Incorrect format of the HTTP
Authorization header.
OAuth credentials
are not specified
Authentication data was not
specified in the request.
OAuth token is not
specified
The request does not specify
an access token (the
oauth_token parameter).
OAuth client id is
not specified
the application identifier
(oauth_client_id
parameter).
OAuth login is not
specified
the user login (the
oauth_login parameter).
Description
Explanation
Possible solution
Token is invalid
The specified access token
(oauth_token parameter)
is invalid.
Check that authentication data is correct. If it
is valid, get a new access token and repeat
the request with new authentication data.
User account
is disabled
The user account that
the specified access token
was issued for has been blocked.
Contact the technical support service for the
Yandex.Market partner interface.
Client id is invalid
The specified application
identifier
(oauth_client_id
parameter) is invalid.
Check that authentication data is correct. If it
is valid, get a new identifier for the
application and repeat the request with
new authentication data.
Login is invalid
The specified user login
(oauth_login parameter)
is invalid.
Scope is invalid
The specified access token
(oauth_token parameter)
does not have the necessary
set of rights.
Get a new access token and select permission
to use the Yandex.Market Partner API when
getting it; repeat the request with
new authentication data.
Access denied
Access to the specified resource
is forbidden.
Check whether the resource is specified
correctly, and whether the user login
has access rights to it.
Access to API denied
for the client/
campaign
The client or campaign is not
allowed to access
the Yandex.Market Partner API.
Agency clients should contact their agency
about getting access to the Yandex.Market
Partner API.
For the 403 Forbidden error:
Developer's guide
Other short descriptions that can be found in messages about this error are provided in the descriptions of the
corresponding resources.
•
•
•
•
•
For the 404 Not Found error:
Description
Explanation
Possible solution
Login not found:
'login'
The login name specified in the
request was not found.
Make sure the correct login name is passed.
Order not found:
'orderId'
The order specified in the
Check whether the correct order ID was
passed.
Feed not found:
'feedId'
The price list specified in the
Check whether the correct price list ID was
passed.
Model not found:
'modelId'
The model specified in the
Check whether the correct model ID was
passed.
For the 405 Method Not Allowed error:
Description
Explanation
Possible solution
Request method
'method'
not supported
The requested HTTP method
is not supported.
Check which methods are supported by the
resource. There is a list of all methods in the
section API methods.
For the 415 Unsupported Media Type error:
Description
Explanation
Possible solution
Unknown content-type:
'content-type'
The requested content type
is unknown.
Pass one of the supported content types.
Content type
'content-type'
not supported
The requested content type is not
supported.
Pass one of the supported content types.
Missing Content-Type
The content type is not specified.
Pass the content type.
For the 420 Enhance Your Calm error:
Description
Explanation
Possible solution
Hit rate limit of 'N'
parallel requests
Exceeded the global limit on the
number of simultaneous
requests to the Yandex.Market
Partner API.
Reduce the number of parallel requests to the
Partner API for a single campaign/partner
to N requests.
Hit rate limit of 'N'
requests per 'period'
for resource 'R'
Exceeded the resource limit
of N number of requests
to resource R over the period
for the same campaign/partner.
The limit will be in effect until the time
shown in the X-RateLimitResource-Until header. The resource
will be usable after this time.
For the 503 Service Unavailable error:
Description
Explanation
Possible solution
Service temporarily
unavailable. Please,
try again later
The server is temporarily
unavailable due to high loads.
Try repeating the request again later.
Sample error message
XML
Sample request:
Developer's guide
GET /v2/campaigns.xml HTTP/1.1
User-Agent: curl/7.19.7 (x86_64-pc-linux-gnu) libcurl/7.19.7 OpenSSL/0.9.8k zlib/1.2.3.3
libidn/1.15
Host: api.partner.market.yandex.ru
Accept: */*
Authorization: OAuth
oauth_token=35962aaccc064c5584c1d8accf1b22e1,oauth_login=,oauth_client_id=b12320932d4e40
1ab6e1ba43d553d433
Sample response:
<?xml version="1.0" encoding="UTF-8"?>
<response><error code="401"><message>OAuth login is not specified</message></error></
response>
JSON
Sample request:
GET /v2/campaigns.json HTTP/1.1
User-Agent: curl/7.19.7 (x86_64-pc-linux-gnu) libcurl/7.19.7 OpenSSL/0.9.8k zlib/1.2.3.3
libidn/1.15
Host: api.partner.market.yandex.ru
Accept: */*
Authorization: OAuth
oauth_token=35962aaccc064c5584c1d8accf1b22e1,oauth_login=,oauth_client_id=b12320932d4e40
1ab6e1ba43d553d433
Sample response:
{"error":{"message":"OAuth login is not specified","code":401}}
Restrictions for requests to the Yandex.Market Partner API are divided into three types:
•
Global limits (restrictions on the number of simultaneous requests).
•
Resource limits (restrictions on the number of requests to the same resource over a continuous length of time,
such as a 24-hour period).
•
Functional limits (restrictions on the amount of data passed or returned in a single request).
Global limits restrict the volume of simultaneous (parallel) requests for a single campaign (when requests are to
a resource for a particular campaign, such as GET /campaigns/{campaignId}/offers) or for a single partner (when
requests are to a resource outside the context of a campaign, such as GET /campaigns or GET /campaigns/
by_login/{login}). No more than two simultaneous requests are allowed.
When the limit is exceeded, the server returns a special HTTP code "420 Enhance Your Calm" with
an explanation:
Hit rate limit of 2 parallel requests
Resource limits restrict the volume of requests to the same Partner API resource over a continuous period
of time for the same campaign (when requests are to a resource for a particular campaign, such as GET /
campaigns/{campaignId}/offers) or from the same partner (when requests are to a resource outside the context
of a campaign, such as GET /campaigns or GET /campaigns/by_login/{login}). The request volume refers to the
number of requests and the amount of data passed and returned for a single request.
For most resources, the limits only apply to the number of requests. These limits are individual for each resource,
and their values are provided in the descriptions for each group of methods.
For some resources, limits apply to the total amount of data passed and returned in requests to the same resource.
These limits are calculated individually for each campaign/partner. Criteria for calculating these limits
are provided in the description of these resources.
Some of the resources are put in groups that have a shared resource limit. In this case, limits apply to the volume
of requests to any of the resources in the group over a continuous period of time.
Developer's guide
Note:
Prices on product offers, bid values, and the Yandex.Market assortment are updated approximately once every
two to three hours. So it doesn't make sense to process requests that return the assortment or information about
modifications for the same product offer, or set bids, more often than once an hour.
Individual limits for these requests are calculated so that a shop is able to request information or set bids for all
its products with an hourly interval.
Each response to a request returns special HTTP headers that specify the state of the resource limit for the
campaign/partner:
•
The X-RateLimit-Resource-Limit header contains the numerical value of the limit.
•
The X-RateLimit-Resource-Until header contains the date when the limit expires, in RFC822
format (for example, Thu, 26 Jan 2012 08:49:37 GMT).
•
The X-RateLimit-Resource-Remaining header contains the numerical value of the volume
of requests to the given resource remaining before the limit is exceeded.
When the limit is exceeded, the server returns a special HTTP code "420 Enhance Your Calm" with
an explanation, such as:
Hit rate limit of 10000 points per 1 day for resource /campaigns.json
Functional limits apply to the amount of data passed or returned for a resource per request. These limits
are individual for each resource, and their values are provided in the descriptions for each group of methods,
as well as in the documentation of the methods themselves.
When the limit is exceeded, the server returns a special HTTP code "400 Bad Request" with an explanation.
Versions
This page describes the Partner API versions for methods that merchants use to make requests to Yandex.Market.
When making requests to the Yandex.Market API, the merchant must specify the version in the resource URL,
in the format:
v<major_version>
The major version number of the API is updated for significant changes to resources, logic, or restrictions that
may cause applications that are making requests to earlier versions of the API to work incorrectly on the older
version.
The minor version number is updated only for the addition of new resources, features, output parameters,
and other changes that still allow applications that are making requests to an earlier version of the API to continue
working correctly on the older version. It is specified in method descriptions to make it convenient to track these
changes, in the format v<major_version>.<minor_version>.
Attention!
In requests, the current major version number should be specified. The minor version is not specified in requests.
Developer's guide
If the version is not specified in the request, the last major version of the Partner API will be selected for this
method. We recommend explicitly setting the version for every resource to avoid unexpectedly using a new
major version with a changed interface.
Version 2.3 from November 6, 2013.
Added the method:
•
GET /regions/{regionId}/children.
Updated methods:
•
GET /regions — Changed restrictions and added the new type parameter in output data.
•
GET /regions/{regionId} — Changed restrictions and added the new type parameter in output data.
•
GET /campaigns/{campaignId}/region — Added the new type parameter in output data.
•
GET /campaigns/{campaignId}/orders —Added the new type parameter in output data.
•
GET /campaigns/{campaignId}/orders/{orderId} — Added the new type parameter in output data.
•
PUT /campaigns/{campaignId}/orders/{orderId}/delivery — Updated error descriptions.
•
PUT /campaigns/{campaignId}/orders/{orderId}/status — Updated error descriptions.
Version 2.2 from October 8, 2013.
Added methods:
•
PUT /campaigns/{campaignId}/orders/{orderId}/status
•
PUT /campaigns/{campaignId}/orders/{orderId}/delivery
•
GET /campaigns/{campaignId}/orders/{orderId}
•
GET /campaigns/{campaignId}/orders
Version 2.1 from May 16, 2013.
Added methods:
•
GET /campaigns/{campaignId}/settings
•
GET campaigns/{campaignId}/bids/settings
Updated methods:
•
GET /campaigns/{campaignId}/stats/offers — Introduced limits on the number of requests per day.
Version 2.0 from March 5, 2013
Attention!
Version 2.0 of the Partner API for methods that are used to make requests to Yandex.Market that are not
compatible with earlier versions.
Added methods:
•
POST campaigns/{campaignId}/bids
•
GET campaigns/{campaignId}/feeds
•
GET campaigns/{campaignId}/feeds/{feedId}
•
GET campaigns/{campaignId}/feeds/{feedId}/categories
•
GET campaigns/{campaignId}/feeds/categories
Developer's guide
Updated methods:
•
GET campaigns/{campaignId} and GET campaigns/{campaignId}/logins — Changed the input data
structure and updated error descriptions.
•
GET campaigns/{campaignId}/offers — Added a feature for searching for product offers by category
in the price list, along with outputting the offer ID from the price list in the response, and changed
the output data structure.
•
GET campaigns/{campaignId}/balance — Changed output data structure.
•
GET models — Changed the output data structure for information about search results.
•
PUT campaigns/{campaignId}/bids — Added a feature for working with bids by the product offer ID, and
changed the output data structure.
•
POST campaigns/{campaignId}/bids/recommended and PUT campaigns/{campaignId}/bids/
recommended — Added a feature for getting/setting recommended values for the basic bid, along with
the ability to work with bids using the product offer ID.
•
PUT campaigns/{campaignId}/bids/recommended — Changed the output data structure.
•
GET campaigns/{campaignId}/stats/main — Introduced time limits for how long impressions statistics
are available, and changed the output data structure.
•
GET campaigns/{campaignId}/stats/offers — Added a feature for getting statistics for a specific product
offer and changed the output data structure.
Updated the description of settings in the partner interface for setting bids using the Partner API.
Version 1.2 from July 31, 2012
The Yandex.Market Partner API added a feature for getting information about average prices for product
modifications, along with information about prices for product offers of modifications.
Added methods:
•
GET campaigns/{campaignId}/region
•
GET models/{modelId}
•
GET models
•
POST models
•
GET models/{modelId}/offers
•
POST models/offers
•
GET regions
•
GET regions/{regionId}
The request response structure was added to the documentation for each method, and the structure of the
request body was added for PUT and POST type methods. Parameter names in structure descriptions
are clickable; when clicked, a popup hint opens with a description of the parameter.
Developer's guide
Changed resource limits for the methods: GET campaigns/{campaignId}/offers, PUT campaigns/
{campaignId}/bids, POST campaigns/{campaignId}/bids/recommended and PUT campaigns/{campaignId}/
bids/recommended.
Version 1.1 from March 28, 2012
Updated methods:
•
GET campaigns/{campaignId}/stats/main — Introduced a 180-day limit for the time period for getting
statistics.
•
GET campaigns, GET campaigns/{campaignId} and GET campaigns/by_login/{login} — Added output
of campaign states.
•
GET campaigns/{campaignId}/offers — Added a limit for the page input data parameter.
Version 1.0 (Beta) from February 28, 2012.
Added methods:
•
GET campaigns
•
GET campaigns/{campaignId}
•
GET campaigns/{campaignId}/logins
•
GET campaigns/by_login/{login}
•
GET campaigns/{campaignId}/offers
•
PUT campaigns/{campaignId}/bids
•
POST campaigns/{campaignId}/bids/recommended
•
PUT campaigns/{campaignId}/bids/recommended
•
GET campaigns/{campaignId}/balance
•
GET campaigns/{campaignId}/stats/main
•
GET campaigns/{campaignId}/stats/offers
Debugging the API
In order to investigate an error for an application accessing the Yandex.Market Partner API, a manager may ask
you to repeat the problematic API request using a debugging token.
After getting a debugging token from the manager, you will need to send the problem request with the dbg
parameter and the token value added to the resource URL.
Sample request with a debugging token:
GET https://api.partner.market.yandex.ru/v2/campaigns.json?dbg=C6000001DD36EDFC
Note:
Each debugging token is unique and can only be used for three days after it has been generated and in no more
than five requests to the Yandex.Market Partner API.
Developer's guide
Requests to the merchant 18
Requests to the merchant
Authentication
A merchant must be able to authenticate requests from Yandex.Market in order to differentiate them from
unauthorized third-party requests. An access token is used for authorizing Yandex.Market; it is passed in every
request in a URL parameter or HTTP header (depending on the settings in the partner interface).
Example:
•
In URL parameters:
POST https://<request URL>/cart?auth-token=546df3as346fasd6f2312 HTTP/1.1
•
In the HTTP Authorization header:
Authorization: 546df3as346fasd6f2312
Note:
Since the access token is passed in every request from Yandex.Market, this parameter is not shown in examples
in order to simplify documentation of the API methods.
The merchant must compare the passed token with the token that was generated in the partner interface earlier.
For a request that tries to pass an invalid token or omits the token, the merchant must return the error 403
Forbidden.
An access token can be generated only after switching to testing mode for the “Purchase on Market” program.
To do this, go to the section Настройки API заказа (Settings for Market Ordering program) on the page
Настройки (Settings) in the partner interface and click Изменить (Change) next to the parameter
Авторизационный токен (Access token).
If necessary, the access token can be replaced. The new token becomes active immediately after it is generated
if you select the option “Применить сейчас (Apply now)” while changing the token. If you select the option
“Применить позже (Apply later)”, the old token remains active. In this case, both tokens are shown in the
partner interface; the new token can be activated whenever convenient for the merchant.
See also
Request method
SSL certificate
SSL certificate
Yandex.Market sends requests to a merchant only if the merchant's application that is taking requests from
Yandex.Market uses the HTTPS protocol with an SSL certificate.
The merchant can use any type of SSL certificate, either signed by an official certificate authority, or self-signed.
Developer's guide
Generating an SSL certificate
1. Install the OpenSSL utility.
2. Generate a private key using the command openssl genrsa -out server.key 2048.
3. Execute the request for a certificate using the command: openssl req -new -key server.key
-out server.csr.
4. Specify the corresponding data in the lines:
Country Name (2 letter code) [AU]:
State or Province Name (full name) [Some-State]:
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:
Organizational Unit Name (eg, section) []:
Common Name (eg, YOUR name) []:
Email Address []:
Please enter the following 'extra' attributes to be sent with your certificate
request
A challenge password []:
An optional company name []:
Note:
•
The most important line to fill in is the Common Name line, where you must indicate the shop's domain
name.
•
For a certificate signed by a certificate authority:
•
•
The Country Name line must have a country name entered in accordance with the ISO 3166
standard.
•
The domain email address or email address of the site administrator must be specified.
For a self-signed certificate, it is not necessary to enter information in the Email Address,
A challenge password and An optional company name lines.
Further steps, if the shop is planning to use a certificate signed by a CA:
1. Give the server.csr file located in the /home/login/ directory to a company that issues
SSL certificates so it can be signed.
2. Install the certificate you get from the CA on your web server, following the instructions for it.
Further steps, if the shop is planning to use a self-signed certificate.
1. Generate a self-signed certificate using the command openssl req -new -x509 -days 365 key server.key -out server.crt.
Pay attention to the -days parameter — how many days the certificate will be valid. You can set any period
of validity.
2. Get the SHA1 fingerprint using the command openssl x509 -in server.crt -sha1 -noout
-fingerprint.
3. In the partner interface, go to the page Настройки API заказа (Settings for Market Ordering
program) in the menu Настройки (Settings), click изменить (change) next to the parameter SHA1
fingerprint and enter the certificate's fingerprint in the box.
4. Install your self-signed certificate on your web server, following the instructions for it.
Replacing the certificate
If necessary, the certificate can be replaced. If a self-signed certificate is replaced with a certificate signed by a
CA, you do not need to do anything in the partner interface. If a self-signed certificate is replaced with a different
self-signed certificate, you need to indicate the new SHA1 fingerprint in the partner interface.
The shop's certificate is validated with the new digital signature immediately after the certificate is replaced.
Developer's guide
If there is a problem with the certificate, the request logs will show an SSL_ERROR error.
See also
Authentication
Request method
Requests from Yandex.Market are sent over the HTTPS protocol in the following format:
<method type>
https://<request URL>/<resource>
where
•
<method type> ― Depends on the resource.
•
<request URL> ― The URL where the merchant accepts requests from Yandex.Market (set in the
partner interface).
•
<resource> ― The name of the resource to perform the action on.
Note:
In each request, Yandex.Market passes an access token in a URL parameter or HTTP header.
If an error occurs, the merchant must stop processing the request and return an error message. A list of errors
and descriptions is provided in the section Error messages.
URL
We recommend that merchants specify a base URL, such as: https://shop.ru/market/api. For this
example, the request POST /cart will be sent to the URL https://shop.ru/market/api/cart.
Chain stores should set different URLs for different stores, so that it is possible to identify by the URL which
store the call is being sent to, such as:
•
https://shop-network.ru/market/api/Moscow
•
https://shop-network.ru/market/api/St-Petersburg
•
https://shop-network.ru/market/api/Ekaterinburg
This kind of differentiation helps you correctly implement the API logic within the chain of stores.
Timeout
When sending requests to a merchant, Yandex.Market uses timeouts on connecting and getting a response. If the
merchant does not respond to a request within the given amount of time, Yandex.Market registers this as an
error response from the merchant. The timeout for connection is 1 second; the timeout for getting a response
depends on the resource and is indicated on the appropriate page of the resource.
See also
Data format in the request and response
Data format in the request and response
Either one of two serialization formats can be used — XML or JSON.
Developer's guide
The merchant should specify the desired format for request data in the API settings in the partner interface.
The response data format should match the request data format.
In the response, the data format is specified in the HTTP Content-Type header. Acceptable header values:
•
application/xml
•
application/json
See also
Request method
Description of the JSON format
Error messages
For a request from Yandex.Market, the merchant is expected to respond with 200 OK (request successfully
processed), but if there is an error, the merchant can send an error message. Acceptable HTTP codes for merchant
responses:
•
500 Internal Server Error — Error on the merchant's side.
•
400 Bad Request — The request from Yandex.Market violates the API logic.
•
403 Forbidden — Yandex.Market passed an invalid token.
Versions
Below is a list of Partner API versions for the methods that Yandex.Market uses to make requests to merchants.
Version from October 8, 2013
Added methods:
•
POST /cart
•
POST /order/accept
•
POST /order/status
Debugging the API
Introduction
To ensure correct implementation of the API when getting requests from Yandex.Market (the Market
Ordering program), a debugging feature is provided in the partner interface.
The debugging interface lets you reproduce the order process. You can add products to the shopping cart, select
payment methods and delivery options, and create and cancel orders. As a result, the shop gets requests from
Yandex.Market in real time.
All orders created in the debugging interface are sent to the shop with the true value for the fake parameter,
which lets the merchant differentiate between test orders and real ones.
Test orders are not rated, and errors with them do not cause the shop to be excluded from the program.
Restrictions
Request logs are stored for one week, and test orders are stored for 30 days.
Developer's guide
Accessing API debugging
The debugging interface is available in the partner interface in the menu Настройки (Settings) → Отладка
API заказа (API Debugging for Market Ordering program).
To get access to API debugging, the merchant must:
•
Turn on testing mode in the partner interface on the page Настройки (Settings) → Параметры
размещения (Publishing parameters).
•
Indicate the required information in the partner interface on the page Настройки (Settings) →
Настройки API заказа (Settings for Market Ordering program).
Note:
The merchant cannot test the API if none of the shop's products is published on Yandex.Market.
Creating a test order
A test order is made on the Новый заказ (New order) tab.
Getting a request for product information
To test getting a request for information about products in a customer's shopping cart:
•
Add products to the cart (use the button with an arrow in the list of products).
•
Set the customer's region (in the box under the search).
•
Click the Актуализировать (Update) button.
The merchant will get a request via the method POST /cart (Request for product information).
The list of products shows only the products from the shop that are part of the Market Ordering program.
The merchant can use search in products in the list.
Developer's guide
Note:
Products will be displayed in the list only after enabling testing mode and performing another update
on Yandex.Market.
Getting a request to accept an order and notification of changes to order status
To test getting a request to accept an order and notification of changes to order status:
•
Indicate the delivery method and payment method.
•
Enter test user data (address, name, phone number, and so on).
•
Click the Оформить заказ (Create order) button.
Note:
If the region (city) was changed while filling in the delivery parameters, you must update the data for products
in the cart by clicking the Актуализировать (Update) button.
The merchant gets requests with the following methods in the order shown:
1. POST /cart (Request for product information).
2. POST /order/accept (Passing the order and request to accept the order) with the order status
RESERVED.
3. POST /order/status (Notification of a new order status) with the order status PROCESSING.
Attention!
Notification of status changes is sent to the merchant only if a response was received from the merchant
indicating acceptance of the order.
The created order is shown on the Все заказы (All orders) tab with the status “в обработке (processing)”.
Reserving an order
To test the process of reserving products, after setting delivery parameters and test user data, click the Резерв
(Reserve) button. In this case, the merchant gets requests with the following methods in the order shown:
1. POST /cart (Request for product information).
2. POST /order/accept (Passing the order and request to accept the order) with the order status
RESERVED.
The reserved order is shown on the Все заказы (All orders) tab with the corresponding status.
Actions with orders
Created test orders are displayed on the Все заказы (All orders) tab.
Developer's guide
Clicking the order ID expands detailed information, such as the product names, quantities, payment method,
delivery address, and so on.
If the order has the status“зарезервирован” ("reserved"), the following customer actions can be emulated:
•
Buyer confirmation of the order.
To do this, click the Заказать (Order) button. The merchant will get a POST /order/status request
specifying the order status PROCESSING.
•
No order confirmation from the buyer.
An order is reserved for 10 minutes; if the Заказать (Order) button has not been clicked during this time,
the order will be canceled by Yandex.Market, and the merchant will get a POST /order/status request
specifying the order status CANCELLED.
If the order has the status “в обработке” ("processing"), the following customer action can be emulated:
•
Order cancellation by the buyer.
To do this, click the Отменить (Cancel) button. The merchant will get a POST /order/status request
specifying the order status CANCELLED.
Viewing logs
Logs of all requests are displayed on the Лог API (API log) tab.
Click the buttons in the Запрос (Request) and Ответ (Response) columns to open popup windows with request
and response data. Click a line of the log to display additional information below it.
Developer's guide
Verification tests
If a shop gets requests from Yandex.Market for the Market Ordering program, it has to pass regular automatic
verification tests. As part of verification, a Yandex.Market robot makes a particular set of requests to the shop,
and the shop must respond and pass the required information in the response body. If invalid responses
are received from the shop, it may be excluded from the program. An invalid response is considered:
•
No response within the established timeout.
•
A 200 OK response that contains invalid data in the response body.
•
The responses 400 Bad Request, 500 Internal Server Error, or any other response codes
other than 200 OK.
Merchants can debug their applications in the partner interface before verification begins. Debugging
is described in the section Debugging the API.
Types of verification tests
The following verification tests are made via the API:
•
Verifying correct order processing before enabling the program
•
Regular verification of availability via the API
•
Checking for resolution of errors in request handling
•
Regular verification of correct authorization of Yandex.Market
Verification tests are made in the following order:
Before joining
the Market
Ordering
program
While
participating
in the program
For 24 hours
after leaving
the program
Before re-joining
the program
Correct order processing
✔
—
—
✔
Shop availability via the API
—
✔
✔
✔
Resolving errors in request
processing
—
✔
✔
—
Correct authorization
of Yandex.Market
—
✔
—
✔
Verifying correct order processing before enabling the program
After a merchant changes the parameter Участие в программе Заказ на Маркете (Participation in the
Market Ordering program) to «включено» (enabled) in the section Настройки (Settings) → Параметры
Developer's guide
размещения (Publishing parameters) in the partner interface, a robot sends control orders to check whether
the shop is able to accept and process orders:
1. The robot sends the shop a request to accept an order using the method
The request body specifies in the comments that this is a control order.
POST /order/accept .
2. The shop must accept the control order in response to the request.
3. The merchant will get a POST /order/status request specifying the order status PROCESSING
or CANCELLED.
4. If the order status PROCESSING is received, the merchant must perform the action described in the order
comments:
•
Cancel the order within three days by sending a request to Yandex.Market using the method PUT /
campaigns/{campaignId}/orders/{orderId}/status (any cancellation reason can be
specified).
•
Switch the order to the DELIVERY status (sent out for delivery) within three days by sending a request
to Yandex.Market using the method PUT /campaigns/{campaignId}/orders/
{orderId}/status.
If the CANCELLED status was received for the order, the merchant does not need to do anything else.
Note:
If the merchant refuses to accept the order (the response indicates the false value for the accepted
parameter), the robot repeats the order acceptance request for other products in the shop. If 5 rejections in a
row are received from the shop, an error is registered and the shop may be excluded from the Market Ordering
program.
A control order is used to verify that a shop is able to accept and process non-standard orders. For this purpose,
the control order may include:
•
A heavy or oversize item (if the shop sells any).
•
A large number of items (up to 10 items).
•
Delivery to a different region (if the shop supports this type of delivery).
•
Delivery to surrounding areas outside of the city (if the shop supports this type of delivery).
In addition, the shop is also tested for correctly changing the order status.
Verification period: Before enabling the Market Ordering program the first time, or before re-enabling it.
If the shop is not able to correctly process the control order, it will not be allowed to join the Market Ordering
program. The shop can send a request to repeat verification tests from the partner interface.
Regular verification of availability via the API
A ping bot constantly checks the shop's availability via the API by sending requests to the shop using the POST /
cart method. The shop must send a response to each request and pass all necessary information in the response.
Verification period: During participation in the program, for 24 hours after disabling the program, and before
re-enabling the Market Ordering program.
Verification frequency: Once every 10 minutes. If a response is invalid, the ping bot starts checking once every
minute. If there are 5 invalid responses within 30 minutes, the Market Ordering program is automatically disabled
for the shop.
Re-enabling the program:
•
Automatic if 5 requests in a row are processed correctly by the shop within 24 hours after disabling. The ping
bot resumes the verification frequency of once every 10 minutes.
•
In the partner interface if more than 24 hours have passed since disabling.
Developer's guide
Checking for resolution of errors in request handling
If it is detected that while participating in the Market Ordering program a merchant has incorrectly processed
requests from Yandex.Market with the methods POST /order/accept and POST /order/status,
the robot performs an extra verification test of the shop using the POST /order/accept request. If the shop
returns a valid response accepting the order, the order will be canceled within ten minutes by a POST /order/
status request specifying the status CANCELLED.
Verification period:
•
While participating in the Market Ordering program, only if errors occurred when processing requests.
•
For 24 hours after disabling the Market Ordering program, only if errors occurred with request processing
while participating in the program.
Verification frequency: Once per minute after an error has been detected. If there are five invalid responses
within 30 minutes, the program is automatically disabled for the shop. Verification will continue for 24 hours
after disabling, with the frequency of one test every 10 minutes.
Re-enabling the program:
•
Automatic if 5 requests in a row are processed correctly by the shop within one day after disabling. In this
case, the robot will stop performing this type of test.
•
In the partner interface if more than 24 hours have passed since disabling.
Regular verification of correct authorization of Yandex.Market
A merchant must be able to authenticate requests from Yandex.Market and differentiate them from unauthorized
third-party requests by checking the access token.
As part of this verification, the shop is passed an invalid access token. If the shop sends the response 200 OK,
the request logs will show the error INVALID_RESPONSE with the subtype IGNORED_WRONG_TOKEN. If the
merchant does not fix this error, the program may be disabled for the shop.
Verification period: During participation in the program and before re-enabling the Market Ordering program.
Verification frequency: Once per day.
Re-enabling the program: in the partner interface. If disabled for this error, the shop cannot have the program
re-enabled automatically.
Attention!
When a shop is automatically disabled for errors processing requests from Yandex.Market, only the Market
Ordering program is disabled. The shop continues being published on Yandex.Market.
Error logs
The log of errors found in merchant responses to Market requests is available on the page Контроль качества
(Quality control) → Ошибки API (API errors) in the partner interface. Information about passing the control
order is displayed on the page Контроль качества (Quality control) → Контрольный заказ (Control
order). The main types of errors and reasons for failing control order verification are listed in the Help section
Ошибки по программе «Заказ на Маркете» (Errors for the Market Ordering program).
Developer's guide
28
API methods
Links to descriptions of API methods are provided below.
Basic methods
List of user campaigns: GET campaigns
Information about a campaign: GET campaigns/{campaignId}
List of logins associated with a campaign: GET campaigns/{campaignId}/logins
List of campaigns accessible by a login: GET campaigns/by_login/{login}
Campaign settings: GET campaigns/{campaignId}/settings
Placement settings
Information about the region of a campaign on Yandex.Market: GET campaigns/{campaignId}/region
Assortment
Information about product offers shown on Yandex.Market: GET campaigns/{campaignId}/offers
List of the campaign's price lists: GET campaigns/{campaignId}/feeds
Information about a price list: GET campaigns/{campaignId}/feeds/{feedId}
List of categories in a price list: GET campaigns/{campaignId}/feeds/{feedId}/categories
List of campaign categories: GET campaigns/{campaignId}/feeds/categories
Product modifications
Information about a modification: GET models/{modelId}
Information about modifications that meet the specified search conditions: GET models
Information about multiple modifications: POST models
Information about product offers shown on the product profile: GET models/{modelId}/offers
Information about product offers shown on multiple product profiles: POST models/offers
Managing bids
Information about bids set for product offers: POST campaigns/{campaignId}/bids
Setting and removing bids on product offers: PUT campaigns/{campaignId}/bids
Recommended bids on product offers for priority placement on Yandex.Market: POST campaigns/
{campaignId}/bids/recommended
Setting recommended bids on product offers: PUT campaigns/{campaignId}/bids/recommended
Bid settings: GET campaigns/{campaignId}/bids/settings
Finances
Current campaign balance, along with the expenditure forecast and the recommended payment amount: GET
campaigns/{campaignId}/balance
Statistics
Basic campaign statistics (clicks and expenditures): GET campaigns/{campaignId}/stats/main
Basic daily statistics (clicks and expenditures) for a campaign: GET campaigns/{campaignId}/stats/main-daily
Basic weekly statistics (clicks and expenditures) for a campaign: GET campaigns/{campaignId}/stats/mainweekly
Basic monthly statistics (clicks and expenditures) for a campaign: GET campaigns/{campaignId}/stats/mainmonthly
Statistics for product offers: GET campaigns/{campaignId}/stats/offers
Geobase
Information about a region that meets the specified search conditions: GET regions
Information about a region: GET regions/{regionId}
Information about child regions: GET /regions/{regionId}/children
Purchase on Market
Request for product information: POST /cart
Passing an order and request to accept order: POST /order/accept
Notification of changes to the order status: POST order/status
Changing the order status: PUT /campaigns/{campaignId}/orders/{orderId}/status
Changing conditions for order delivery: PUT /campaigns/{campaignId}/orders/{orderId}/delivery
Information about a requested order: GET /campaigns/{campaignId}/orders/{orderId}
Information about requested orders: GET /campaigns/{campaignId}/orders
Developer's guide
29
Basic methods
Use the basic methods to get information about campaigns on Yandex.Market.
Method
Short description
Restrictions
GET campaigns
Returns a list of user campaigns.
10000 requests per day.
GET campaigns/{campaignId}
Returns information about the specified 10000 requests per day.
campaign.
GET campaigns/{campaignId}/logins
Returns a list of logins associated with 10000 requests per day.
the specified campaign.
GET campaigns/by_login/{login}
Returns a list of campaigns that
the specified login name has access
rights for.
User campaigns
Description
GET /campaigns
Returns a list of user campaigns on Yandex.Market. This list corresponds to the list of campaigns displayed
in the Yandex.Market partner interface on the "My shops" page.
Note:
For agency users, the list contains subagency campaigns.
Resource URL:
https://api.partner.market.yandex.ru/v2/campaigns.[format]
Output data
Structure of output data:
XML
<campaigns>
<campaign id="{number}" domain="{string}" state="{number}">
<state-reasons>
<reason id="{number}"/>
...
</state-reasons>
</campaign>
...
</campaigns>
Developer's guide
30
JSON
{
"campaigns":
[
{
"id":{number},
"domain":"{string}",
"state":{number},
"stateReasons":
[
{number},
...
]
},
...
]
}
Parameter descriptions:
Parameter
for XML
format
Parameter
for JSON
format
campaigns
campaigns
Type
Value
List of campaigns.
Parameters nested in campaigns
campaign
Description of a campaign.
Parameters nested in campaign
id
id
Number
The campaign ID.
domain
domain
String
URL of the campaign.
state
state
Number
State of the campaign.
Possible values:
statereasons
stateReason
s
•
1 — Active campaign.
•
2 — Inactive campaign.
•
3 — Campaign is being activated.
•
4 — Campaign is being deactivated.
List of reasons for the campaign state.
This parameter is output only when the state parameter has the
following values:
•
•
Parameters nested in state-reasons/stateReasons
reason
Description of a reason. Each reason is explained in a separate
reason parameter.
Parameters nested in reason
id
Number
Reason code.
Developer's guide
31
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
Possible values:
•
5 — Campaign is being approved.
•
6 — Campaign needs approval.
•
7 — A manager has deactivated or is deactivating the campaign.
•
9 — The campaign is inactive or is being deactivated due to financial
issues.
•
11 — The campaign is inactive or is being deactivated due to errors
in the campaign's price list.
•
12 — A user has deactivated or is deactivating the campaign.
•
13 — The campaign is inactive or is being deactivated due to
unacceptable quality.
•
15 — The campaign is inactive or is being deactivated because
duplicated shops have been detected.
•
16 — The campaign is inactive or is being deactivated due to other
quality issues.
•
20 — The campaign is inactive or is being deactivated based on a
schedule.
•
the campaign's site is temporarily unavailable.
•
24 — The campaign is inactive or is being deactivated due to a lack
of information about the shop.
•
of outdated information.
Error descriptions
If an error occurs, the server returns the HTTP response code and a brief error description.
Examples
XML
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns.xml
Sample response:
<response>
<campaigns>
<campaign id="10001" domain="nif-nif.yandex.ru" state="2">
<state-reasons>
<reason id="6"/>
<reason id="9"/>
</state-reasons>
</campaign>
<campaign id="10002" domain="nuf-nuf.yandex.ru" state="4">
<state-reasons>
<reason id="21"/>
</state-reasons>
</campaign>
<campaign id="10003" domain="naf-naf.yandex.ru" state="1"/>
</campaigns>
</response>
JSON
Sample request:
Developer's guide
32
GET https://api.partner.market.yandex.ru/v2/campaigns.json
Sample response:
{"campaigns": [
{"id":10001,"domain":"nif-nif.yandex.ru","state":2,"stateReasons":[6,9]},
{"id":10002,"domain":"nuf-nuf.yandex.ru","state":4,"stateReasons":[21]},
{"id":10003,"domain":"naf-naf.yandex.ru","state":1}
]}
Information about a campaign
Description
GET /campaigns/{campaignId}
Returns information about the campaign specified in the request.
Resource URL:
https://api.partner.market.yandex.ru/v2/campaigns/{campaignId}.[format]
Input data
Parameter
Type
Value
Number
The campaign ID.
Mandatory
campaignId
Output data
XML
<state-reasons>
...
</state-reasons>
</campaign>
Output data structure for XML format prior to version 2.0 of the Yandex.Market Partner API
<campaign>
<state-reasons>
...
</state-reasons>
</campaign>
</campaign>
Developer's guide
33
JSON
{
"campaign":
{
"id":{number},
"state":{number},
"stateReasons":
[
{number},
...
]
}
}
Parameter
for XML
format
Parameter
for JSON
format
campaign
campaign
Type
Value
id
id
Number
The campaign ID.
domain
domain
String
state
state
Number
Possible values:
statereasons
stateReason
s
•
•
•
•
following values:
•
•
reason
reason parameter.
id
Number
Reason code.
Developer's guide
34
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
Possible values:
•
•
•
•
issues.
•
•
•
•
•
quality issues.
•
schedule.
•
•
•
Error descriptions
Errors containing brief descriptions typical for this method:
Description
Explanation
Possible solution
Information about the campaign
specified in the request is not
accessible.
Check whether the campaign ID is correct.
Error 403 Forbidden
Access denied
Examples
XML
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/10001.xml
Sample response:
<response>
<campaign id="10001" domain="nif-nif.yandex.ru" state="2">
<state-reasons>
<reason id="6"/>
<reason id="9"/>
</state-reasons>
</campaign>
</response>
Developer's guide
35
JSON
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/10001.json
Sample response:
{"campaign":{"id":10001,"domain":"nif-nif.yandex.ru","state":2,"stateReasons":[6,9]}}
Logins associated with a campaign
Description
GET /campaigns/{campaignId}/logins
Returns a list of logins that have access to the specified campaign.
Resource URL:
https://api.partner.market.yandex.ru/v2/campaigns/{campaignId}/logins.[format]
Input data
Parameter
Type
Value
Number
The campaign ID.
Mandatory
campaignId
Output data
XML
<logins>
<login>{string}</login>
...
</logins>
<logins>
<string>{string}</string>
...
</logins>
JSON
{
"logins":
[
"{string}",
...
]
}
Developer's guide
36
Parameter
for XML
format
Parameter
for JSON
format
logins
logins
Type
Value
List of login names.
Parameters nested in logins
login
String
Login.
Prior to version 2.0 of the Yandex.Market Partner API, the parameter
was called string in XML format.
Error descriptions
Description
Explanation
Possible solution
accessible.
Error 403 Forbidden
Access denied
Examples
XML
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/10001/logins.xml
Sample response:
<response>
<logins>
<login>nif-nif</login>
<login>naf-naf</login>
</logins>
</response>
JSON
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/10001/logins.json
Sample response:
{"logins":["nif-nif","naf-naf"]}
Campaigns accessible by login
Description
GET /campaigns/by_login/{login}
Returns a list of campaigns that the specified login name has access rights for.
Developer's guide
37
Resource URL:
https://api.partner.market.yandex.ru/v2/campaigns/by_login/{login}.[format]
Input data
Parameter
Type
Value
String
User login name.
Mandatory
login
Output data
XML
<campaigns>
<state-reasons>
...
</state-reasons>
</campaign>
...
</campaigns>
JSON
{
"campaigns":
[
{
"id":{number},
"state":{number},
"stateReasons":
[
{number},
...
]
},
...
]
}
Parameter
for XML
format
Parameter
for JSON
format
campaigns
campaigns
Type
Value
List of campaigns.
Parameters nested in campaigns
campaign
id
id
Number
The campaign ID.
domain
domain
String
state
state
Number
Developer's guide
38
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
Possible values:
statereasons
stateReason
s
•
•
•
•
following values:
•
•
reason
reason parameter.
Parameters nested in reason
id
Number
Reason code.
Possible values:
•
•
•
•
issues.
•
•
•
•
•
quality issues.
•
schedule.
•
•
•
Error descriptions
Description
Explanation
Possible solution
Error 403 Forbidden
Developer's guide
39
Description
Explanation
Possible solution
Access denied
Access to the specified resource
is forbidden.
An authenticated login only has access
to equivalent logins. For an agency, this means
subagency logins.
The login name specified in the
Make sure the login name is correct.
Error 404 Not Found
Login not found:
'login'
Examples
XML
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/by_login/nuf-nuf.xml
Sample response:
<response>
<campaigns>
<campaign id="10002" domain="nuf-nuf.yandex.ru" state="4">
<state-reasons>
<reason id="21"/>
</state-reasons>
</campaign>
</campaigns>
</response>
JSON
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/by_login/nuf-nuf.json
Sample response:
{"campaigns":[{"id":10002,"domain":"nuf-nuf.yandex.ru","state":4,"stateReasons":[21]}]}
Campaign settings
Description
GET /campaigns/{campaignId}/settings
Returns information about settings for the campaign specified in the request.
Note:
This method is available starting from version 2.1 of the Yandex.Market Partner API.
Resource URL:
https://api.partner.market.yandex.ru/v2/campaigns/{campaignId}/settings.[format]
Developer's guide
40
Input data
Parameter
Type
Value
Number
The campaign ID.
Mandatory
campaignId
Output data
XML
<settings shop-name="{string}" country-region="{number}" is-online="{boolean}" show-incontext="{boolean}" show-in-snippets="{boolean}" show-in-premium="{boolean}" use-openstat="{boolean}"/>
JSON
{
"settings":
{
"shopName":"{string}",
"countryRegion":{number},
"isOnline":{boolean},
"showInContext":{boolean},
"showInSnippets":{boolean},
"showInPremium":{boolean},
"useOpenStat":{boolean}
}
}
Parameter
for XML
format
Parameter
for JSON
format
settings
settings
Type
Value
Campaign settings.
Parameters nested in settings
shop-name
shopName
countryregion
countryRegi Number
on
ID of the region the shop is located in.
is-online
isOnline
Type of shop:
show-incontext
String
Logical
showInConte Logical
xt
Name of the shop on Yandex.Market. If the name is omitted,
the parameter value will be empty for XML, and it will be null
for JSON.
•
true — Online shop.
•
false — Offline shop.
Flag for whether the shop is a participant of the Yandex Advertising
Network:
•
true — Participant.
•
false — Not a participant.
Developer's guide
41
Parameter
for XML
format
Parameter
for JSON
format
show-insnippets
showInSnipp Logical
ets
show-inpremium
use-openstat
Type
showInPremi Logical
um
useOpenStat Logical
Value
Flag for whether data from the price list is used in Search:
•
true — Used.
•
false — Not used.
Flag for whether offers are displayed in the advertising block above
search results (Premium Placement):
•
true — Shown in Premium Placement.
•
false — Not shown in Premium Placement.
Flag for whether external internet statistics are used:
•
true — Used.
•
false — Not used.
Error descriptions
Description
Explanation
Possible solution
Error 403 Forbidden
Access denied
The campaign cannot be accessed. Check whether the campaign ID is correct.
Examples
XML
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/10001/settings.xml
Sample response:
<response>
<settings shop-name="Nif-Nif" country-region="213" is-online="true" show-incontext="true" show-in-snippets="true" show-in-premium="true" use-open-stat="true"/>
</response>
JSON
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/10001/settings.json
Sample response:
{"settings":{"shopName":"Nif-Nif", "countryRegion":213, "isOnline":true,
"showInContext":true, "showInSnippets":true, "showInPremium":true, "useOpenStat":true}}
Developer's guide
42
Placement settings
Use these methods to get information about campaign settings on Yandex.Market.
Method
Short description
Restrictions
GET campaigns/{campaignId}/region
Returns information about the local
region of a campaign
on Yandex.Market.
Campaign region
Description
GET /campaigns/{campaignId}/region
Returns the region the shop is located in. This method is used for online shops, because the region is not specified
for offline shops.
Note:
Resource URL:
https://api.partner.market.yandex.ru/v2/campaigns/{campaignId}/region.[format]
Input data
Parameter
Type
Value
Number
The campaign ID.
Mandatory
campaignId
Output data
XML
<region id="{number}" name="{string}" type="{string}">
<parent id="{number}" name="{string}" type="{string}">
...
</parent>
</region>
Developer's guide
43
JSON
{
"region":
{
"id":{number},
"name":"{string}",
"type":"{string}",
"parent":
{
"id":{number},
"name":"{string}",
"type":"{string}",
"parent":
{
...
}
}
}
}
Parameter
for XML
format
Parameter
for JSON
format
region
region
Type
Value
Shop region. This parameter is output only if the shop has a region
specified in the Yandex.Market partner interface.
Parameters nested in region
id
id
Number
ID of the region.
name
name
String
Name of the region.
type
type
String
Type of region. Possible values:
parent
parent
•
REGION — Region.
•
COUNTRY — Country.
•
COUNTRY_DISTRICT — Federal district (Russian "okrug").
•
REPUBLIC — Federation subject.
•
REPUBLIC_AREA — District within a federation republic.
•
CITY — City.
•
VILLAGE — Town or village.
•
CITY_DISTRICT — District within a city.
•
SUBWAY_STATION — Subway (underground) station.
•
OTHER — Another type of region that is not listed.
"Parent" region.
"Parent" regions are specified up to the country level.
Parameters nested in parent
id
id
Number
ID of the "parent" region.
name
name
String
Name of the "parent" region.
Developer's guide
44
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
type
type
String
parent
parent
•
REGION — Region.
•
•
•
•
•
CITY — City.
•
•
•
•
Recursively nested element for specifying higher-level "parent" regions.
Error descriptions
Description
Explanation
Possible solution
accessible.
Error 403 Forbidden
Access denied
Examples
XML
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/10001/region.xml
Sample response:
<response>
<region id="11380" name="Ivanovka" type="CITY">
<parent id="100295" name="Ivanovskiy region" type="REPUBLIC_AREA">
<parent id="11375" name="Amurskaya republic" type="REPUBLIC">
<parent id="73" name="Far East" type="COUNTRY_DISTRICT">
<parent id="225" name="Russia" type="COUNTRY"/>
</parent>
</parent>
</parent>
</region>
</response>
JSON
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/10001/region.json
Sample response:
Developer's guide
45
{"region":
{"id":11380, "name":"Ivanovka", "type":"CITY", "parent":
{"id":100295, "name":"Ivanovskiy region", "type":"REPUBLIC_AREA", "parent":
{"id":11375, "name":"Amurskaya republic", "type":"REPUBLIC", "parent":
{"id":73, "name":"Far East", "type":"COUNTRY_DISTRICT", "parent":
{"id":225, "name":"Russia", "type":"COUNTRY"}}}}
}
}
Developer's guide
46
Assortment
Use the assortment methods to get information about product offers and price lists for a campaign
on Yandex.Market.
Method
Short description
Restrictions
GET campaigns/{campaignId}/offers
Returns information about product
offers of a campaign
on Yandex.Market.
Individual number of requests per day;
1000 offers per request; search depth
of 50000 offers.
GET campaigns/{campaignId}/feeds
Returns a list of price lists for a
campaign on Yandex.Market.
GET campaigns/{campaignId}/feeds/
{feedId}
Returns information about the price list 10000 requests per day.
of a campaign on Yandex.Market.
{feedId}/categories
Returns a list of price list categories for a Individual number of requests per day;
1000 categories per request.
categories
Returns a list of categories for a
1000 categories per request.
For the methods GET campaigns/{campaignId}/feeds/{feedId}/categories and GET campaigns/{campaignId}/
feeds/categories, there is a group resource limit.
Product offers in a campaign
Description
GET /campaigns/{campaignId}/offers
Returns information about the campaign's product offers that are published on Yandex.Market and match
the given search query (if specified).
The search for product offers that are published on Yandex.Market works using a search query in the same
way Yandex.Market search works; results are returned using a pager.
For each found offer, the response to the request provides the offer's URL and name, the price and the currency
it is in, the Yandex.Market product profile the offer is associated with, and the auction bids for it.
Note:
Due to certain features of the Yandex.Market search, the pager's final pages sometimes show fewer results than
was indicated earlier on previous pages.
For this reason, we strongly recommend analyzing the contents of the pager parameter for each page you get.
Resource URL:
https://api.partner.market.yandex.ru/v2/campaigns/{campaignId}/offers.[format]
Developer's guide
47
Input data
Parameter
Type
Value
Number
The campaign ID.
String
Search query. The request language is supported.
Mandatory
campaignId
Optional
query
If omitted, searches for all the campaign's product offers that are published
on Yandex.Market.
shopCategor String
yId
ID of a category of product offers indicated in the campaign's price list. When this parameter
is set, the search for product offers is restricted to offers in the specified category.
This parameter is available starting in version 2.0 of the Yandex.Market Partner API.
feedId
String
Price list ID. When this parameter is set, the search for product offers is restricted to offers
in this price list.
Set this parameter if the shopCategoryId parameter is set and the campaign has more
than one price list registered.
pageSize
Number
The number of offers to output on the page with search results in the response.
Default value: 100 offers.
Maximum value: 1000 offers.
page
Number
Page number in results.
If omitted, the first page is output.
If the page number specified is higher than the total number of pages found, the results
for the last page are output.
Maximum value: 50.
currency
String
The currency to use for prices of product offers on the search result pages.
Possible values: RUR (Russian ruble), UAH (Ukrainian hrivna), BYR (Belarusian ruble),
KZT (Kazakhstani tenge).
By default, the campaign's national currency is used (the national currency of the country
where the campaign is taking place).
matched
Number
Filter based on whether a product offer is associated with a product profile.
Possible values:
•
1 (search in offers that are associated with product profiles).
•
0 (search in offers that are not associated with any product profiles).
If the parameter is omitted, the filter is not applied.
Attention!
The Yandex.Market assortment is updated approximately once every two hours, so it is pointless to process
a request for the same product offers more than once an hour.
Output data
Developer's guide
48
XML
<pager total="{number}" from="{number}" to="{number}" current-page="{number}" pagescount="{number}" page-size="{number}"/>
<offers>
<offer id="{string}" feed-id="{number}" model-id="{number}" price="{number}"
currency="{string}" bid="{number}" cbid="{number}" shop-category-id="{string}">
<url>{string}</url>
<name>{string}</name>
</offer>
...
</offers>
JSON
{
"pager":
{
"total":{number},
"from":{number},
"to":{number},
"pageSize":{number},
"pagesCount":{number},
"currentPage":{number}
},
"offers":
[
{
"id":"{string}",
"feedId":{number},
"url":"{string}",
"modelId":{number},
"name":"{string}",
"price":{number},
"currency":"{string}",
"bid":{number},
"cbid":{number},
"shopCategoryId":"{string}"
},
...
]
}
Parameter
for XML
format
Parameter
for JSON
format
pager
pager
Type
Value
Summary of search results.
was
called
search-summary
in
XML
format,
and searchSummary in JSON format.
offers
offers
List of found offers.
Parameters nested in search-pager
total
total
Number
Total number of product offers for the campaign that are on
Yandex.Market. If the desired product offers were not found, the value
of the parameter is 0.
was called total-offers in XML format, and totalOffers
in JSON format.
from
from
Number
The index number within search results for the first offer on the page that
is output in the response. If the desired product offers were not found,
the value of the parameter is 0.
Developer's guide
49
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
was called from-offer in XML format, and fromOffer in JSON
format.
to
to
Number
The index number within search results for the last offer on the page that
is output in the response. If the desired product offers were not found,
was called to-offer in XML format, and toOffer in JSON format.
currentpage
currentPage Number
The index number of the page with search results that is output in the
response. If the desired product offers were not found, the value of the
parameter is 0.
pages-count pagesCount
Number
The number of pages with search results. If the desired product offers
were not found, the value of the parameter is 0.
page-size
Number
The number of offers to output on the current search results page. If the
desired product offers were not found, the value of the parameter is 0.
pageSize
was called page-offers in XML format, and pageOffers in JSON
format.
Parameters nested in offers
offer
Information about a found product offer.
Parameters nested in offer
id
id
String
Product offer ID from the price list.
This parameter is output if the ID is set in the price list and it is unique.
If the price list contains multiple product offers with the same IDs,
the id parameter is only specified for the first one; id and feed-id
are not output for the others.
This parameter is available starting in version 2.0 of the Yandex.Market
Partner API.
feed-id
feedId
Number
ID of the price list containing the product offer.
Partner API.
url
url
String
URL of the product offer.
name
name
String
Name of the product offer.
model-id
modelId
Number
ID of the Yandex.Market product profile that the product offer
is associated with.
If the product offer is not associated with any product profile,
the modelid parameter contains the value 0.
Note:
The profile ID is shown in the product profile URL, in the modelid
parameter. For example: http://market.yandex.ru/
model.xml?modelid=6533207&hid=91033.
price
price
Number
Price of the product offer.
Prior to version 2.0 of the Yandex.Market Partner API, this was a string
type parameter.
currency
currency
String
The currency the price of the product offer is shown in.
Developer's guide
50
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
Possible values: RUR (Russian ruble), UAH (Ukrainian hrivna),
BYR (Belarusian ruble), KZT (Kazakhstani tenge).
bid
bid
Number
Value of the basic bid, in Yandex units.
The basic bid is the bid for showing a product offer on Yandex search,
Yandex.Market search, and the Yandex Advertising Network, and also
for the product profile, if the product profile bid is not set separately.
cbid
cbid
Number
The bid value for the product profile, in Yandex units.
The product profile bid is the bid for showing product offers on the
product profile page in Yandex.Market. If the product profile bid is
not specified, the basic bid is used for the product profile.
shopshopCategor String
category-id yId
ID of the product offer category specified in the price list.
This parameter is output only for product offers that have a category
specified in the price list.
Partner API.
Error descriptions
Description
Explanation
Possible solution
Unsupported currency:
'currency'
The currency specified in the
request is not supported.
Check whether the correct currency value
is being passed in the request.
Page number must
be positive: 'pageNum'
The page number specified in the Check whether the correct page number is being
request must be a positive number. passed in the request.
Error 400 Bad Request
Page number is too big: The page number specified in the Check whether the correct page number is being
'pageNum'. Max page
request exceeds the maximum value passed in the request.
number is 'maxPageNum' of maxPageNum.
Page size must
The number of offers to output
Check whether the correct number of offers
be positive: 'pageSize' per page must be a positive number. to output per page is being passed in the request.
Page size is too big:
'pageSize'. Max page
size is 'maxPageSize'
The number of offers to output
per page exceeds the maximum
value maxPageSize.
Feed should
be specified
The request omitted the price list
Check whether the correct data is being passed
ID, which is a mandatory parameter in the request.
if the campaign has more than
one price list registered.
Parameters 'feedId'
and 'shopCategoryId'
may not be used without
each other
The feedId
in the request.
and shopCategoryId cannot
be used separately from each other,
except when the shop has only
one price list.
Check whether the correct number of offers
to output per page is being passed in the request.
Error 404 Not Found
Feed not found:
'feedId'
The price list specified in the Check whether the correct data is being passed
in the request.
Developer's guide
51
Restrictions
The number of requests to a resource that can be processed during a 24-hour period is calculated individually
and depends on the following factors:
•
The number of product offers.
Note:
The number of product offers is based on data from the past seven days (not including today).
For new shops that have not yet published product offers, the limit is 0. After publishing product offers, the limit
for these shops is not recalculated until the next day.
Examples
XML
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/10003/offers.xml?
query=toaster&pageSize=50&page=2
Sample response:
<response>
<pager total="20" from="51" to="58" current-page="2" pages-count="2" page-size="50"/>
<offers>
<offer id="120" feed-id="29392" model-id="282404" price="1215" currency="RUR"
bid="0.12" cbid="0.12" shop-category-id="12345678">
<url>http://nuf-nuf.yandex.ru/product/21003/</url>
<name>Tefal 539625</name>
</offer>
<offer id="121" feed-id="29392" model-id="0" price="1329" currency="RUR" bid="0.15"
cbid="0.22" shop-category-id="12345678">
<name>Clatronic CM 3372</name>
</offer>
<name>DeLonghi CTO 2003.B</name>
</offer>
bid="0.12" cbid="0.12 shop-category-id="87654321"">
<url>http://nuf-nuf.yandex.ru/product/84958/?from=yandex_market_hard2_lower750</
url>
<name>Clatronic TA 3287, White</name>
</offer>
<name>Moulinex SM1511</name>
</offer>
<name>Bosch TAT 6104</name>
</offer>
Developer's guide
52
<name>Brand 33102, Green</name>
</offer>
<name>Bosch TAT 6101</name>
</offer>
</offers>
</response>
JSON
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/10003/offers.json?
query=toaseter&pageSize=50&page=2
Sample response:
{
"pager":
{
"total":20,
"from":51,
"to":58,
"pageSize":50,
"pagesCount":2,
"currentPage":2
},
"offers":
[
{"id":"120", "feedId":29392, "url":"http://nuf-nuf.yandex.ru/product/
21003/","modelId":282404,
"name":"Tefal 539625","price":1215,"currency":"RUR","bid":
0.12,"cbid":0.12, "shopCategoryId":"12345678"},
93728/","modelId":0,
"name":"Clatronic CM 3372","price":1329,"currency":"RUR","bid":
27381/","modelId":4999699,
"name":"DeLonghi CTO 2003.B","price":
2555,"currency":"RUR","bid":0.12,"cbid":0.12, "shopCategoryId":"12345678"},
84958/","modelId":7146186,
"name":"Clatronic TA 3287, White","price":
638,"currency":"RUR","bid":0.12,"cbid":0.12, "shopCategoryId":"87654321"},
29101/","modelId":0,
"name":"Moulinex SM1511","price":1131,"currency":"RUR","bid":
{"id":"125", "feedId":"29392", "url":"http://nuf-nuf.yandex.ru/product/
50955/","modelId":956896,
"name":"Bosch TAT 6104","price":1163,"currency":"RUR","bid":
76477/","modelId":0,
"name":"Brand 33102, Green","price":1064,"currency":"RUR","bid":
37701/","modelId":928393,
"name":"Bosch TAT 6101","price":1206,"currency":"RUR","bid":
0.12,"cbid":0.12, "shopCategoryId":"87654321"}
]
}
List of the campaign's price lists
Description
GET /campaigns/{campaignId}/feeds
Returns a list of price lists that are published on Yandex.Market for the campaign specified in the request.
Information about disabled price lists is not provided.
Developer's guide
53
Note:
Resource URL:
https://api.partner.market.yandex.ru/v2/campaigns/{campaignId}/feeds.[format]
Input data
Parameter
Type
Value
Number
The campaign ID.
Mandatory
campaignId
Output data
XML
<feeds>
<feed id="{number}" url="{string}" login="{string}" password="{string}"
name="{string}" upload-date="{string}" expire-date="{string}"/>
...
</feeds>
JSON
{
"feeds":
[
{
"id":{number},
"url":"{string}",
"login":"{string}",
"password":"{string}",
"name":"{string}",
"uploadDate":"{string}",
"expireDate":"{string}"
},
...
]
}
Parameter
for XML
format
Parameter
for JSON
format
feeds
feeds
Type
Value
List of price lists.
Parameters nested in feeds
feed
Information about a price list.
Parameters nested in feed
id
id
Number
Price list ID.
Developer's guide
54
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
url
url
String
URL of the price list.
This parameter is output when the price list is published on your shop's
site.
login
login
String
Login for authentication when downloading the price list.
site with restricted access.
password
password
String
Password for authentication when downloading the price list.
name
name
String
Name of the file containing the price list.
This parameter is output when the price list is published on the
Yandex.Market server.
upload-date uploadDate
String
Date when the price list was uploaded to Yandex.Market. Date format:
DD-MM-YYYY.
expire-date expireDate
String
Expiration date, after which the price list is considered outdated and must
be updated. Date format: DD-MM-YYYY.
Note:
If at least one of the shop's price lists expires, the shop is closed.
Error descriptions
Description
Explanation
Possible solution
accessible.
Error 403 Forbidden
Access denied
Examples
XML
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/10001/feeds.xml
Sample response:
<response>
<feeds>
<feed id="12345" url="http://nuf-nuf.yandex.ru/price.xml" login="badbadwolf"
password="afraid"/>
<feed id="12346" name="toys.xls" upload-date="07-11-2012" expire-date="07-12-2012"/>
</feeds>
</response>
Developer's guide
55
JSON
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/10001/feeds.json
Sample response:
{"feeds":
[
{
"id":12345,
"url":"http://nuf-nuf.yandex.ru/price.xml",
"login":"badbadwolf",
"password":"afraid"
},
{
"id":12346,
"name":"toys.xls",
"uploadDate":"07-11-2012",
"expireDate":"07-12-2012"
}
]
}
Price list information
Description
GET /campaigns/{campaignId}/feeds/{feedId}
Returns information about the price list specified in the request that is published on Yandex.Market for this
campaign. Information about disabled price lists is not provided.
Note:
Resource URL:
https://api.partner.market.yandex.ru/v2/campaigns/{campaignId}/feeds/{feedId}.
[format]
Input data
Parameter
Type
Value
campaignId
Number
The campaign ID.
feedId
Number
Price list ID.
Mandatory
Output data
Developer's guide
56
XML
<feed id="{number}" url="{string}" login="{string}" password="{string}" name="{string}"
upload-date="{string}" expire-date="{string}"/>
JSON
{
"feed":
{
"id":{number},
"url":"{string}",
"login":"{string}",
"password":"{string}",
"name":"{string}",
"uploadDate":"{string}",
"expireDate":"{string}"
}
}
Parameter
for XML
format
Parameter
for JSON
format
feed
feed
Type
Value
Information about a price list.
Parameters nested in feed
id
id
Number
Price list ID.
url
url
String
URL of the price list.
site.
login
login
String
Login for authentication when downloading the price list.
password
password
String
Password for authentication when downloading the price list.
name
name
String
Name of the file containing the price list.
upload-date uploadDate
String
Date when the price list was uploaded to Yandex.Market. Date format:
DD-MM-YYYY.
expire-date expireDate
String
Expiration date, after which the price list is considered outdated and must
be updated. Date format: DD-MM-YYYY.
Note:
If at least one of the shop's price lists expires, the shop is closed.
Developer's guide
57
Error descriptions
Description
Explanation
Possible solution
accessible.
Error 403 Forbidden
Access denied
Error 404 Not Found
Feed not found:
'feedId'
The price list specified in the Check whether the price list ID is correct.
Examples
XML
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/10001/feeds/12345.xml
Sample response:
<response>
<feed id="12345" url="http://nuf-nuf.yandex.ru/price.xml" login="badbadwolf"
password="afraid"/>
</response>
JSON
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/10001/feeds/12345.json
Sample response:
{
"feed":
{
"id":12345,
"url":"http://nuf-nuf.yandex.ru/price.xml",
"login":"badbadwolf",
"password":"afraid"
}
}
Price list category
Description
GET /campaigns/{campaignId}/feeds/{feedId}/categories
Returns a list of categories of product offers from the price list specified in the request that is published
on Yandex.Market for this campaign. Information about categories is not provided for disabled price lists.
The response to the request specifies each category with its name, ID, and the ID of the parent category. The list
is sorted by increasing order of category ID. If there are many categories, results are paginated.
Developer's guide
58
Note:
Resource URL:
https://api.partner.market.yandex.ru/v2/campaigns/{campaignId}/feeds/{feedId}/
categories.[format]
Input data
Parameter
Type
Value
campaignId
Number
The campaign ID.
feedId
Number
Price list ID.
Number
The number of categories to output on the page with search results in the response.
Mandatory
Optional
pageSize
Default value: 500 categories.
Maximum value: 1000 categories.
page
Number
If the page number specified is higher than the total number of pages found, an error message
is returned.
Output data
XML
<categories>
<category feed-id="{number}" id="{string}" parent-id="{string}" name="{string}"/>
...
</categories>
JSON
{
"pager":
{
"total":{number},
"from":{number},
"to":{number},
},
"categories":
Developer's guide
59
[
{
"id":"{string}",
"feedId":{number},
"parentId":"{string}",
"name":"{string}"
},
...
]
}
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
pager
pager
categories
categories
List of categories.
total
total
Number
If the desired categories were not found, the value of the parameter is 0.
from
from
Number
The index number within search results for the first category on the page
that is output in the response. If the desired categories were not found,
to
to
Number
The index number within search results for the last category on the page
currentpage
currentPage Number
response. If the desired categories were not found, the value of the
parameter is 0.
Number
The number of pages with search results. If the desired categories were
not found, the value of the parameter is 0.
page-size
Number
The number of categories to output on the current search results page.
pageSize
Parameters nested in categories
category
Information about the category.
Parameters nested in category
feed-id
feedId
Number
Price list ID.
id
id
String
The category ID.
parent-id
parentId
String
ID of the parent category.
This parameter is not output for a root-level category.
name
name
String
Name of the category.
Error descriptions
Description
Explanation
Possible solution
Developer's guide
60
Description
Explanation
Possible solution
Page number must
'pageNum'. Max page
Page size must
The number of categories to output Check whether the correct number of categories
value maxPageSize.
Error 403 Forbidden
Access denied
accessible.
Error 404 Not Found
Feed not found:
'feedId'
The price list specified in the Check whether the price list ID is correct.
Restrictions
feeds/categories, there is a group resource limit. The limit is applied to the total number of categories that
information is requested for using these methods.
The volume of requests to a resource that can be processed during a 24-hour period is calculated individually
•
The number of categories.
Note:
The number of categories is calculated for the previous day.
Examples
XML
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/10003/feeds/12347/categories.xml
Sample response:
<response>
<categories>
<category feed-id="12347" id="1" name="Televisions"/>
<category feed-id="12347" id="2" parent-id="1" name="LCD"/>
<category feed-id="12347" id="3" parent-id="1" name="Plasma"/>
</categories>
</response>
JSON
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/10003/feeds/12347/categories.json
Sample response:
Developer's guide
61
{
"pager":
{
"total":3,
"from":1,
"to":3,
"pageSize":3,
"pagesCount":1,
"currentPage":1
},
"categories":
[
{
"id":"1",
"feedId":12347,
"name":"Televisions"
},
{
"id":"2",
"feedId":12347,
"parentId":"1",
"name":"LCD"
},
{
"id":"3",
"feedId":12347,
"parentId":"1",
"name":"Plasma"
}
]
}
Campaign categories
Description
GET /campaigns/{campaignId}/feeds/categories
Returns a list of categories of product offers for the campaign specified in the request, for all of this campaign's
price lists that are published on Yandex.Market. Information about categories is not provided for disabled price
lists.
The response to the request specifies each category with its name, ID, and the ID of the parent category. The list
is sorted first by increasing price list ID, then by increasing category ID. If there are many categories, results
are paginated.
Note:
Resource URL:
https://api.partner.market.yandex.ru/v2/campaigns/{campaignId}/feeds/categories.
[format]
Input data
Parameter
Type
Value
Mandatory
Developer's guide
62
Parameter
Type
Value
campaignId
Number
The campaign ID.
Number
The number of categories to output on the page with search results in the response.
Optional
pageSize
Default value: 500 categories.
Maximum value: 1000 categories.
page
Number
If the page number specified is higher than the total number of pages found, an error message
is returned.
Output data
XML
<categories>
<category feed-id="{number}" id="{string}" parent-id="{string}" name="{string}"/>
...
</categories>
JSON
{
"pager":
{
"total":{number},
"from":{number},
"to":{number},
},
"categories":
[
{
"id":"{string}",
"feedId":{number},
"parentId":"{string}",
"name":"{string}"
},
...
]
}
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
pager
pager
categories
categories
List of categories.
total
total
Number
Developer's guide
63
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
from
from
Number
The index number within search results for the first category on the page
to
to
Number
The index number within search results for the last category on the page
currentpage
currentPage Number
response. If the desired categories were not found, the value of the
parameter is 0.
Number
The number of pages with search results. If the desired categories were
not found, the value of the parameter is 0.
page-size
Number
The number of categories to output on the current search results page.
pageSize
Parameters nested in categories
category
Information about the category.
Parameters nested in category
feed-id
feedId
Number
Price list ID.
id
id
String
The category ID.
parent-id
parentId
String
ID of the parent category.
This parameter is not output for a root-level category.
name
name
String
Name of the category.
Error descriptions
Description
Explanation
Possible solution
Page number must
'pageNum'. Max page
Page size must
value maxPageSize.
Error 403 Forbidden
Access denied
accessible.
Restrictions
feeds/categories, there is a group resource limit. The limit is applied to the total number of categories that
information is requested for using these methods.
Developer's guide
64
•
The number of categories.
Note:
The number of categories is calculated for the previous day.
Examples
XML
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/10003/feeds/categories.xml
Sample response:
<response>
<categories>
<category feed-id="12347" id="3" parent-id="1" name="Plasma"/>
<category feed-id="12345" id="4" parent-id="1" name="CRT"/>
</categories>
</response>
JSON
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/10003/feeds/categories.json
Sample response:
{
"pager":
{
"total":6,
"from":1,
"to":6,
"pageSize":6,
"pagesCount":1,
"currentPage":1
},
"categories":
[
{
"id":"1",
"feedId":12347,
},
{
"id":"2",
"feedId":12347,
"parentId":"1",
"name":"LCD"
},
{
"id":"3",
"feedId":12347,
"parentId":"1",
"name":"Plasma"
},
{
"id":"1",
Developer's guide
65
"feedId":12345,
},
{
"id":"2",
"feedId":12345,
"parentId":"1",
"name":"LCD"
},
{
"id":"4",
"feedId":12345,
"parentId":"1",
"name":"CRT"
}
]
}
Developer's guide
66
Product modifications
Use these methods to get information about modifications of Yandex.Market products and product offers
for modifications.
Method
Short description
Restrictions
GET models/{modelId}
Returns information about the specified Individual number of requests per day.
product modification.
GET models
Returns information about
modifications that meet the search
conditions.
POST models
Returns information about the specified Individual number of requests per day;
product modifications.
100 modifications per request.
GET models/{modelId}/offers
offers for the specified modification.
Individual number of requests per day.
POST models/offers
offers for the specified modifications.
For the methods GET models/{modelId}, GET models, and POST models, a group resource limit is applied.
The methods GET models/{modelId}/offers and POST models/offers also have a group resource limit.
Information about a product modification
Description
GET /models/{modelId}
Returns information about the product modification specified in the request.
Note:
Resource URL:
https://api.partner.market.yandex.ru/v2/models/{modelId}.[format]
Input data
Parameter
Type
Value
modelId
Number
ID of the product modification.
regionId
Number
ID of the region that information about a modification is being output for.
Mandatory
Use the GET regions method to get the region ID.
Optional
currency
String
The currency used for prices of product offers for the modification.
Developer's guide
67
Parameter
Type
Value
Possible values:
•
RUR (Russian ruble)
•
UAH (Ukrainian hrivna)
•
BYR (Belarusian ruble)
•
KZT (Kazakhstani tenge)
By default, the national currency of the region specified in the regionId parameter is used.
Output data
XML
<models region-id="{number}" currency="{string}">
<model id="{number}" name="{string}">
<prices min="{number}" max="{number}" avg="{number}">
</model>
</models>
JSON
{
"models":
[
{
"id":{number},
"name":"{string}",
"prices":
{
"min":{number},
"max":{number},
"avg":{number}
}
}
],
"regionId":{number},
"currency":"{string}"
}
Parameter
for XML
format
Parameter
for JSON
format
models
models
regionId
Type
Value
The product modification specified in the request.
Number
ID of the region that information about the product modification is being
output for.
Use the GET regions/{regionId} method to get region information by ID.
currency
String
Possible values:
•
RUR (Russian ruble)
•
•
•
Parameters nested in models
Developer's guide
68
Parameter
for XML
format
Parameter
for JSON
format
region-id
Type
Value
Number
ID of the region that information about the product modification is being
output for.
currency
String
Possible values:
model
•
RUR (Russian ruble)
•
•
•
Description of a modification.
Parameters nested in model
id
id
Number
name
name
String
Name of the product modification.
prices
prices
Prices for the product modification.
Parameters nested in prices
min
min
Number
Minimum price of a product offer for the modification in this region.
max
max
Number
Maximum price of a product offer for the modification in this region.
avg
avg
Number
Average price of a product offer for the modification in this region.
Error descriptions
Description
Explanation
Possible solution
'currency'
Check whether the correct currency code
Invalid regionId:
'regionId'
The region with the specified
regionId was not found.
Check whether the region ID is correct.
Error 404 Not Found
Model not found:
'modelId'
The modification with the specified Check whether the modification ID is correct.
modelId was not found.
Restrictions
The limit is applied to the total number of modifications that information is requested for using these methods.
•
The number of offers on product profiles.
•
How many active campaigns the client has.
Developer's guide
69
Note:
For clients with multiple campaigns, the limit is calculated based on the number of maximum offers in the client's
campaigns. For agencies, the limit is combined for all the agency's subclients.
Examples
XML
Sample request:
GET https://api.partner.market.yandex.ru/v2/models/7012977.xml?regionId=213
Sample response:
<response>
<models region-id="213" currency="RUR">
<model id="7012977" name="Galaxy S II I9100">
<prices min="14130" max="50000" avg="22690"/>
</model>
</models>
</response>
JSON
Sample request:
GET https://api.partner.market.yandex.ru/v2/models/7012977.json?regionId=213
Sample response:
{"models":[
{"id":7012977,"name":"Galaxy S II I9100",
"prices":{"min":14130,"max":50000,"avg":22690}
}],
"regionId":213,
"currency":"RUR"
}
Search for product modifications
Description
GET /models
Returns information about modifications that meet the search conditions specified in the request.
Note:
Resource URL:
Developer's guide
70
https://api.partner.market.yandex.ru/v2/models.[format]
Input data
Parameter
Type
Value
query
String
Search query.
regionId
Number
ID of the region that information about product modifications is being requested for.
Mandatory
Optional
page
Number
By default, the first page is output.
If the page number specified is higher than the total number of results pages, an error message
is returned.
Maximum value: 50 pages.
pageSize
Number
The number of results on a page.
Default value: 10 modifications.
Maximum value: 100 modifications.
currency
String
The currency the price of product offers is shown in.
Possible values:
•
RUR (Russian ruble)
•
•
•
Output data
XML
</model>
...
</models>
JSON
{
"models":
[
{
"id":{number},
"name":"{string}",
"prices":
{
"min":{number},
"max":{number},
Developer's guide
71
"avg":{number}
}
},
...
],
"pager":
{
"total":{number},
"from":{number},
"to":{number},
"currentPage":{number},
"pageSize":{number}
},
}
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
models
models
List of product modifications that meet the search conditions.
pager
pager
Information about search results.
was
called
search-summary
in
XML
format,
and searchSummary in JSON format.
regionId
Number
ID of the region that information about product modifications is being
output for.
currency
String
The currency used for prices of product offers for modifications.
Possible values:
•
RUR (Russian ruble)
•
•
•
region-id
Number
output for.
currency
String
Possible values:
model
•
RUR (Russian ruble)
•
•
•
id
id
Number
name
name
String
Developer's guide
72
Parameter
for XML
format
Parameter
for JSON
format
prices
prices
Type
Value
min
min
Number
max
max
Number
avg
avg
Number
Number
Total number of modifications found.
Parameters nested in pager
total
total
If no modifications were found that meet the search conditions, the value
of the parameter is "0".
from
from
Number
Index number of the modification at the top of the search results page
to output.
to
to
Number
Index number of the modification at the end of the search results page
to output.
currentpage
currentPage Number
Page number in search results to output.
Number
The number of pages with results.
page-size
pageSize
Number
The number of modifications to output on a page.
was called on-page in XML format, and onPage in JSON format.
Error descriptions
Description
Explanation
Possible solution
'currency'
Invalid regionId:
'regionId'
Too many modifications
requested: 'count'.
Maximum is 'maxCount'
Exceeded the functional limit on the Reduce the number of requested modifications
number of requested modifications to the allowed limit.
for the resource per request.
Page number is too big: The results page number specified Increase the number of results output per page,
'page'. Max page number in the request exceeds the maximum or make the request more specific to reduce
is 'maxPage'
number of pages.
the number of results.
Developer's guide
73
Restrictions
•
•
Note:
Examples
XML
Sample request:
GET https://api.partner.market.yandex.ru/v2/models.xml?query=iPhone+4s&regionId=2
Sample response:
<response>
<model id="7717706" name="Apple iPhone 4S 16Gb">
<prices min="21500" max="68400" avg="24990">
</model>
</model>
</model>
</models>
<pager total="3263" from="1" to="3" current-page="1" pages-count="1088" page-size="3"/
>
</response>
JSON
Sample request:
GET https://api.partner.market.yandex.ru/v2/models.json?query=iPhone+4s&regionId=2
Sample response:
Developer's guide
74
{"models":
[
{"id":7717706,
"name":"Apple iPhone 4S 16Gb",
},
{"id":7717686,
},
{"id":7717687,
}
],
"pager":{"total":3263,"from":1,"to":3,"currentPage":1,"pagesCount":1088,"pageSize":3},
"regionId":2,
"currency":"RUR"
}
Information about multiple modifications
Description
POST /models
Returns information about the product modifications whose IDs are specified in the request.
Note:
Resource URL:
https://api.partner.market.yandex.ru/v2/models.[format]
Input data
Parameter
Type
Value
Number
ID of the region that information about product modifications is being requested for.
Mandatory
regionId
Optional
currency
String
The currency used for product offer prices for modifications.
Possible values:
•
RUR (Russian ruble)
•
•
•
Structure of the body of the POST request:
Developer's guide
75
XML
<models>
<id>{number}</id>
...
</models>
JSON
{
"models":
[
{number},
...
]
}
The following parameters are passed in the body of the POST request:
Parameter
for XML
format
Parameter
for JSON
format
models
models
Type
Value
List of modifications.
id
Number
ID of the modification.
Output data
Note:
If one or more of the modifications whose IDs are indicated in the request body are not found, the response
is returned with results for the other modifications. If none of the requested modifications is found, the HTTP
code 404 is returned with a brief error description.
XML
</model>
...
</models>
Developer's guide
76
JSON
{
"models":
[
{
"id":{number},
"name":"{string}",
"prices":
{
"min":{number},
"max":{number},
"avg":{number}
}
},
...
],
}
Parameter
for XML
format
Parameter
for JSON
format
models
models
regionId
Type
Value
List of found product modifications whose IDs are indicated in the
request.
Number
output for.
currency
String
Possible values:
•
RUR (Russian ruble)
•
•
•
region-id
Number
output for.
currency
String
Possible values:
model
•
RUR (Russian ruble)
•
•
•
id
id
Number
name
name
String
Developer's guide
77
Parameter
for XML
format
Parameter
for JSON
format
prices
prices
Type
Value
min
min
Number
max
max
Number
avg
avg
Number
Error descriptions
Description
Explanation
Possible solution
'currency'
Invalid regionId:
'regionId'
Models ids not
specified
The request body does not specify
the modification IDs.
Check the validity of the request body.
requested: 'count'.
Error 404 Not Found
Models not found
None of the modifications with
Check whether the correct modification IDs are
the IDs specified in the request body indicated in the request body.
could be found.
Restrictions
•
•
Note:
Developer's guide
78
Examples
XML
Sample request:
POST https://api.partner.market.yandex.ru/v2/models.xml?regionId=2
Content-Type: application/xml
POST request body:
<models>
<id>7717706</id>
<id>7717686</id>
<id>7717687</id>
</models>
Sample response:
<response>
</model>
</model>
</model>
</models>
</response>
JSON
Sample request:
POST https://api.partner.market.yandex.ru/v2/models.json?regionId=2
Content-Type: application/json
POST request body:
{"models":
[7717706,7717686,7717687]
}
Sample response:
{"models":
[
{"id":7717706,
},
{"id":7717686,
},
{"id":7717687,
}
],
"regionId":2,
"currency":"RUR"
}
Developer's guide
79
List of offers for a modification
Description
GET /models/{modelId}/offers
Returns information about the top ten product offers shown on the product profile specified in the request.
Offers are output for a particular region and are arranged in the same order as they are shown in Yandex.Market
on the product profile.
This method is not supported for groups of modifications. If the ID of a group of modifications is indicated
in the request, it is ignored.
Note:
Resource URL:
https://api.partner.market.yandex.ru/v2/models/{modelId}/offers.[format]
Input data
Parameter
Type
Value
modelId
Number
regionId
Number
ID of the region that information about product offers for a modification is being requested
for.
Mandatory
Optional
currency
String
Possible values:
•
RUR (Russian ruble)
•
•
•
Output data
Developer's guide
80
XML
<model id="{number}">
<offers online="{number}" offline="{number}">
<offer pos="{number}" name="{string}" price="{number}" region-id="{number}"
shipping-cost="{number}" in-stock="{number}" shop-name="{string}" shop-rating="{number}"/
>
...
</offers>
</model>
</models>
JSON
{
"models":
[
{
"id":{number},
"offers":
[
{
"pos":{number},
"name":"{string}",
"price":{number},
"shippingCost":{number},
"inStock":{number},
"shopRating":{number}
},
...
],
"onlineOffers":{number},
"offlineOffers":{number}
}
],
}
Parameter
for XML
format
Parameter
for JSON
format
models
models
regionId
Type
Value
The product modification specified in the request.
Number
ID of the region that information about the modification's product offers
is output for (for offers that are delivered to this region).
currency
String
Possible values:
•
RUR (Russian ruble)
•
•
•
region-id
Number
ID of the region that information about the modification's product offers
is output for (for offers that are delivered to this region).
Developer's guide
81
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
currency
String
Possible values:
model
•
RUR (Russian ruble)
•
•
•
id
id
offers
offers
Number
List of the top ten product offers placed on the product profile.
online
onlineOffer Number
s
The number of product offers in internet shops in the region.
offline
offlineOffe Number
rs
The number of product offers in offline shops in the region.
offer
Description of the product offer.
pos
pos
Number
The product offer's position in Yandex.Market output on the product
profile.
name
name
String
price
price
Number
region-id
regionId
Number
ID of the product offer's region (the region the product is delivered from).
Offers that are delivered from the region indicated in the regionId
parameter in the request are shown first. Offers delivered from other
regions are shown after these.
shippingcost
shippingCos Number
t
The cost of delivering the product to the region.
in-stock
inStock
Whether the shop has the product in stock.
Number
If the parameter value is 0, delivery is free of charge. If the parameter
value is 1, the shop does not deliver this product (pick-up only). If the
delivery cost is unknown, the parameter is not output.
Possible values:
shop-name
shopName
shop-rating shopRating
•
"1" — Product is in stock.
•
"0" — Product is not in stock and must be ordered.
String
Name of the shop (as it appears on Yandex.Market).
Number
Shop rating.
Possible values: from "1" to "5", or "-1".
Shops that recently appeared on Yandex.Market do not have a rating
immediately. The parameter value "-1" is returned for these shops until
they get a rating.
Developer's guide
82
Error descriptions
Description
Explanation
Possible solution
'currency'
Invalid regionId:
'regionId'
Group cards offers
are not supported
The modification in the request
Set a modification ID that is not from a group.
is from a group. Output of product
offers is not supported for these
types of modifications.
Error 404 Not Found
Model not found:
'modelId'
The modification with the specified Check whether the modification ID is correct.
modelId was not found.
Restrictions
For the methods GET models/{modelId}/offers and POST models/offers, a group resource limit is applied.
•
•
Note:
Examples
XML
Sample request:
GET https://api.partner.market.yandex.ru/v2/models/7012977/offers.xml?regionId=213
Sample response:
<response>
<model id="7012977">
<offers online="689" offline="496">
<offer pos="1" name="Samsung Galaxy S II GT-I9100" price="15740" region-id="213"
shipping-cost="250" in-stock="1" shop-name="Store.Com" shop-rating="4"/>
<offer pos="2" name="Cell phones Samsung GT-I9100 Galaxy S II White" price="21637"
region-id="213" shipping-cost="350" in-stock="1" shop-name="Piggy.Ru" shop-rating="4"/>
<offer pos="3" name="Samsung GT-I9100 Galaxy S II" price="16090" region-id="213"
Developer's guide
83
shipping-cost="200" in-stock="1" shop-name="Piggier.Ru" shop-rating="5"/>
<offer pos="4" name="Samsung I9100 Galaxy S II" price="21480" region-id="213"
shipping-cost="200" in-stock="1" shop-name="Piggiest.Ru" shop-rating="4"/>
shipping-cost="100" in-stock="1" shop-name="Wolf.Ru" shop-rating="5"/>
<offer pos="6" name="Smartphone Samsung GT-I9100 Galaxy S II" price="17146" regionid="213" shipping-cost="584" in-stock="1" shop-name="SnowWhite.Ru" shop-rating="3"/>
<offer pos="7" name="Samsung Galaxy S II I9100" price="16700" region-id="213"
shipping-cost="300" in-stock="1" shop-name="Cinderella.Ru" shop-rating="4"/>
<offer pos="8" name="Samsung GT-i9100 Galaxy S II" price="21500" region-id="213"
shipping-cost="200" in-stock="1" shop-name="Rapunzel.Ru" shop-rating="4"/>
<offer pos="9" name="Mobile phone Samsung GT-i9100 Galaxy S II" price="21570"
region-id="213" shipping-cost="0" in-stock="1" shop-name="SleepingBeauty.Ru" shoprating="4"/>
<offer pos="10" name="Phones GSM Samsung I9100 Galaxy S II 16Gb (pink)"
price="22690" region-id="213" shipping-cost="0" in-stock="1" shop-name="WickedWitch.Ru"
shop-rating="3"/>
</offers>
</model>
</models>
</response>
JSON
Sample request:
GET https://api.partner.market.yandex.ru/v2/models/7012977/offers.json?regionId=213
Sample response:
{"models":[
{"id":7012977,"offers":
[
{"pos":1,"name":"Samsung Galaxy S II GT-I9100","price":15740,"regionId":
213,"shippingCost":250,"inStock":1,"shopName":"Store.Com","shopRating":4},
{"pos":2,"name":"Cell phones Samsung GT-I9100 Galaxy S II White","price":
21637,"regionId":213,"shippingCost":350,"inStock":1,"shopName":"Piggy.Ru","shopRating":
4},
{"pos":3,"name":"Samsung GT-I9100 Galaxy S II","price":16090,"regionId":
213,"shippingCost":200,"inStock":1,"shopName":"Piggier.Ru","shopRating":5},
{"pos":4,"name":"Samsung I9100 Galaxy S II","price":21480,"regionId":
213,"shippingCost":200,"inStock":1,"shopName":"Piggiest.Ru","shopRating":4},
213,"shippingCost":100,"inStock":1,"shopName":"Wolf.Ru","shopRating":5},
{"pos":6,"name":"Smartphone Samsung GT-I9100 Galaxy S II","price":17146,"regionId":
213,"shippingCost":584,"inStock":1,"shopName":"SnowWhite.Ru","shopRating":3},
{"pos":7,"name":"Samsung Galaxy S II I9100","price":16700,"regionId":
213,"shippingCost":300,"inStock":1,"shopName":"Cinderella.Ru","shopRating":4},
{"pos":8,"name":"Samsung GT-i9100 Galaxy S II","price":21500,"regionId":
213,"shippingCost":200,"inStock":1,"shopName":"Rapunzel.Ru","shopRating":4},
{"pos":9,"name":"Mobile phone Samsung GT-i9100 Galaxy S II","price":21570,"regionId":
213,"shippingCost":0,"inStock":1,"shopName":"SleepingBeauty.Ru","shopRating":4},
{"pos":10,"name":"Phones GSM Samsung I9100 Galaxy S II 16Gb (pink)","price":
22690,"regionId":213,"shippingCost":0,"inStock":
1,"shopName":"WickedWitch.Ru","shopRating":3}
],
"onlineOffers":689,
"offlineOffers":496
}
],
"regionId":213,
"currency":"RUR"
}
List of offers for multiple modifications
Description
POST /models/offers
Developer's guide
84
Returns information about the top ten product offers shown on the product profiles whose IDs are specified
in the request.
Offers are output for a particular region and are arranged in the same order as they are shown in Yandex.Market
on the product profile.
Output of product offers is not supported for groups of modifications. IDs of grouped modifications in the request
are ignored.
Note:
Resource URL:
https://api.partner.market.yandex.ru/v2/models/offers.[format]
Input data
Parameter
Type
Value
Number
ID of the region that information about product offers for modifications is being requested
for.
Mandatory
regionId
Optional
currency
String
The currency used for product offer prices for modifications.
Possible values:
•
RUR (Russian ruble)
•
•
•
XML
<models>
<id>{number}</id>
...
</models>
JSON
{
"models":
[
{number},
...
]
}
Developer's guide
85
Parameter
for XML
format
Parameter
for JSON
format
models
models
Type
Value
List of modifications.
id
Number
ID of the modification.
Output data
Note:
If one or more of the modifications whose IDs are indicated in the request body are not found, the response
is returned with results for the other modifications. If none of the requested modifications is found, the HTTP
code 404 is returned with a brief error description.
XML
<model id="{number}">
<offers online="{number}" offline="{number}">
<offer pos="{number}" name="{string}" price="{number}" region-id="{number}"
shipping-cost="{number}" in-stock="{number}" shop-name="{string}" shop-rating="{number}"/
>
...
</offers>
</model>
...
</models>
JSON
{
"models":
[
{
"id":{number},
"offers":
[
{
"pos":{number},
"name":"{string}",
"price":{number},
"shippingCost":{number},
"inStock":{number},
"shopRating":{number}
},
...
],
"onlineOffers":{number},
"offlineOffers":{number}
},
...
],
}
Developer's guide
86
Parameter
for XML
format
Parameter
for JSON
format
models
models
regionId
Type
Value
List of product modifications whose IDs are indicated in the request.
Number
ID of the region that information about product offers for modifications
is output for.
currency
String
Possible values:
•
RUR (Russian ruble)
•
•
•
region-id
Number
ID of the region that information about product offers for modifications
is output for.
currency
String
Possible values:
model
•
RUR (Russian ruble)
•
•
•
id
id
offers
offers
Number
List of the top ten product offers placed on the product profile.
online
onlineOffer Number
s
The number of product offers in internet shops in the region.
offline
offlineOffe Number
rs
The number of product offers in offline shops in the region.
offer
Description of the product offer.
pos
pos
Number
The product offer's position in Yandex.Market output on the product
profile.
name
name
String
price
price
Number
region-id
regionId
Number
ID of the product offer's region (the region the product is delivered from).
Offers that are delivered from the region indicated in the regionId
parameter in the request are shown first. Offers delivered from other
regions are shown after these.
Developer's guide
87
Parameter
for XML
format
Parameter
for JSON
format
Type
shippingcost
shippingCos Number
t
The cost of delivering the product to the region.
in-stock
inStock
Whether the shop has the product in stock.
Number
Value
If the parameter value is 0, delivery is free of charge. If the parameter
value is 1, the shop does not deliver this product (pick-up only). If the
delivery cost is unknown, the parameter is not output.
Possible values:
shop-name
shopName
shop-rating shopRating
•
"1" — Product is in stock.
•
"0" — Product is not in stock and must be ordered.
String
Name of the shop (as it appears on Yandex.Market).
Number
Shop rating.
Possible values: from "1" to "5", or "-1".
Shops that recently appeared on Yandex.Market do not have a rating
immediately. The parameter value "-1" is returned for these shops until
they get a rating.
Error descriptions
Description
Explanation
Possible solution
'currency'
Invalid regionId:
'regionId'
Group cards offers
are not supported
All the modifications indicated
in the request are from groups.
Output of product offers is not
supported for these types
of modifications.
Specify IDs of modifications that are not
grouped.
requested: 'count'.
Error 404 Not Found
Models not found
None of the modifications with
Check whether the correct modification IDs are
the IDs specified in the request body indicated in the request body.
could be found.
Restrictions
For the methods GET models/{modelId}/offers and POST models/offers, a group resource limit is applied.
•
•
Developer's guide
88
Note:
Examples
XML
Sample request:
POST https://api.partner.market.yandex.ru/v2/models/offers.xml?regionId=213
POST request body:
<models>
<id>7012977</id>
<id>7717686</id>
</models>
Sample response:
<response>
<model id="7012977">
<offer pos="1" name="Samsung Galaxy S II GT-I9100" price="15740" region-id="213"
shipping-cost="250" in-stock="1" shop-name="Store.Com" shop-rating="4"/>
<offer pos="2" name="Cell phones Samsung GT-I9100 Galaxy S II White" price="21637"
region-id="213" shipping-cost="350" in-stock="1" shop-name="Piggy.Ru" shop-rating="4"/>
<offer pos="3" name="Samsung GT-I9100 Galaxy S II" price="16090" region-id="213"
<offer pos="6" name="Smartphone Samsung GT-I9100 Galaxy S II" price="17146" regionid="213" shipping-cost="584" in-stock="1" shop-name="SnowWhite.Ru" shop-rating="3"/>
<offer pos="7" name="Samsung Galaxy S II I9100" price="16700" region-id="213"
shipping-cost="300" in-stock="1" shop-name="Cinderella.Ru" shop-rating="4"/>
<offer pos="8" name="Samsung GT-i9100 Galaxy S II" price="21500" region-id="213"
shipping-cost="200" in-stock="1" shop-name="Rapunzel.Ru" shop-rating="4"/>
<offer pos="9" name="Mobile phone Samsung GT-i9100 Galaxy S II" price="21570"
region-id="213" shipping-cost="0" in-stock="1" shop-name="SleepingBeauty.Ru" shoprating="4"/>
<offer pos="10" name="Phones GSM Samsung I9100 Galaxy S II 16Gb (pink)"
price="22690" region-id="213" shipping-cost="0" in-stock="1" shop-name="WickedWitch.Ru"
shop-rating="3"/>
</offers>
</model>
<model id="7717686">
<offer pos="1" name="Smartphone Apple iPhone 4S 32 Gb black" price="38990" regionid="213" shipping-cost="290" in-stock="1" shop-name="Store.Com" shop-rating="4"/>
<offer pos="2" name="Cell phones Apple iPhone 4S 32Gb Black" price="29490" regionid="213" shipping-cost="0" in-stock="1" shop-name="Piggy.Ru" shop-rating="5"/>
<offer pos="3" name="Apple iPhone 4S 32Gb Black" price="29590" region-id="213"
<offer pos="4" name="Apple iPhone 4S 32Gb (white)" price="33990" region-id="213"
<offer pos="5" name="Apple iPhone 4S 32Gb White" price="27700" region-id="213"
<offer pos="6" name="Apple iPhone 4S 32 Gb Black" price="28900" region-id="213"
shipping-cost="300" in-stock="1" shop-name="SnowWhite.Ru" shop-rating="5"/>
Developer's guide
89
<offer pos="7" name="Apple iPhone 4S 32Gb" price="27200" region-id="213" shippingcost="300" in-stock="1" shop-name="Cinderella.Ru" shop-rating="5"/>
<offer pos="8" name="Smartphone Apple iPhone 4S 32Gb White" price="40990" regionid="213" shipping-cost="0" in-stock="1" shop-name="Rapunzel.Ru" shop-rating="5"/>
<offer pos="9" name="iPhone 4S 32GB, Black" price="36550" region-id="213" shippingcost="0" in-stock="1" shop-name="SleepingBeauty.Ru" shop-rating="3"/>
<offer pos="10" name="Apple iPhone 4S 32Gb" price="27200" region-id="213" shippingcost="300" in-stock="1" shop-name="WickedWitch.Ru" shop-rating="5"/>
</offers>
</model>
</models>
</response>
JSON
Sample request:
POST https://api.partner.market.yandex.ru/v2/models/offers.json?regionId=213
POST request body:
{"models":
[7012977,7717686]
}
Sample response:
{"models":
[
{
"id":7012977,
"offers":
[
{"pos":1,"name":"Samsung Galaxy S II GT-I9100","price":15740,"regionId":
{"pos":2,"name":"Cell phones Samsung GT-I9100 Galaxy S II White","price":
21637,"regionId":213,"shippingCost":350,"inStock":1,"shopName":"Piggy.Ru","shopRating":
4},
{"pos":3,"name":"Samsung GT-I9100 Galaxy S II","price":16090,"regionId":
{"pos":6,"name":"Smartphone Samsung GT-I9100 Galaxy S II","price":
1,"shopName":"SnowWhite.Ru","shopRating":3},
{"pos":7,"name":"Samsung Galaxy S II I9100","price":16700,"regionId":
{"pos":8,"name":"Samsung GT-i9100 Galaxy S II","price":21500,"regionId":
{"pos":9,"name":"Mobile phone Samsung GT-i9100 Galaxy S II","price":
1,"shopName":"SleepingBeauty.Ru","shopRating":4},
{"pos":10,"name":"Phones GSM Samsung I9100 Galaxy S II 16Gb (pink)","price":
1,"shopName":"WickedWitch.Ru","shopRating":3}
],
"onlineOffers":689,
"offlineOffers":496
},
{
"id":7012977,
"offers":
[
{"pos":1,"name":"Smartphone Apple iPhone 4S 32 Gb black","price":38990,"regionId":
{"pos":2,"name":"Cell phones Apple iPhone 4S 32Gb Black","price":29490,"regionId":
213,"shippingCost":0,"inStock":1,"shopName":"Piggy.Ru","shopRating":5},
{"pos":3,"name":"Apple iPhone 4S 32Gb Black","price":29590,"regionId":
{"pos":4,"name":"Apple iPhone 4S 32Gb white","price":33990,"regionId":
{"pos":5,"name":"Apple iPhone 4S 32Gb White","price":27700,"regionId":
Developer's guide
90
{"pos":6,"name":"Apple iPhone 4S 32 Gb Black","price":28900,"regionId":
213,"shippingCost":300,"inStock":1,"shopName":"SnowWhite.Ru","shopRating":5},
{"pos":7,"name":"Apple iPhone 4S 32Gb","price":27200,"regionId":
{"pos":8,"name":"Smartphone Apple iPhone 4S 32Gb White","price":40990,"regionId":
{"pos":9,"name":"iPhone 4S 32GB, Black","price":36550,"regionId":
213,"shippingCost":0,"inStock":1,"shopName":"SleepingBeauty.Ru","shopRating":3},
{"pos":10,"name":"Apple iPhone 4S 32Gb","price":27200,"regionId":
213,"shippingCost":300,"inStock":1,"shopName":"WickedWitch.Ru","shopRating":5}
],
"onlineOffers":729,
"offlineOffers":508
}
],
"regionId":213,
"currency":"RUR"
}
Developer's guide
91
Managing bids
Bid management methods are for setting and removing bids (basic bids and product profile bids) for product
offers in priority placement areas in Yandex.Market.
The position that your offer will be placed in depends on your bid. Offers with a larger bid are displayed first
(in certain placement areas, the offer position also depends on its popularity, or clickability). There are two types
of bids on Yandex.Market:
•
Basic bid — The bid for showing a product offer on Yandex search, Yandex.Market search, and the Yandex
Advertising Network, and also for the product profile, if the product profile bid is not set separately.
•
Product profile bid — The bid for showing product offers on the product profile page in Yandex.Market.
If the product profile bid is not specified, the basic bid is used for the product profile.
Note:
Prior to version 2.0 of the Partner API, recommended bids were given only for Yandex.Market product profiles.
Method
Short description
Restrictions
Returns information about bids set for
product offers for the campaign
specified in the request.
500 recommendations per request.
Sets or removes bids on product offers. Individual number of requests per day;
500 bids per request.
POST campaigns/{campaignId}/bids/
recommended
Returns recommended bid values
for product offers for placing these
offers in priority positions
on Yandex.Market.
500 recommendations per request.
PUT campaigns/{campaignId}/bids/
recommended
Sets the recommended bid values
on product offers.
500 bids per request.
For the methods PUT campaigns/{campaignId}/bids, POST campaigns/{campaignId}/bids/recommended,
and PUT campaigns/{campaignId}/bids/recommended, a group resource limit is applied.
Settings in the partner interface
In order to use the Partner API to set bids, you must select the partner interface and the API as the source of bid
information in the partner interface. To do this, go to the Managing Bids page in the partner interface and click
Settings. You will see a form for selecting the source of bid information.
If you previously specified bids in a price list, when you switch the bid source it will use the bids that are specified
using the Partner API.
You can also select the mode for working with product offers:
•
Identifying products by name — Bid operations use the product offer name indicated in the price list.
If two or more products have the same name, the bid will be set simultaneously for all of these products.
•
Identifying products by ID — Bid operations use the product offer ID. All product offer IDs must be unique
within a single price list.
Developer's guide
92
Information about bids
Description
Returns information about bids set for product offers for the campaign specified in the request.
The list of product offers to get information for is passed in the body of the POST request. There is a limit on the
number of product offers in a single request: 500 offers.
Note:
Resource URL:
https://api.partner.market.yandex.ru/v2/campaigns/{campaignId}/bids.[format]
Input data
Parameter
Type
Value
Number
The campaign ID.
Mandatory
campaignId
XML
<offers>
<offer id="{string}" feed-id="{number}" name="{string}"/>
...
</offers>
JSON
{
"offers":
[
{
"name":"{string}",
"id":"{string}",
"feedId":{number}
},
...
]
}
Parameter
for XML
format
Parameter
for JSON
format
offers
offers
Type
Value
List of product offers.
Developer's guide
93
Parameter
for XML
format
Parameter
for JSON
format
Type
offer
Value
Product offer.
name
name
String
This parameter is specified when getting information about a bid based
on the product offer name.
id
id
String
on the product offer ID.
feed-id
feedId
Number
on the product offer ID, when the campaign has more than one registered
price list.
Output data
XML
<bids>
<bid offer-id="{string}" feed-id="{number}" bid="{number}" cbid="{number}"
status="{string}" modified="{string}" offer-name="{string}"/>
...
</bids>
JSON
{
"bids":
[
{
"offerName":"{string}",
"offerId":"{string}",
"feedId":{number},
"bid":{number},
"cbid":{number},
"status":"{string}",
"modified":"{string}"
},
...
]
}
Parameter
for XML
format
Parameter
for JSON
format
bids
bids
Type
Value
List of set bids.
Parameters nested in bids
bid
Information about a bid for the product offer.
Parameters nested in bid
offer-name
offerName
String
Developer's guide
94
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
This parameter is output when getting information about a bid based
on the product offer name.
offer-id
offerId
String
This parameter is output when getting information about a bid based
feed-id
feedId
Number
bid
bid
Number
The set basic bid, in Yandex units.
If omitted, the basic bid is not set for the product offer, meaning the default
bid is used.
cbid
cbid
Number
The set bid for the product profile, in Yandex units.
If omitted, the product profile bid is not set for the product offer, meaning
the default bid is used.
status
status
String
The bid status or code of an error that occurred.
Possible values:
modified
modified
String
•
PUBLISHED — Bid is published.
•
INDEXING — Bid is being applied.
•
ERROR_OFFER_NOT_FOUND — An error occurred and the
product offer specified in the request was not published.
•
ERROR_INVALID_BID_VALUE — An error occurred; invalid
bid value.
•
ERROR_UNKNOWN — An unknown error occurred; try calling
the method later. If the error persists, contact the support service
of the Yandex.Market partner interface.
Date and time of the last bid modification in the format DD-MM-YYYY
HH:MM:SS.
Error descriptions
Description
Explanation
Possible solution
Too many offers:
'offersCount'
The number of product offers
Decrease the number of product offers being
specified in the request exceeds
passed.
the maximum amount: 500 product
offers.
Offer name should not be The name of the product offer
empty
passed in the request body must
not be empty.
in the request.
Duplicate offers
are not allowed:
'offerName'/'offerId'
The same product offer cannot
be specified more than once.
in the request.
Feed-id should
be specified
The ID of the price list was not
specified.
in the request.
Developer's guide
95
Description
Explanation
Possible solution
Current offer
identification type
is: 'idType'
The bid ID does not match the mode Identify bids in accordance with the selected
in use.
mode. If necessary, change the identification
mode in the partner interface.
Either offer-id
or offer-name should
be specified
Neither the name nor the ID of
the product offer was specified
in the request.
Feed should
be specified
The price list ID was not specified; Check whether the correct data is being passed
this is a mandatory parameter if the in the request.
campaign has more than
one registered price list and the
selected mode is to get bid
information using the product offer
ID.
in the request to match the selected mode.
Error 403 Forbidden
Auction is not allowed
for campaign
'campaignId'. Reason:
'reason'
Bids cannot be set or removed If the reason is SOURCE_NOT_WEB, set the
for the campaign campaignId source for bid information in the partner
because of reason.
interface to "partner interface". In the other
cases, bid management is not available.
Possible reasons:
•
SOURCE_NOT_WEB — In
the partner interface,
the source for bid information
is set to something other than
"partner interface".
•
OFFLINE_SHOP — The
campaign specified in the
request is for an offline shop.
Offline shops do not have
access to bid management.
•
FIXED_TARIFF — The
"Start" placement type is set
for the campaign specified
in the request. Shops with
"Start" placement do not have
Error 404 Not Found
Feed not found:
'feedId'
in the request.
Restrictions
•
Note:
Developer's guide
96
Examples
XML
Sample request:
POST https://api.partner.market.yandex.ru/v2/campaigns/10001/bids.xml
POST request body:
<offers>
<offer id="120" feed-id="31920"/>
<offer id="121" feed-id="31920"/>
<offer id="122" feed-id="31920"/>
</offers>
Sample response:
<response>
<bids>
<bid offer-id="120" feed-id="31920" bid="0.22" cbid="0.33" status="PUBLISHED"
modified="16-11-2012 12:31:47"/>
<bid offer-id="121" feed-id="31920" cbid="0.51" status="INDEXING"
modified="16-11-2012 20:01:38"/>
<bid offer-id="122" feed-id="31920" bid="1.12" status="ERROR_OFFER_NOT_FOUND"
modified="12-11-2012 16:49:05"/>
</bids>
</response>
JSON
Sample request:
POST https://api.partner.market.yandex.ru/v2/campaigns/10001/bids.json
POST request body:
{"offers":[
{"id":"120", "feedId":31920},
{"id":"121", "feedId":31920},
{"id":"122", "feedId":31920}
]}
Sample response:
{"bids":
[
{"offerId":"120", "feedId":31920, "bid":0.22, "cbid":0.33, "status":"PUBLISHED",
"modified":"16-11-2012 12:31:47"},
{"offerId":"121", "feedId":31920, "cbid":0.51, "status":"INDEXING",
"modified":"16-11-2012 20:01:38"},
{"offerId":"122", "feedId":31920, "bid":1.12, "status":"ERROR_OFFER_NOT_FOUND",
"modified":"12-11-2012 16:49:05"}
]
}
Setting bids for offers
Description
Sets or removes bids on product offers.
Developer's guide
97
Attention!
In order to use this method, the information source for bids in the partner interface must be set to the partner
interface and the API.
Bid values are passed in the body of the PUT request. There is a limit on the number of bids in a single request:
500 bids.
Resource URL:
https://api.partner.market.yandex.ru/v2/campaigns/{campaignId}/bids.[format]
Input data
Parameter
Type
Value
Number
The campaign ID.
Mandatory
campaignId
Structure of the body of the PUT request:
XML
<offer-bids>
<offer-bid offer-name="{string}" offer-id="{string}" feed-id="{number}" bid="{number}"
cbid="{number}"/>
...
</offer-bids>
Structure of the PUT request body prior to version 2.0 of the Yandex.Market Partner API
<offer-bids>
<offer-bid bid="{number}" cbid="{number}">
<offer-name>{string}</offer-name>
</offer-bid>
...
</offer-bids>
JSON
{
"bids":
[
{
"feedId":{number},
"bid":{number},
"cbid":{number},
"offerName":"{string}"
},
...
]
}
Structure of the PUT request body prior to version 2.0 of the Yandex.Market Partner API
{
"bids":
[
{
"bid":{number},
"cbid":{number},
"offerName":"{string}"
},
...
]
}
Developer's guide
98
The following parameters are passed in the body of the PUT request:
Parameter
for XML
format
Parameter
for JSON
format
offer-bids
bids
Type
Value
List of bids.
Parameters nested in offer-bids/bids
offer-bid
Description of a bid.
Each description must indicate the selected offer ID and at least one of
the parameters bid or cbid.
Parameters nested in offer-bid
offer-name
offerName
String
This parameter is specified when setting a bid based on the product offer
name.
offer-id
offerId
String
ID.
Partner API.
feed-id
feedId
Number
ID, when the campaign has more than one registered price list.
Partner API.
bid
bid
Number
Basic bid, in Yandex units.
To remove the basic bid (i.e. set the default bid for a product offer), set the
parameter value to 0.
This parameter is optional. If the parameter is omitted or set to an empty
value, the current basic bid does not change.
cbid
cbid
Number
The bid for the product profile, in Yandex units.
To remove the product profile bid (i.e., set the default bid for the product
offer), set the parameter value to 0.
This parameter is optional. If the parameter is omitted or set to an empty
value, the current product profile bid does not change.
Attention!
Bid values are updated in the Yandex.Market partner interface approximately once every three hours, so it
is pointless to change bid values more often than once an hour.
Output data
Developer's guide
99
XML
<bids-set>
cbid="{number}" error="{string}"/>
...
</bids-set>
Output data structure prior to version 2.0 of the Yandex.Market Partner API
<bids-set>
<offer-bid bid="{number}" cbid="{number}" error="{string}">
</offer-bid>
...
</bids-set>
JSON
{
"bidsSet":
[
{
"offerId":"239982",
"feedId":30919,
"bid":{number},
"cbid":{number},
"error":"{string}"
},
...
]
}
{
"bids-set":
[
{
"bid":{number},
"cbid":{number},
"error":"{string}"
},
...
]
}
Parameter
for XML
format
Parameter
for JSON
format
bids-set
bidsSet
Type
Value
List of set bids.
was called bids-set in JSON format.
Parameters nested in bids-set
offer-bid
Description of a set bid.
Parameters nested in offer-bid
offer-name
offerName
String
This parameter is output when setting a bid based on the product offer
ID.
offer-id
offerId
String
Developer's guide
100
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
ID.
feed-id
feedId
Number
ID.
bid
bid
Number
cbid
cbid
Number
error
error
String
Code of the error that occurred. The parameter is output only if an error
occurred.
Possible values:
•
OFFER_NOT_FOUND — The product offer has not been
published.
•
INVALID_BID_VALUE — An incorrect bid value was specified.
Error descriptions
Description
Explanation
Possible solution
Too many bids:
'bidsCount'
The number of bids specified in the Decrease the number of bids being passed.
request exceeds the maximum
amount: 500 bids.
empty
not be empty.
in the request.
Either bid or cbid
should be specified
For each product offer passed in the Specify at least one of the bids, bid or cbid,
request body, there must be at least for each product offer.
one bid specified: bid or cbid.
Duplicate offer bids
are not allowed:
'offerName'
The same product offer is found
more than once in the data passed
in the request body.
Feed should
be specified
one price list registered and the
selected bid setting mode uses
the product offer ID.
Current offer
identification type
is: 'idType'
in use.
Check for duplicated product offers in the data
being passed in the request body.
Error 403 Forbidden
for campaign
'reason'
because of reason.
Developer's guide
101
Description
Explanation
Possible solution
Possible reasons:
•
•
•
Error 404 Not Found
Feed not found:
'feedId'
in the request.
Restrictions
and PUT campaigns/{campaignId}/bids/recommended, a group resource limit is applied. The limit applies to the
total number of offers that these methods are used for to set bids and get recommendations.
•
Note:
Examples
XML
Sample request when setting bids by product offer ID:
PUT https://api.partner.market.yandex.ru/v2/campaigns/10001/bids.xml
Body of the PUT request:
<offer-bids>
<offer-bid offer-id="239982" feed-id="30919" bid="0.22" cbid="0.33"/>
</offer-bids>
Sample response:
Developer's guide
102
<response>
<bids-set>
<offer-bid offer-id="239984" feed-id="30919" bid="0.22" cbid="0.15"
error="OFFER_NOT_FOUND"/>
</bids-set>
</response>
Sample request prior to version 2.0 of the Yandex.Market Partner API
PUT https://api.partner.market.yandex.ru/v1/campaigns/10001/bids.xml
<offer-bids>
<offer-bid bid="0.4" cbid="0.33">
<offer-name>Bosch MSM 6B300</offer-name>
</offer-bid>
<offer-name>Tefal HB 7151</offer-name>
</offer-bid>
<offer-name>Philips HR 1371</offer-name>
</offer-bid>
</offer-bids>
Sample response:
<response>
<bids-set>
</offer-bid>
</offer-bid>
<offer-bid bid="0.18" cbid="0.15" error="OFFER_NOT_FOUND">
</offer-bid>
</bids-set>
</response>
JSON
Sample request when setting bids by product offer ID:
PUT https://api.partner.market.yandex.ru/v2/campaigns/10001/bids.json
{"bids":[
{"offerId":"239982","feedId":30919,"bid":0.22, "cbid":0.33},
{"offerId":"239983","feedId":30919,"bid":0.22, "cbid":0.27},
{"offerId":"239984","feedId":30919,"bid":0.22, "cbid":0.15}
]}
Sample response:
{"bidsSet":[
{"offerId":"239982","feedId":30919,"bid":0.22, "cbid"=0.33},
{"offerId":"239983","feedId":30919,"bid":0.22, "cbid"=0.27},
{"offerId":"239984","feedId":30919,"bid":0.22,
"cbid"=0.15,"error":"OFFER_NOT_FOUND"}
]}
PUT https://api.partner.market.yandex.ru/v1/campaigns/10001/bids.json
Developer's guide
103
{"bids":[
{"bid":0.4, "cbid":0.33, "offerName":"Bosch MSM 6B300"},
{"bid":0.35, "cbid":0.27, "offerName":"Tefal HB 7151"},
{"bid":0.18, "cbid":0.15, "offerName":"Philips HR 1371"}
]}
Sample response:
{"bids-set":[
{"offerName":"Bosch MSM 6B300","bid":0.4,"cbid":0.33},
{"offerName":"Tefal HB 7151","bid":0.35,"cbid":0.27},
{"offerName":"Philips HR 1371","bid":0.18,"cbid":0.15,"error":"OFFER_NOT_FOUND"}
]}
Bid recommendations
Description
POST campaigns/{campaignId}/bids/recommended
Returns recommended bid values for the specified product offers for placing these offers in priority positions
on Yandex.Market. Bid recommendations are calculated for the campaign region (the region the shop is located
in).
The list of product offers to get recommendations for is passed in the body of the POST request. There is a limit
on the number of product offers in a single request: 500 offers.
Note:
Prior to version 2.0, the Partner API could be used to get bid recommendations only for Yandex.Market product
profiles.
Resource URL:
https://api.partner.market.yandex.ru/v2/campaigns/{campaignId}/bids/recommended.
[format]
Input data
Parameter
Type
Value
campaignId
Number
The campaign ID.
target
String
The type of bid that the recommended value is being set for.
Mandatory
Possible values:
•
model-card — The bid for the product profile.
•
search — The basic bid.
Optional
positions
Number
List of position numbers in the product offer section of the display area that you need to get
bid recommendations for. The position numbers are comma-separated.
Acceptable values when getting recommendations for the product profile: from 1 to 10.
Developer's guide
104
Parameter
Type
Value
Acceptable values when getting recommendations for the basic bid:
•
0 — Displaying the product offer in the Premium Placement section.
•
1 — Placed in the top position.
•
5 — Guaranteed Placement.
The list may specify no more than ten positions. If the parameter is omitted or has an empty
value, the response for the product profile gives recommendations for the first five positions,
and the response for the basic bid gives recommendations for all positions.
XML
<offers>
<offer name="{string}" id="{string}" feed-id="{number}" query="{string}"/>
...
</offers>
Structure of the POST request body for XML format prior to version 2.0 of the Yandex.Market Partner API
<offers>
...
</offers>
JSON
{
"offers":
[
{
"name":"{string}",
"id":"{string}",
"feedId":{number},
"query":"{string}"
},
...
]
}
Structure of the POST request body for JSON format prior to version 2.0 of the Yandex.Market Partner API
{
"offers":
[
"{string}",
...
]
}
Parameter
for XML
format
Parameter
for JSON
format
offers
offers
Type
Value
offer
Product offer.
name
name
String
This parameter is specified when requesting bids based on the product
offer name.
Developer's guide
105
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
id
id
String
offer ID.
Partner API.
feed-id
feedId
Number
offer ID, when the campaign has more than one registered price list.
Partner API.
query
query
String
The search query that the basic bid is being set for.
This parameter is mandatory if the basic bid is selected as the bid to
get recommended values for in the request.
Partner API.
Output data
XML
<recommendations>
<offer id="{string}" feed-id="{number}" error="{string}">
<model-card offer-position="{number}">
<position pos="{number}" cbid="{number}" error="{string}"></position>
...
</model-card>
<search>
<position pos="{number}" bid="{number}" error="{string}"></position>
...
</search>
</offer>
...
</recommendations>
<recommendations>
<offer error="{string}">
<model-card offer-position="{number}">
<position pos="{number}" cbid="{number}" error="{string}"></position>
...
</model-card>
</offer>
...
</recommendations>
JSON
{
"recommendations":
[
{
"feedId":{number},
"modelCard":
{
"error":"{string}",
Developer's guide
106
"offerPosition":{number},
"posRecommendations":
{
"{number}":
{
"cbid":{number},
"error":"{string}"
},
...
}
},
"search":
{
"error":"{string}",
{
"{number}":
{
"bid":{number},
"error":"{string}"
},
...
}
}
},
...
]
}
Output data structure for JSON format prior to version 2.0 of the Yandex.Market Partner API
{
"recommendations":
[
{
"modelCard":
{
"error":"{string}",
"offerPosition":{number},
{
"{number}":
{
"cbid":{number},
"error":"{string}"
},
...
}
}
},
...
]
}
Parameter
for XML
format
Parameter
for JSON
format
Type
recommendat recommendat
ions
ions
Value
List of recommendations.
Parameters nested in recommendations
offer
A recommendation for product offer bids.
name
offerName
String
This parameter is output when requesting bids based on the product offer
name.
Developer's guide
107
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
offer-id
offerId
String
This parameter is output when requesting bids based on the product offer
ID.
feed-id
feedId
Number
offer ID.
error
String
occurred.
Possible values:
model-card
modelCard
•
OFFER_NOT_DELIVERED — The position indicated in the
request is impossible because the product offer is not delivered to the
region.
•
OFFER_NOT_MATCHED — The product offer is not associated
with a product profile.
•
published.
Recommended bid for the product offer to show it in the product profile.
This parameter is output if the recommended bid value is requested for the
product profile bid.
search
search
The recommended basic bid for the product offer.
This parameter is output if the recommended bid value is requested for the
basic bid.
Parameters nested in model-card/modelCard
error
String
occurred.
Possible values:
•
region.
•
•
published.
offerposition
offerPositi Number
on
The current position of the product offer on the product profile. If the
offer is not in the top ten, the parameter has an empty value.
position
posRecommen
dations
Recommended bid for the product offer to place it in a certain position.
Parameters nested in search
error
String
occurred.
Developer's guide
108
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
Possible values:
position
posRecommen
dations
•
region.
•
published.
•
OFFER_LOW_CTR — The position indicated in the request
is impossible due to a low CTR for the product offer (there are not
enough click-throughs on this offer in relation to the number
of impressions).
•
OFFER_BAD_CATEGORY — The position indicated in the
request is impossible because the offer belongs to a category
of Yandex.Market products that are not shown in Yandex search
results (for example, products in the "Knife" category).
•
STOP_QUERY — The position indicated in the request
is impossible because a stop query is used (Yandex.Market product
offers are not shown on Yandex search for this query).
Recommended bid for the product offer to place it in a certain position.
Parameters nested in position/posRecommendations
pos
Number
Number of the product offer's position on Yandex search or on the product
profile that the recommendation is for.
bid
bid
Number
The recommended bid to achieve the specified position on Yandex search,
in Yandex units.
cbid
cbid
Number
The recommended bid to achieve the specified position on the product
profile, in Yandex units.
error
error
String
occurred.
Possible values:
•
BID_UPPER_LIMIT — The position indicated in the request
is impossible because a competitor has set the maximum bid.
Error descriptions
Description
Explanation
Possible solution
Too many offers:
'offersCount'
passed.
offers.
empty
not be empty.
in the request.
Too many positions
specified
Reduce the number of positions in the
positions parameter.
The number of positions specified
in the positions parameter
exceeds the maximum number
of positions.
Developer's guide
109
Description
Explanation
Possible solution
Position number should
be positive and not
greater than
'maxPosition':
'position'
The position number specified
in the request must be a positive
integer and must not exceed
the maxPosition value.
Check whether the positions are specified
correctly in the request.
be in
'availablePositions' :
'position'
The position number in the request Check whether the positions are specified
must be from the list of acceptable correctly in the request.
values
in availablePositions.
Invalid position
number: 'position'
The position specified in the request Check whether the positions are specified
is not a number.
Feed should
be specified
Current offer
identification type
is: 'idType'
in use.
Error 403 Forbidden
for campaign
'reason'
Bids cannot be set or removed Bid management is not available.
for the campaign campaignId
because of reason.
Possible reasons:
•
•
Error 404 Not Found
Feed not found:
'feedId'
in the request.
Restrictions
•
Note:
Developer's guide
110
Sample for XML format
Sample request for getting recommended bids by product offer name:
POST https://api.partner.market.yandex.ru/v2/campaigns/10001/bids/
recommended.xml?target=model-card
POST request body:
<offers>
<offer name="Pioneer AVH-P6300BT"/>
<offer name="Mystery MCD-695MPU"/>
<offer name="Braun HD750"/>
</offers>
Sample response:
<response>
<recommendations>
<offer>
<name>Pioneer AVH-P6300BT</name>
<model-card offer-position="4">
<position pos="1" cbid="0.21"></position>
</model-card>
</offer>
<offer>
<name>Mystery MCD-695MPU</name>
</model-card>
</offer>
<offer>
<name>Braun HD750</name>
</model-card>
</offer>
</recommendations>
</response>
Sample request for getting recommended bids by product offer ID:
recommended.xml?target=model-card
POST request body:
Developer's guide
111
<offers>
<offer id="239982" feed-id="30919"/>
<offer id="239983" feed-id="30919"/>
<offer id="239984" feed-id="30919"/>
</offers>
Sample response:
<response>
<recommendations>
<offer id="239982" feed-id="30919">
</model-card>
</offer>
<offer id="239983" feed-id="30919">
</model-card>
</offer>
<offer id="239984" feed-id="30919">
</model-card>
</offer>
</recommendations>
</response>
recommended.xml
POST request body:
<offers>
</offers>
Sample response:
<response>
<recommendations>
<offer>
Developer's guide
112
</model-card>
</offer>
<offer>
</model-card>
</offer>
<offer>
</model-card>
</offer>
</recommendations>
</response>
Sample for JSON format
Sample request for getting recommended bids by product offer name:
recommended.json?target=model-card
POST request body:
{"offers":
[
{"name":"Pioneer AVH-P6300BT"},
{"name":"Mystery MCD-695MPU"},
{"name":"Braun HD750"}
]
}
Sample response:
{"recommendations":
[
{
"offerName":"Pioneer AVH-P6300BT",
"model-card":
{
"offerPosition":4,
{
"1":{"cbid":0.21},
"2":{"cbid":0.16},
"3":{"cbid":0.13},
"4":{"cbid":0.12},
"5":{"cbid":0.12}
}
}
},
{
"offerName":"Mystery MCD-695MPU",
"modelCard":
{
"offerPosition":3,
Developer's guide
113
{
"1":{"cbid":0.15},
"2":{"cbid":0.13},
"3":{"cbid":0.12},
"4":{"cbid":0.12},
"5":{"cbid":0.11}
}
}
},
{
"offerName":"Braun HD750",
"modelCard":
{
"offerPosition":8,
{
"1":{"cbid":0.67},
"2":{"cbid":0.63},
"3":{"cbid":0.41},
"4":{"cbid":0.31},
"5":{"cbid":0.31}
}
}
}
]
}
Sample request for getting recommended bids by product offer ID:
recommended.json?target=model-card
POST request body:
{"offers":
[
{"id":"239982","feedId":30919},
{"id":"239983","feedId":30919},
{"id":"239984","feedId":30919}
]
}
Sample response:
{"recommendations":
[
{
"offerId":"239982",
"feedId":30919,
"model-card":
{
"offerPosition":4,
{
"1":{"cbid":0.21},
"2":{"cbid":0.16},
"3":{"cbid":0.13},
"4":{"cbid":0.12},
"5":{"cbid":0.12}
}
}
},
{
"offerId":"239983",
"feedId":30919,
"modelCard":
{
"offerPosition":3,
Developer's guide
114
{
"1":{"cbid":0.15},
"2":{"cbid":0.13},
"3":{"cbid":0.12},
"4":{"cbid":0.12},
"5":{"cbid":0.11}
}
}
},
{
"offerId":"239984",
"feedId":30919,
"modelCard":
{
"offerPosition":8,
{
"1":{"cbid":0.67},
"2":{"cbid":0.63},
"3":{"cbid":0.41},
"4":{"cbid":0.31},
"5":{"cbid":0.31}
}
}
}
]
}
recommended.json
POST request body:
{"offers":
[
"Pioneer AVH-P6300BT",
"Mystery MCD-695MPU",
"Braun HD750"
]
}
Sample response:
{"recommendations":
[
{"offerName":"Pioneer AVH-P6300BT","modelCard":{"offerPosition":
4,"posRecommendations":{"1":{"cbid":0.21},"2":{"cbid":0.16},"3":{"cbid":
0.13},"4":{"cbid":0.12},"5":{"cbid":0.12}}}},
{"offerName":"Mystery MCD-695MPU","modelCard":{"offerPosition":
0.12},"4":{"cbid":0.12},"5":{"cbid":0.11}}}},
{"offerName":"Braun HD750","modelCard":{"offerPosition":
0.41},"4":{"cbid":0.31},"5":{"cbid":0.31}}}}
]
}
Setting recommended bids
Description
PUT campaigns/{campaignId}/bids/recommended
Developer's guide
115
Sets recommended bid values for the specified product offers for placing these offers in priority positions
on Yandex.Market. Bid recommendations are calculated for the campaign region (the region the shop is located
in).
When setting bids, modifiers can be applied to the recommended values of these bids. The following modifiers
are available: absolute (set in Yandex units) and relative (set as a percent). If both modifiers are specified
simultaneously, the relative one is applied first, then the absolute one.
It is also possible to set a maximum limit on bid values being set. The limit is checked after the modifiers
are applied to bids. If applying the modifiers caused any of the bid values to exceed the allowed limits, the bid
is adjusted to the nearest allowed value.
Attention!
In order to use this method, the information source for bids in the partner interface must be set to the partner
interface.
The list of product offers to set recommended values for is passed in the body of the PUT request. There is a
limit on the number of bids in a single request: 500 bids.
Note:
Prior to version 2.0, the Partner API could be used to set recommended bids only for Yandex.Market product
profiles.
Resource URL:
https://api.partner.market.yandex.ru/v2/campaigns/{campaignId}/bids/recommended.
[format]
Input data
Parameter
Type
Value
campaignId
Number
The campaign ID.
target
String
The type of bid that the recommended value is being set for.
Mandatory
Possible values:
•
model-card — The bid for the product profile.
•
search — The basic bid.
position
Number
The desired position number in the section of product offers in the display area that
the recommended bid is being set for.
Acceptable values when setting recommended bids for the product profile: from 1 to 10.
Acceptable values when setting recommendations for the basic bid:
•
0 — Displaying the product offer in the Premium Placement section.
•
1 — Placed in the top position.
•
5 — Guaranteed Placement.
Optional
offset
Number
Absolute modifier. The value that the recommended bid is changed by before setting it, in
Yandex units. Either positive or negative values are acceptable.
Developer's guide
116
Parameter
Type
Value
offsetPct
Number
Relative modifier. The value that the recommended bid is changed by before setting it, as
a percent. Either positive or negative values are acceptable.
maxBid
Number
The maximum value for bids being set, in Yandex units.
Structure of the body of the PUT request:
XML
<offers>
<offer name="{string}" id="{string}" feed-id="{number}" query="{string}"/>
...
</offers>
Structure of the PUT request body for XML format prior to version 2.0 of the Yandex.Market Partner API
<offers>
...
</offers>
JSON
{
"offers":
[
{
"name":"{string}",
"id":"{string}",
"feedId":{number},
"query":"{string}"
},
...
]
}
Structure of the PUT request body for JSON format prior to version 2.0 of the Yandex.Market Partner API
{
"offers":
[
"{string}",
...
]
}
The following parameters are passed in the body of the PUT request:
Parameter
for XML
format
Parameter
for JSON
format
offers
offers
Type
Value
offer
Product offer.
name
name
String
name.
id
id
String
ID.
Developer's guide
117
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
Partner API.
feed-id
feedId
Number
ID, when the campaign has more than one registered price list.
Partner API.
query
query
String
The search query that the basic bid is being set for.
This parameter is mandatory if a recommended bid value is being
requested for the basic bid.
Partner API.
Attention!
Bid values are updated in the Yandex.Market partner interface approximately once every three hours, so it
is pointless to change bid values more often than once an hour.
Output data
XML
<bids-set>
cbid="{number}" error="{string}"/>
...
</bids-set>
<bids-set>
<offer-bid cbid="{number}" error="{string}">
</offer-bid>
...
</bids-set>
Developer's guide
118
JSON
{
"bidsSet":
[
{
"id":"{string}",
"feedId":{number},
"bid":{number},
"cbid":{number},
"error":"{string}"
},
...
]
}
Output data structure for JSON format prior to version 2.0 of the Yandex.Market Partner API
{
"bids-set":
[
{
"cbid":{number},
"error":"{string}"
},
...
]
}
Parameter
for XML
format
Parameter
for JSON
format
bids-set
bidsSet
Type
Value
List of set bids.
was called bids-set in JSON format.
Parameters nested in bids-set/bidsSet
offer-bid
offerBid
Description of a set bid.
Parameters nested in offer-bid/offerBid
offer-name
offerName
String
name.
offer-id
offerId
String
ID.
feed-id
feedId
Number
ID.
bid
bid
Number
If omitted, the basic bid is not set for the product offer, meaning the default
bid is used.
cbid
cbid
Number
If omitted, the product profile bid is not set for the product offer, meaning
the default bid is used.
Developer's guide
119
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
error
error
String
occurred.
Possible values:
•
BID_UPPER_LIMIT — The position indicated in the request
is impossible because a competitor has set the maximum bid.
•
region.
•
•
published.
•
OFFER_LOW_CTR — The position indicated in the request
is impossible due to a low CTR for the product offer (there are not
enough click-throughs on this offer in relation to the number
of impressions).
•
OFFER_BAD_CATEGORY — The position indicated in the
request is impossible because the offer belongs to a category
of Yandex.Market products that are not shown in Yandex search
results (for example, products in the "Knife" category).
•
STOP_QUERY — The position indicated in the request
is impossible because a stop query is used (Yandex.Market product
offers are not shown on Yandex search for this query).
Error descriptions
Description
Explanation
Possible solution
Too many offers:
'offersCount'
passed.
offers.
empty
not be empty.
in the request.
be positive and not
greater than
'maxPosition':
'position'
The position number specified
in the request must be a positive
integer and must not exceed
the maxPosition value.
Check whether the positions are specified
Invalid position
number: 'position'
The position specified in the request Check whether the positions are specified
is not a number.
Invalid maxBid value:
'maxBid'
The value of the maxBid
parameter specified in the request
is invalid.
Feed should
be specified
Check whether the maxBid parameter is set
Developer's guide
120
Description
Explanation
Possible solution
Current offer
identification type
is: 'idType'
in use.
Error 403 Forbidden
for campaign
'reason'
because of reason.
Possible reasons:
•
•
•
Error 404 Not Found
Feed not found:
'feedId'
in the request.
Restrictions
•
Note:
Examples
XML
Sample request for setting recommended bids by product offer ID:
PUT https://api.partner.market.yandex.ru/v2/campaigns/10001/bids/recommended.xml?
position=5&target=model-card
Developer's guide
121
<offers>
<offer id="239982" feed-id="30919"/>
<offer id="239983" feed-id="30919"/>
<offer id="239984" feed-id="30919"/>
</offers>
Sample response:
<response>
<bids-set>
<offer-bid id="239982" feed-id="30919" cbid="0.33"/>
<offer-bid id="239983" feed-id="30919" cbid="0.27"/>
<offer-bid id="239984" feed-id="30919" cbid="0.15" error="OFFER_NOT_FOUND"/>
</bids-set>
</response>
PUT https://api.partner.market.yandex.ru/v1/campaigns/10001/bids/recommended.xml?
position=5
<offers>
<name>Bosch MSM 6B300</name>
<name>Tefal HB 7151</name>
<name>Philips HR 1371</name>
</offers>
Sample response:
<response>
<bids-set>
<offer-bid cbid="0.33">
</offer-bid>
<offer-bid cbid="0.27">
</offer-bid>
<offer-bid error="OFFER_NOT_FOUND">
</offer-bid>
</bids-set>
</response>
JSON
Sample request for setting recommended bids by product offer ID:
PUT https://api.partner.market.yandex.ru/v2/campaigns/10001/bids/recommended.json?
position=5&target=model-card
POST request body:
{"offers":[
{"id":"239982","feedId":30919},
{"id":"239983","feedId":30919},
{"id":"239984","feedId":30919}
]}
Sample response:
{"bidsSet":[
{"id":"239982","feedId":30919,"cbid"=0.33},
{"id":"239983","feedId":30919,"cbid"=0.27},
{"id":"239984","feedId":30919,"cbid"=0.15,"error":"OFFER_NOT_FOUND"}
]}
PUT https://api.partner.market.yandex.ru/v1/campaigns/10001/bids/recommended.json?
position=5
Developer's guide
122
POST request body:
{"offers":[
"Bosch MSM 6B300",
"Tefal HB 7151",
"Philips HR 1371"
]}
Sample response:
{"bids-set":[
{"offerName":"Bosch MSM 6B300","cbid":0.33},
{"offerName":"Tefal HB 7151","cbid":0.27},
{"offerName":"Philips HR 1371","error":"OFFER_NOT_FOUND"}
]}
Bid settings
Description
GET campaigns/{campaignId}/bids/settings
Returns information about settings for set bids for the campaign specified in the request.
Note:
Resource URL:
https://api.partner.market.yandex.ru/v2/campaigns/{campaignId}/bids/settings.
[format]
Input data
Parameter
Type
Value
Number
The campaign ID.
Mandatory
campaignId
Output data
XML
<settings bids-from="{string}" offer-id-by="{string}" autobroker-enabled="{boolean}"/>
JSON
{
"settings":
{
bidsFrom:"{string}",
offerIdBy:"{string}",
autobrokerEnabled:{boolean}
}
}
Developer's guide
123
Parameter
for XML
format
Parameter
for JSON
format
settings
settings
Type
Value
Bid settings.
Parameters nested in settings
bids-from
bidsFrom
String
Source of information about bids.
Possible values:
offer-id-by offerIdBy
String
•
PRICE_LIST — Bids are shown in the price list.
•
UI_OR_API — Bids are shown in the partner interface or passed
using the Partner API.
•
DISABLED — Bids are disabled.
Type of product identification.
Possible values:
autobroker- autobrokerE Logical
enabled
nabled
•
TITLE — By product name.
•
OFFER ID — By the offer_id identifier shown in the price list.
Whether Autobroker is used:
•
true — Autobroker is enabled.
•
false — Autobroker is disabled.
Error descriptions
Description
Explanation
Possible solution
Error 403 Forbidden
Access denied
Examples
XML
Sample request:
GET http://api.partner.market.yandex.ru/v2/campaigns/10001/bids/settings.xml
Sample response:
<response>
<settings bids-from="UI_OR_API" offer-id-by="OFFER_ID" autobroker-enabled="true"/>
</response>
JSON
Sample request:
GET http://api.partner.market.yandex.ru/v2/campaigns/10001/bids/settings.json
Sample response:
{"settings":{bidsFrom:"UI_OR_API", offerIdBy:"OFFER_ID", autobrokerEnabled:true}}
Developer's guide
124
Finances
Use the finance methods to get financial information about campaigns on Yandex.Market.
Method
Short description
Restrictions
GET campaigns/{campaignId}/balance Returns the current balance of funds
for the campaign, along with a forecast
of expenditures and the recommended
payment amount.
Campaign balance and forecast of expenditures
Description
GET /campaigns/{campaignId}/balance
Returns the current balance of funds for the campaign specified in the request, along with a forecast
of expenditures and the recommended payment amount.
Resource URL:
https://api.partner.market.yandex.ru/v2/campaigns/{campaignId}/balance.[format]
Input data
Parameter
Type
Value
Number
The campaign ID.
Mandatory
campaignId
Output data
XML
<balance balance="{number}" days-left="{number}" recommended-payment="{number}"></
balance>
<balance>
<balance balance="{number}" days-left="{number}" recommended-payment="{number}"/>
</balance>
JSON
{
"balance":
{
"balance":{number},
"daysLeft":{number},
"recommendedPayment":{number}
}
}
Developer's guide
125
Parameter
for XML
format
Parameter
for JSON
format
balance
balance
Type
Value
Balance.
Parameters nested in balance
balance
balance
Number
Value of the current campaign balance in Yandex units.
days-left
daysLeft
Number
The forecasted number of days left before funds are completely used up.
recommended recommended Number
-payment
Payment
The recommended payment amount in Yandex units.
Error descriptions
Examples
XML
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/10002/balance.xml
Sample response:
<response>
<balance balance="85.74" days-left="4" recommended-payment="415.00"></balance>
</response>
JSON
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/10002/balance.json
Sample response:
{"balance":{"balance":85.74,"daysLeft":4,"recommendedPayment":415.00}}
Developer's guide
126
Statistics
Use the statistics methods to get statistical information about running campaigns on Yandex.Market.
Method
Short description
Restrictions
GET campaigns/{campaignId}/stats/
main
Returns basic campaign statistics
(clicks and expenditures) for the
specified period of time. Statistics
are output for each day. Maximum time
period that may be specified: 180 days.
main-daily
are output for each day. Maximum time
main-weekly
are output by week. Maximum time
main-monthly
are output by month. Maximum time
offers
Returns basic statistics (clicks
and expenditures) for the campaign's
product offers for the specified time
period. Maximum time period that
may be specified: 30 days.
Individual number of requests per day.
Basic statistics
Description
GET
GET
GET
GET
/campaigns/{campaignId}/stats/main
/campaigns/{campaignId}/stats/main-daily
/campaigns/{campaignId}/stats/main-weekly
/campaigns/{campaignId}/stats/main-monthly
The methods return basic statistics (clicks and expenditures) for the campaign specified in the request, for the
requested period of time. The maximum time period for getting statistics in a single request is 180 days.
Note:
Statistics on clicks are available for the entire time from the creation of the campaign. Statistics on impressions
are available only for the last 30 days.
Developer's guide
127
Statistics are combined, depending on the request resource:
•
/campaigns/{campaignId}/stats/main — Statistics are output for each day of the requested
period.
•
/campaigns/{campaignId}/stats/main-daily — Statistics are output for each day of
the requested period (the same as for /campaigns/{campaignId}/stats/main).
•
/campaigns/{campaignId}/stats/main-weekly — Statistics are summarized by week for the
requested period.
•
/campaigns/{campaignId}/stats/main-monthly — Statistics are summarized by month
for the requested period.
Resource URLs:
https://api.partner.market.yandex.ru/v2/campaigns/{campaignId}/stats/main.
[format]
https://api.partner.market.yandex.ru/v2/campaigns/{campaignId}/stats/main-daily.
[format]
https://api.partner.market.yandex.ru/v2/campaigns/{campaignId}/stats/mainweekly.[format]
https://api.partner.market.yandex.ru/v2/campaigns/{campaignId}/stats/mainmonthly.[format]
Input data
Parameter
Type
Value
campaignId
Number
The campaign ID.
fromDate
Date
Start date of the report period.
Mandatory
Date format: DD-MM-YYYY.
Maximum length of the report period: 180 days.
Optional
toDate
Date
End date of the report period.
Maximum length of the report period: 180 days.
byEventtime Number
The type of date to use in the report.
Possible values:
•
1 (yes) — The event date is used in the report.
•
0 (no) — The report calculation date is used in the report.
By default, the event date is used.
byPlaces
Number
Whether to group by placement position:
•
1 (yes) — Group.
•
0 (no) — Do not group.
By default, grouping by placement is not used.
Output data
Developer's guide
128
XML
<main-stats>
<main-stats-item date="{date}" place-group="{number}" clicks="{number}"
spending="{number}"/>
...
</main-stats>
JSON
{
"mainStats":
[
{
"date":"{date}",
"placeGroup":{number},
"clicks":{number},
"spending":{number}
},
...
]
}
Parameter
for XML
format
Parameter
for JSON
format
main-stats
mainStats
Type
Value
List of statistical data grouped by day, week, or month (depending on the
resource specified in the request).
was called main-stats in JSON format.
Parameters nested in main-stats
main-statsitem
Statistics for a particular day, week, or month of the period specified in the
request.
Parameters nested in main-stats-item
date
date
Date
The date of statistics for the resources
{campaignId}/stat/main
and
{campaignId}/stat/main-daily.
/campaigns/
/campaigns/
The date of the beginning of the week of statistics for the /campaigns/
{campaignId}/stat/main-weekly resource.
The date of the beginning of the month of statistics for the /
campaigns/{campaignId}/stat/main-monthly resource.
Date format: YYYY-MM-DD.
place-group placeGroup
Number
Placement identifier when the request indicates grouping by placement
area (the byPlaces input parameter).
Possible values:
•
3 — Search+
•
4 — Product profiles
•
5 — Yandex.Market, other than product profiles
•
6 — Partners
If grouping by placement area is not set in the request, the parameter value
is 0.
Developer's guide
129
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
clicks
clicks
Number
The number of clicks per day, week, or month (depending on the resource
specified in the request).
spending
spending
Number
Expenditures on clicks per day, week, or month (depending on the
resource specified in the request), in Yandex units.
Error descriptions
Description
Explanation
Possible solution
The report period that statistics
were requested for exceeds
the maximum report period:
maxPeriod.
Make the report period shorter.
Too long time period.
Maximum is 'maxPeriod'
days
Examples
Resource /campaigns/{campaignId}/stats/main)
XML
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/10002/stats/main.xml?
fromDate=22-11-2011&toDate=28-11-2011
Sample response:
<response>
<main-stats>
<main-stats-item date="2011-11-22"
spending="11452.41"/>
spending="11805.57"/>
spending="11730.09"/>
spending="10206.59"/>
>
>
>
</main-stats>
</response>
place-group="0" clicks="39251"
place-group="0" clicks="30635" spending="7516.03"/
JSON
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/10002/stats/main.json?
fromDate=22-11-2011&toDate=28-11-2011
Sample response:
Developer's guide
130
{"mainStats":[
{"date":"2011-11-22","placeGroup":0,"clicks":39251,"spending":11452.41},
{"date":"2011-11-28","placeGroup":0,"clicks":14487,"spending":3798.01}
]}
Resource /campaigns/{campaignId}/stats/main-daily)
XML
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/10002/stats/main-daily.xml?
fromDate=22-11-2011&toDate=28-11-2011
Sample response:
<response>
<main-stats>
spending="11452.41"/>
spending="11805.57"/>
spending="11730.09"/>
spending="10206.59"/>
>
>
>
</main-stats>
</response>
JSON
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/10002/stats/main-daily.json?
fromDate=22-11-2011&toDate=28-11-2011
Sample response:
{"mainStats":[
]}
Resource /campaigns/{campaignId}/stats/main-weekly)
XML
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/10002/stats/main-weekly.xml?
fromDate=22-11-2011&toDate=28-11-2011
Sample response:
Developer's guide
131
<response>
<main-stats>
<main-stats-item date="2011-11-21" place-group="0" clicks="218899"
spending="61047.11"/>
<main-stats-item date="2011-11-28" place-group="0" clicks="14487" spending="3798.01"/
>
</main-stats>
</response>
JSON
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/10002/stats/main-weekly.json?
fromDate=22-11-2011&toDate=28-11-2011
Sample response:
{"mainStats":[
]}
Resource /campaigns/{campaignId}/stats/main-monthly)
XML
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/10002/stats/main-monthly.xml?
fromDate=22-11-2011&toDate=22-12-2011
Sample response:
<response>
<main-stats>
spending="740217.05"/>
spending="93305.33"/>
</main-stats>
</response>
JSON
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/10002/stats/main-monthly.json?
fromDate=22-11-2011&toDate=22-12-2011
Sample response:
{"mainStats":[
]}
Statistics for product offers
Description
GET /campaigns/{campaignId}/stats/offers
Returns basic statistics (clicks and expenditures) for the product offers specified in the campaign request for the
requested time period.
Developer's guide
132
Product offers can be filtered by search query. Starting with version 2.0 of the Yandex.Market Partner API,
statistics can be obtained for a specific product offer when specifying its ID from the price list in the request.
Statistics by offer are available for the last 30 days (not including the current day).
Resource URL:
https://api.partner.market.yandex.ru/v2/campaigns/{campaignId}/stats/offers.
[format]
Input data
Parameter
Type
Value
campaignId
Number
The campaign ID.
fromDate
Date
Start date of the report period.
Mandatory
Optional
toDate
Date
End date of the report period.
query
String
The search query for filtering product offers that statistics are needed for. By default, filtering
does not occur.
offerId
String
ID of the product offer from the price list to get statistics for.
feedId
Number
ID of the price list containing the product offer to get statistics for.
This parameter is mandatory if the request specifies the offerId parameter and the
campaign has more than one price list registered.
pageSize
Number
The number of offers to output on the page with search results in the response.
Default value: 10 offers.
page
Number
Output data
Developer's guide
133
XML
<offers-stats total-offers-count="{number}" from-offer="{number}" to-offer="{number}">
<offer-stats clicks="{number}" spending="{number}" offer-id="{number}" feedid="{number}">
</offer-stats>
...
</offers-stats>
<offers-stats>
<offers-stats total-offers-count="{number}" from-offer="{number}" tooffer="{number}">
<offer-stats clicks="{number}" spending="{number}">
</offer-stats>
...
</offers-stats>
</offers-stats>
JSON
{
"offersStats":
{
"offerStats":
[
{
"clicks":{number},
"spending":{number},
"offerId":{number},
"feedId":{number}
},
...
],
"totalOffersCount":{number},
"fromOffer":{number},
"toOffer":{number}
}
}
{
"offersStats":
{
"offerStats":
[
{
"clicks":{number},
"spending":{number}
},
...
],
"totalOffersCount":{number},
"fromOffer":{number},
"toOffer":{number}
}
}
Parameter
for XML
format
Parameter
for JSON
format
offersstats
offersStats
Type
Value
List of statistical data.
Developer's guide
134
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
Parameters nested in offers-stats/offersStats
totalofferscount
totalOffers Number
Count
Total number of product offers in the report.
from-offer
fromOffer
Number
The index number within search results for the first offer on the page that
is output in the response.
to-offer
toOffer
Number
The index number within search results for the last offer on the page that
is output in the response.
offer-stats offerStats
Statistics for a specific product offer.
Parameters nested in offer-stats/offerStats
offer-name
offerName
String
clicks
clicks
Number
Number of clicks on the product offer.
spending
spending
Number
Expenditures on clicks on the product offer, in Yandex units.
offer-id
offerId
Number
Partner API.
feed-id
feedId
Number
Partner API.
Error descriptions
Restrictions
•
Note:
Examples
XML
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/10002/stats/offers.xml?
fromDate=22-11-2011&toDate=28-11-2011
Sample response:
Developer's guide
135
<response>
<offers-stats total-offers-count="21739" from-offer="1" to-offer="10">
<offer-stats clicks="474" spending="52.86" feed-id="323204" offerid="002000000001135">
<offer-name>PocketBook IQ 701, Dark Blue</offer-name>
</offer-stats>
<offer-name>Nokia N9 16GB, Black</offer-name>
</offer-stats>
<offer-name>PocketBook IQ 701, Glossy White</offer-name>
</offer-stats>
<offer-name>Samsung GT-S5830 Galaxy Ace, Black</offer-name>
</offer-stats>
<offer-name>Samsung GT-i9100 Galaxy S II, Noble Black</offer-name>
</offer-stats>
<offer-name>Samsung GT-N7000 Galaxy Note</offer-name>
</offer-stats>
<offer-name>Samsung GT-i9001 Galaxy S Plus 8GB, Metallic Black</offer-name>
</offer-stats>
<offer-name>Tamara Globa "Complete horoscope for 2012"</offer-name>
</offer-stats>
<offer-name>Santa Claus costume, size 48-54</offer-name>
</offer-stats>
<offer-name>LG P698 Optimus Net, Black</offer-name>
</offer-stats>
</offers-stats>
</response>
Sample response prior to version 2.0 of the Yandex.Market Partner API
<response>
<offers-stats total-offers-count="21739" from-offer="1" to-offer="10">
<offer-stats clicks="474" spending="52.86">
<offer-name>PocketBook IQ 701, Dark Blue</offer-name>
</offer-stats>
<offer-name>Nokia N9 16GB, Black</offer-name>
</offer-stats>
<offer-name>PocketBook IQ 701, Glossy White</offer-name>
</offer-stats>
<offer-name>Samsung GT-S5830 Galaxy Ace, Black</offer-name>
</offer-stats>
<offer-name>Samsung GT-i9100 Galaxy S II, Noble Black</offer-name>
</offer-stats>
<offer-name>Samsung GT-N7000 Galaxy Note</offer-name>
</offer-stats>
<offer-name>Samsung GT-i9001 Galaxy S Plus 8GB, Metallic Black</offer-name>
</offer-stats>
Developer's guide
136
<offer-name>Tamara Globa "Complete horoscope for 2012"</offer-name>
</offer-stats>
<offer-name>Santa Claus costume, size 48-54</offer-name>
</offer-stats>
<offer-name>LG P698 Optimus Net, Black</offer-name>
</offer-stats>
</offers-stats>
</response>
JSON
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/10002/stats/offers.json?
fromDate=22-11-2011&toDate=28-11-2011
Sample response:
{"offersStats":{"offerStats":[
{"offerName":"PocketBook IQ 701, Dark Blue","clicks":474,"spending":52.86, feedId":
323204,
"offerId": "002000000001135"},
{"offerName":"Nokia N9 16GB, Black","clicks":204,"spending":174.04, "feedId": 323204,
"offerId": "002000000009984"},
{"offerName":"PocketBook IQ 701, Glossy White","clicks":203,"spending":20.30,
"feedId": 323204, "offerId": "002000000002944"},
{"offerName":"Samsung GT-S5830 Galaxy Ace, Black","clicks":194,"spending":161.02,
"feedId": 323204, "offerId": "002000000004735"},
{"offerName":"Samsung GT-i9100 Galaxy S II, Noble Black","clicks":172,"spending":
213.56, "feedId": 323204, "offerId": "002000000001136"},
{"offerName":"Samsung GT-N7000 Galaxy Note","clicks":165,"spending":81.67, "feedId":
323204, "offerId": "002000000007564"},
{"offerName":"Samsung GT-i9001 Galaxy S Plus 8GB, Metallic Black","clicks":
160,"spending":78.37, "feedId": 323204, "offerId": "002000000001607"},
{"offerName":"Tamara Globa \"Complete horoscope for 2012\"","clicks":96,"spending":
10.17, "feedId": 323204, "offerId": "002000000000243"},
{"offerName":"Costume \"Santa Claus\", size 48-54","clicks":92,"spending":18.40,
"feedId": 323204, "offerId": "002000000006157"},
{"offerName":"LG P698 Optimus Net, Black","clicks":88,"spending":16.26, "feedId":
323204,
"offerId": "002000000002920"}
],"totalOffersCount":21739,"fromOffer":1,"toOffer":10}
}
Sample response prior to version 2.0 of the Yandex.Market Partner API
{"offersStats":{"offerStats":[
{"offerName":"PocketBook IQ 701, Dark Blue","clicks":474,"spending":52.86},
{"offerName":"Nokia N9 16GB, Black","clicks":204,"spending":174.04},
{"offerName":"PocketBook IQ 701, Glossy White","clicks":203,"spending":20.30},
{"offerName":"Samsung GT-S5830 Galaxy Ace, Black","clicks":194,"spending":161.02},
{"offerName":"Samsung GT-i9100 Galaxy S II, Noble Black","clicks":172,"spending":
213.56},
{"offerName":"Samsung GT-N7000 Galaxy Note","clicks":165,"spending":81.67},
{"offerName":"Samsung GT-i9001 Galaxy S Plus 8GB, Metallic Black","clicks":
160,"spending":78.37},
{"offerName":"Tamara Globa \"Complete horoscope for 2012\"","clicks":96,"spending":
10.17},
{"offerName":"Costume \"Santa Claus\", size 48-54","clicks":92,"spending":18.40},
{"offerName":"LG P698 Optimus Net, Black","clicks":88,"spending":16.26}
],"totalOffersCount":21739,"fromOffer":1,"toOffer":10}
}
Developer's guide
137
Geobase
Use the geobase methods to get information about regions.
Method
Short description
Restrictions
GET regions
Returns information about regions that The number of requests per day depends
meet the search conditions.
on the total number of regions.
GET regions/{regionId}
Returns information about the specified The number of requests per day depends
region.
GET /regions/{regionId}/children
Returns information about child regions The number of requests per day depends
for the specified parent region.
The methods listed have a group resource limit. The limit is applied to the total number of regions that information
is requested for using these methods (no more than 100,000 regions). The number of requests to each resource
that can be performed during a day is calculated depending on the number of regions.
Search for region
Description
GET /regions
Returns information about a region that meets the search conditions specified in the request.
If multiple regions are found that meet the search conditions, it returns information on each found region (but
no more than ten regions) in order to determine the desired region by parent regions.
Note:
Resource URL:
https://api.partner.market.yandex.ru/v2/regions.[format]?name={regionName}
Input data
Parameter
Type
Value
String
Name of the region (for example, "Saint Petersburg").
Mandatory
name
Output data
Developer's guide
138
XML
<regions>
...
</parent>
</region>
...
</regions>
JSON
{
"regions":
[
{
"id":{number},
"name":"{string}",
"type":"{string}",
"parent":
{
"id":{number},
"name":"{string}",
"type":"{string}",
"parent":
{
...
}
}
},
...
]
}
Parameter
for XML
format
Parameter
for JSON
format
regions
regions
Type
Value
List of regions that meet the search conditions.
Parameters nested in regions
region
Description of the region.
id
id
Number
ID of the region.
name
name
String
Name of the region.
type
type
String
•
REGION — Region.
•
•
•
•
•
CITY — City.
•
•
•
•
Developer's guide
139
Parameter
for XML
format
Parameter
for JSON
format
parent
parent
Type
Value
"Parent" region.
id
id
Number
name
name
String
type
type
String
parent
parent
•
REGION — Region.
•
•
•
•
•
CITY — City.
•
•
•
•
Error descriptions
Restrictions
For the methods GET /regions, GET /regions/{regionId} and GET /regions/{regionId}/children there is a group
resource limit. The limit is applied to the total number of regions that information is requested for using these
methods (no more than 100,000 regions).
The number of requests to a resource that can be performed during a day depends on the total number of regions.
Examples
XML
Sample request:
GET https://api.partner.market.yandex.ru/v2/regions.xml?name=Cambridge
Sample response:
<response>
<regions>
<region id="11380" name="Ivanovka" type="CITY">
<parent id="100295" name="Ivanovskiy region" type="REPUBLIC_AREA">
<parent id="11375" name="Amurskaya region" type="REPUBLIC">
<parent id="73" name="Far East" type="COUNTRY_DISTRICT">
</parent>
</parent>
</parent>
</region>
<region id="28630" name="Ivanovka" type="VILLAGE">
Developer's guide
140
<parent id="24533" name="Novoarkhangelskiy region" type="REPUBLIC_AREA">
<parent id="20548" name="Kirovogradskaya region" type="REPUBLIC">
<parent id="20527" name="Center" type="REGION">
<parent id="187" name="Ukraine" type="COUNTRY"/>
</parent>
</parent>
</parent>
</region>
</regions>
</response>
JSON
Sample request:
GET https://api.partner.market.yandex.ru/v2/regions.json?name=Cambridge
Sample response:
{"regions":[
{"id":11380, "name":"Ivanovka", "type":"CITY", "parent":
{"id":100295, "name":"Ivanovskiy region", "type":"REPUBLIC_AREA", "parent":
{"id":11375, "name":"Amurskaya region", "type":"REPUBLIC", "parent":
{"id":73, "name":"Far East", "type":"COUNTRY_DISTRICT", "parent":
{"id":225, "name":"Russia", "type":"COUNTRY"}}}}},
{"id":28630, "name":"Ivanovka", "type":"VILLAGE", "parent":
{"id":24533, "name":"Novoarkhangelskiy region", "type":"REPUBLIC_AREA", "parent":
{"id":20548, "name":"Kirovogradskaya region", "type":"REPUBLIC", "parent":
{"id":20527, "name":"Center", "type":"REGION", "parent":
{"id":187, "name":"Ukraine", "type":"COUNTRY"}}}}}
]}
Region information
Description
GET /regions/{regionId}
Returns information about the region specified in the request.
Note:
Resource URL:
https://api.partner.market.yandex.ru/v2/regions/{regionId}.[format]
Input data
Parameter
Type
Value
Number
ID of the region.
Mandatory
regionId
Output data
Developer's guide
141
XML
<regions>
...
</parent>
</region>
</regions>
JSON
{
"regions":
[
{
"id":{number},
"name":"{string}",
"type":"{string}",
"parent":
{
"id":{number},
"name":"{string}",
"type":"{string}",
"parent":
{
...
}
}
}
]
}
Parameter
for XML
format
Parameter
for JSON
format
regions
regions
Type
Value
The region specified in the request.
region
id
id
Number
ID of the region.
name
name
String
Name of the region.
type
type
String
parent
parent
•
REGION — Region.
•
•
•
•
•
CITY — City.
•
•
•
•
"Parent" region.
Developer's guide
142
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
id
id
Number
name
name
String
type
type
String
parent
parent
•
REGION — Region.
•
•
•
•
•
CITY — City.
•
•
•
•
Error descriptions
Description
Explanation
Possible solution
Error 404 Not Found
Region not found:
'regionId'
Restrictions
methods (no more than 100000 regions).
Examples
XML
Sample request:
GET https://api.partner.market.yandex.ru/v2/regions/213.xml
Sample response:
Developer's guide
143
<response>
<regions>
<region id="213" name="Moscow" type="CITY">
<parent id="1" name="Moscow and Moscow region" type="REPUBLIC">
<parent id="3" name="Center" type="COUNTRY_DISTRICT">
</parent>
</parent>
</region>
</regions>
</response>
JSON
Sample request:
GET https://api.partner.market.yandex.ru/v2/regions/213.json
Sample response:
{"regions":[
{"id":213, "name":"Moscow", "type":"CITY", "parent":
{"id":1, "name":"Moscow and Moscow region", "type":"REPUBLIC", "parent":
{"id":3, "name":"Center", "type":"COUNTRY_DISTRICT", "parent":
{"id":225, "name":"Russia", "type":"COUNTRY"}}}}
]}
Information about child regions
Description
GET /regions/{regionId}/children
Returns information about regions that are “children” of the region whose ID is set in the request.
Note:
Resource URL:
https://api.partner.market.yandex.ru/v2/regions/{regionId}/children.[format]?
[pageSize={pageSize}]&[page={page}]
Input data
Parameter
Type
Value
Number
ID of the region.
pageSize
Number
The number of entries on a page. Default value: 10 entries. Maximum allowed value: 100.
page
Number
Page number in results. By default, the first page is output. Maximum allowed value: 100.
Mandatory
regionId
Optional
Developer's guide
144
Output data
XML
<regions>
...
</parent>
<children>
<region id="{number}" name="{string}" type="{string}"/>
...
</children>
</region>
</regions>
JSON
{
"regions":
{
"id":{number},
"name":"{string}",
"type":"{string}",
"parent":
{
"id":{number},
"name":"{string}",
"type":"{string}"
"parent":
{
...
}
},
"children":
[
{
"id":{number},
"name":"{string}",
"type":"{string}"
},
...
]
},
"pager":
{
"total":{number},
"from":{number},
"to":{number},
"currentPage":{number},
"pageSize":{number}
}
}
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
regions
regions
Information about regions.
pager
pager
Developer's guide
145
Parameter
for XML
format
Parameter
for JSON
format
Type
region
Value
id
id
Number
ID of the region.
name
name
String
Name of the region.
type
type
String
parent
parent
•
REGION — Region.
•
•
•
•
•
CITY — City.
•
•
•
•
Parent region.
Parent regions are specified up to the country level.
children
children
Child regions.
id
id
Number
ID of the parent region.
name
name
String
Name of the parent region.
type
type
String
parent
parent
•
REGION — Region.
•
•
•
•
•
CITY — City.
•
•
•
•
Recursively nested element for specifying higher-level parent regions.
Parameters nested in children
region
Description of a child region
id
id
Number
ID of the child region
name
name
String
Name of the child region
Developer's guide
146
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
type
type
String
•
REGION — Region.
•
•
•
•
•
CITY — City.
•
•
•
•
total
total
Number
Number of entries found. The value may increase as the page number
increases. The final number of found entries has been reached when
the value of the total parameter matches the value of the to parameter.
If nothing was found, the parameter value is 0.
from
from
Number
The sequential number of the first entry on the page in the overall search
results. If nothing was found, the parameter value is 0.
to
to
Number
The sequential number of the last entry on the page in the overall search
currentpage
currentPage Number
The sequential number of the current page in results. If nothing was found,
the parameter value is 0.
Number
The number of pages with search results. The value may increase as the
page number increases. The final number of pages has been reached when
the value of the pages-count parameter matches the value of the
current-page parameter.
page-size
pageSize
Number
The number of entries on the current page. If nothing was found,
Error descriptions
Description
Explanation
Possible solution
Page number must
be positive: 'page'
The page number must be a positive Check whether the correct page number is being
integer.
passed.
Page number is too big: The specified page number is too
'pageNum'. Max page
large.
number is 'maxPageNum'
Check whether the correct page number is being
passed.
Page size must
The page size must be a positive
be positive: 'pageSize' integer.
Check whether the correct page size is being
passed.
The specified page size is too large. Check whether the correct page size is being
passed.
Developer's guide
147
Description
Explanation
Possible solution
Error 404 Not Found
Region not found:
'regionId'
Restrictions
methods (no more than 100000 regions).
Examples
XML
Sample request:
GET https://api.partner.market.yandex.ru/v2/regions/1/children.xml?pageSize=20&page=2
Sample response:
<response>
<regions>
<region id="1" name="Moscow and Moscow region" type="REPUBLIC">
</parent>
<children>
<region id="98589" name="Kolomenskiy region" type="REPUBLIC_AREA"/>
<region id="98582" name="Dmitrovskiy region" type="REPUBLIC_AREA"/>
<region id="98580" name="Volokolamskiy region" type="REPUBLIC_AREA"/>
<region id="98581" name="Voskresenskiy region" type="REPUBLIC_AREA"/>
<region id="98601" name="Orehovo-Zuevskiy region" type="REPUBLIC_AREA"/>
<region id="98600" name="Ozerskiy region" type="REPUBLIC_AREA"/>
<region id="98603" name="Podolskiy region" type="REPUBLIC_AREA"/>
<region id="98602" name="Pavlovo-Posadskiy region" type="REPUBLIC_AREA"/>
<region id="98605" name="Ramenskiy region" type="REPUBLIC_AREA"/>
<region id="98604" name="Pushkinskiy region" type="REPUBLIC_AREA"/>
<region id="98607" name="Stupinskiy region" type="REPUBLIC_AREA"/>
<region id="98606" name="Ruzskiy region" type="REPUBLIC_AREA"/>
<region id="98593" name="Luhovitskiy region" type="REPUBLIC_AREA"/>
<region id="98592" name="Lotoshinskiy region" type="REPUBLIC_AREA"/>
<region id="98595" name="Mozhaiskiy region" type="REPUBLIC_AREA"/>
<region id="98594" name="Lyuberetskiy region" type="REPUBLIC_AREA"/>
<region id="98597" name="Naro-Fiminskiy region" type="REPUBLIC_AREA"/>
<region id="98596" name="Mytishinskiy region" type="REPUBLIC_AREA"/>
<region id="98599" name="Odintsovskiy region" type="REPUBLIC_AREA"/>
<region id="98598" name="Noginskiy region" type="REPUBLIC_AREA"/>
</children>
</region>
</regions>
</response>
JSON
Sample request:
GET https://api.partner.market.yandex.ru/v2/regions/1/children.json?pageSize=20&page=2
Sample response:
Developer's guide
148
{
"regions":
{
"id":1, "name":"Moscow and Moscow region", "type":"REPUBLIC", "parent":
{
"id":3, "name":"Center", "type":"COUNTRY_DISTRICT", "parent":
{
"id":225, "name":"Russia", "type":"COUNTRY"
}
},
"children":
[
{"id":98589, "name":"Kolomenskiy region", "type":"REPUBLIC_AREA"},
{"id":98582, "name":"Dmitrovskiy region", "type":"REPUBLIC_AREA"},
{"id":98580, "name":"Volokolamskiy region", "type":"REPUBLIC_AREA"},
{"id":98581, "name":"Voskresenskiy region", "type":"REPUBLIC_AREA"},
{"id":98601, "name":"Orehovo-Zuevskiy region", "type":"REPUBLIC_AREA"},
{"id":98600, "name":"Ozerskiy region", "type":"REPUBLIC_AREA"},
{"id":98603, "name":"Podolskiy region", "type":"REPUBLIC_AREA"},
{"id":98602, "name":"Pavlovo-Posadskiy region", "type":"REPUBLIC_AREA"},
{"id":98605, "name":"Ramenskiy region", "type":"REPUBLIC_AREA"},
{"id":98604, "name":"Pushkinskiy region", "type":"REPUBLIC_AREA"},
{"id":98607, "name":"Stupinskiy region", "type":"REPUBLIC_AREA"},
{"id":98606, "name":"Ruzskiy region", "type":"REPUBLIC_AREA"},
{"id":98593, "name":"Luhovitskiy region", "type":"REPUBLIC_AREA"},
{"id":98592, "name":"Lotoshinskiy region", "type":"REPUBLIC_AREA"},
{"id":98595, "name":"Mozhaiskiy region", "type":"REPUBLIC_AREA"},
{"id":98594, "name":"Lyuberetskiy region", "type":"REPUBLIC_AREA"},
{"id":98597, "name":"Naro-Fiminskiy region", "type":"REPUBLIC_AREA"},
{"id":98596, "name":"Mytishinskiy region", "type":"REPUBLIC_AREA"},
{"id":98599, "name":"Odintsovskiy region", "type":"REPUBLIC_AREA"},
{"id":98598, "name":"Noginskiy region", "type":"REPUBLIC_AREA"}
]
},
"pager":
{
"total":75, "from":21, "to":40, "currentPage":2, "pagesCount":4, "pageSize":20
}
}
Developer's guide
149
Market Ordering program
These methods are used for the Market ordering program and provide a way for an ecommerce merchant
and Yandex.Market to exchange data about an order. Requests may be sent from Yandex.Market to the merchant,
and from the merchant to Yandex.Market.
Methods that Yandex.Market uses for making requests to a
merchant:
Note:
In order for Yandex.Market to be able to make requests to a merchant, the merchant must support these methods
in its implementation of the API.
Method
Short description
POST /cart
Requests information from the merchant about products in a customer's
cart.
POST /order/accept
Passes an order to the merchant and requests confirmation of order
acceptance by the merchant.
POST /order/status
Notifies the merchant about changes to the order status.
Methods that the merchant uses for making requests
to Yandex.Market:
Method
Short description
PUT /campaigns/{campaignId}/orders/
{orderId}/status
Changes the status of an order.
PUT /campaigns/{campaignId}/orders/
{orderId}/delivery
Changes the conditions for order delivery.
GET /campaigns/{campaignId}/orders/
{orderId}
Requests information about a specific order that was created for the
merchant in the Yandex.Market interface.
Requests information about orders that were created for the merchant
in the Yandex.Market interface.
Note:
All parameters passed by the merchant are mandatory, unless specified otherwise.
Request for product information
Developer's guide
150
Attention!
This request is made by Yandex.Market.
Description
POST /cart
Passes the customer's shopping cart to the merchant and requests current information about the products in the
cart:
•
Price and availability.
•
Delivery options available for these products and this delivery region.
•
Payment methods available.
Resource URL:
https://<request URL>/cart
Response timeout: 5.5 seconds.
Data passed to the merchant
Data structure in the request body:
XML
<cart currency="{string}">
<items>
<item feed-id="{number}" offer-id="{string}" feed-category-id="{string}" offername="{string}" count="{number}"/>
...
</items>
<delivery>
...
</parent>
</region>
<address country="{string}" postcode="{string}" city="{string}" subway="{string}"
street="{string}" house="{string}" block="{string}" floor="{string}"/>
</delivery>
</cart>
JSON
{
"cart":
{
"items":
[
{
"feedId":{number},
"count":{number},
"feedCategoryId":"{string}"
},
...
],
"delivery":
{
"region":
{
"id":{number},
"name":"{string}",
Developer's guide
151
"type":"{string}",
"parent":
{
"id":{number},
"name":"{string}",
"type":"{string}",
"parent":
{
...
}
}
},
"address":
{
"country":"{string}",
"postcode":"{string}",
"city":"{string}",
"subway":"{string}",
"street":"{string}",
"house":"{string}",
"block":"{string}",
"floor":"{string}"
}
}
}
}
Parameter
for XML
format
Parameter
for JSON
format
cart
cart
Type
Value
Shopping cart.
Parameters nested in cart
currency
currency
String
Currency used for the product prices in the order. Possible values:
•
RUR — Russian ruble
•
UAH — Ukrainian hrivna
items
items
Products in the cart.
delivery
delivery
Information for determining delivery options.
Parameters nested in items(XML)
item
Information about an item in the cart.
Parameters nested in item / items(JSON)
feed-id
feedId
Number
ID of the price list that contains the product.
offer-id
offerId
String
ID of the product from the price list.
feedfeedСategor String
category-id yId
ID of the product category from the price list.
offer-name
offerName
String
Name of the product.
count
count
Number
Number of items in the cart.
Parameters nested in delivery
region
region
Delivery region.
address
address
Delivery address. Specified if the address is already known.
id
id
Number
ID of the region.
name
name
String
Name of the region.
Developer's guide
152
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
type
type
String
parent
parent
•
REGION — Region.
•
•
•
•
•
CITY — City.
•
•
•
•
Parent region. Parent regions are specified up to the country level.
id
id
Number
name
name
String
type
type
String
parent
parent
•
REGION — Region.
•
•
•
•
•
CITY — City.
•
•
•
•
Parameters nested in address
Mandatory
country
country
String
Country.
city
city
String
City or town.
house
house
String
Number of the house or building.
postcode
postcode
String
Postal code. Specified for the POST (mail) delivery method.
street
street
String
Street.
subway
subway
String
Subway (underground) station.
block
block
String
Unit or building number.
floor
floor
String
Floor.
Optional
Developer's guide
153
Response data from the merchant
In response, the merchant must pass current data for the cart of products and the specified delivery region.
Note:
If the cart contains items that cannot be delivered to the specified region or address, the response for these items
(the item parameter) must have the value false for the delivery attribute, while delivery options should
be calculated for the rest of the cart.
Structure of response data:
XML
<cart>
<items>
<item feed-id="{number}" offer-id="{string}" price="{number}" count="{number}"
delivery="{boolean}"/>
...
</items>
<delivery-options>
<delivery id="{string}" service-name="{string}" type="{string}"
price="{number}">
<dates from-date="{string}" to-date="{string}"/>
<outlets>
<outlet id="{number}"/>
...
</outlets>
</delivery>
...
</delivery-options>
<payment-methods>
<payment-method>{string}</payment-method>
...
</payment-methods>
</cart>
JSON
{
"cart":
{
"items":
[
{
"feedId":{number},
"price":{number},
"count":{number},
"delivery":{boolean}
},
...
],
"deliveryOptions":
[
{
"id":"{string}",
"type":"{string}",
"serviceName":"{string}",
"price":{number},
"dates":
{
"fromDate":"{string}",
"toDate":"{string}"
},
"outlets":
[
{
"id":{number}
Developer's guide
154
},
...
]
},
...
],
"paymentMethods":
[
"{string}",
...
]
}
}
Parameter
for XML
format
Parameter
for JSON
format
cart
cart
Type
Value
Shopping cart.
Parameters nested in cart
items
items
Products in the cart.
paymentmethods
paymentMeth
ods
Methods of payment that are available for the cart.
deliveryoptions
deliveryOpt
ions
Delivery options that are available for the cart.
item
Information about an item in the cart.
feed-id
feedId
Number
offer-id
offerId
String
price
price
Number
Up-to-date product price in the cart's currency. A dot is used as the
decimal separator.
This parameter is not required if the count parameter is equal to 0.
count
count
Number
Quantity of the product that is available for ordering. The exact quantity
does not have to be specified, but it is important to specify a quantity that
is guaranteed to be available for ordering. If the item is out of stock,
specify 0.
delivery
delivery
Logical
Indicates whether the item can be delivered to the region or address
specified in the request. Possible values:
•
false — This item cannot be delivered to the specified region
or address.
•
true — Default value. The item can be delivered to the specified
region or address.
Parameters nested in payment-methods / paymentMethods
paymentmethod
String
How the order will be paid for. Possible values for the PREPAID payment
type:
•
SHOP_PREPAID — Prepayment directly to the merchant.
Developer's guide
155
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
Possible values for the POSTPAID payment type:
•
CASH_ON_DELIVERY — Cash payment when the order
is received.
•
CARD_ON_DELIVERY — Payment by bank card when the order
is received.
Parameters nested in delivery-options
delivery
Information about delivery.
Parameters nested in delivery / deliveryOptions
id
id
String
ID of the delivery option; assigned by the merchant.
Optional attribute. If an ID is specified, it will be passed back to the
merchant in the POST /order/accept request.
The maximum length is 50 characters.
type
type
String
How the order will be delivered. Possible values:
•
DELIVERY — Courier delivery.
•
PICKUP — Pick-up by the customer.
•
POST — Mail.
servicename
serviceName String
Name of the delivery service.
price
price
Cost of delivery in the order's currency. A dot is used as the decimal
separator.
dates
dates
Range of dates for delivery.
outlets
outlets
Pick-up points. Specified for the PICKUP delivery method.
Number
Parameters nested in dates
from-date
fromDate
String
Soonest possible delivery date, in the format DD-MM-YYYY. This date
must be no earlier than the current date and no later than 92 calendar days
from the current date.
to-date
toDate
String
Latest delivery date, in the format DD-MM-YYYY. The date must be no
earlier than the date specified in the from-date parameter and no later
than 92 calendar days from the current date.
Optional parameter. If the to-date parameter is omitted, the only
possible delivery date is assumed to be the date specified in the fromdate parameter.
Parameters nested in outlets(XML)
outlet
Information about a pick-up point.
Parameters nested in outlet / outlets(JSON)
id
id
Number
ID of a pick-up point set in the partner interface.
Note:
If a non-existing ID is specified (it doesn't match any of the IDs set in
the partner interface), this pick-up point will not be shown to the customer
when making an order.
Developer's guide
156
Error descriptions
The merchant can return the following response statuses:
Description
Explanation
Error 500
Error
Internal
If the merchant believes a request from Yandex.Market is invalid, the merchant
should return the response status 400 with a description of the reason for the error
in the response body. Such responses will be analyzed by Yandex.Market to find
issues or bugs in the API.
Server If a technical error occurs on the merchant side, it should return the response status
500. Merchants with a large quantity of these responses may be excluded from
the Purchase on Market program.
Examples
XML
Sample request from Yandex.Market:
POST /cart HTTP/1.1
<cart currency="RUR">
<items>
<item feed-id="12345" offer-id="4609283881" feed-category-id="35" offername="Electric teapot 100W" count="1"/>
<item feed-id="12345" offer-id="4607632101" feed-category-id="41" offername="Toaster" count="1"/>
</items>
<delivery>
</parent>
</parent>
</region>
<address country="Russia" postcode="119313" city="Moscow" subway="Prospekt
Vernadskovo" street="Leninskiy Prospekt" house="90" floor="6"/>
</delivery>
</cart>
Sample merchant response:
HTTP/1.1 200 OK
<cart>
<items>
<item feed-id="12345" offer-id="4609283881" price="1500" count="1"
delivery="true"/>
<item feed-id="12345" offer-id="4607632101" price="2200" count="1"
delivery="false"/>
</items>
<delivery-options>
<delivery service-name="SPSR" type="PICKUP" price="0">
<dates from-date="02-02-2013" to-date="05-02-2013"/>
<outlets>
<outlet id="9"/>
<outlet id="10"/>
<outlet id="11"/>
<outlet id="12"/>
</outlets>
</delivery>
<delivery service-name="In-house delivery service" type="DELIVERY" price="350">
<dates from-date="03-02-2013"/>
</delivery>
</delivery-options>
<payment-methods>
<payment-method>CASH_ON_DELIVERY</payment-method>
<payment-method>CARD_ON_DELIVERY</payment-method>
</payment-methods>
</cart>
Developer's guide
157
JSON
POST /cart HTTP/1.1
{
"cart":
{
"currency":"RUR",
"items":
[
{"feedId":12345, "offerId":"4609283881", "offerName":"Electric teapot 100W", "count":
1, "feedCategoryId":"35"},
{"feedId":12346, "offerId":"4607632101", "offerName":"Toaster", "count":1,
"feedCategoryId":"35"}
],
"delivery":
{"region":
{"id":225, "name":"Russia", "type":"COUNTRY"}
}
}
},
"address":{"country":"Russia", "postcode":"119313", "city":"Moscow",
"subway":"Prospekt Vernadskovo", "street":"Leninskiy Prospekt", "house":"90",
"floor":"6"}
}
}
}
HTTP/1.1 200 OK
{
"cart":
{
"items":
[
{"feedId":12345, "offerId":"4609283881", "price":1500, "count":1, "delivery":true},
{"feedId":12346, "offerId":"4607632101", "price":2200, "count":1, "delivery":false}
],
"deliveryOptions":
[
{"type":"PICKUP", "serviceName":"SPSR", "price":0, "dates":
{"fromDate":"02-02-2013", "toDate":"05-02-2013"}, "outlets":[{"id": 9}, {"id": 10},
{"id": 11}, {"id": 12}]},
{"type":"DELIVERY", "serviceName":"In-house delivery service", "price":350, "dates":
{"fromDate":"03-02-2013"}}
],
"paymentMethods":["CASH_ON_DELIVERY", "CARD_ON_DELIVERY"]
}
}
Passing an order and request to accept order
Attention!
Description
POST /order/accept
Developer's guide
158
Passes a newly created order to the merchant and requests either confirmation of order acceptance, or rejection
of the order. The order is passed without customer information. The customer's personal information becomes
available only after order acceptance has been confirmed.
Note:
The request is made by Yandex.Market and may be called more than once for an order that has already been
accepted by the merchant. This may happen if the merchant received the Yandex.Market POST /order/
accept request and confirmed order acceptance, but due to some technical issue the merchant's response
was not registered by Yandex.Market. Since it is unknown whether the order acceptance request reached
the merchant or not, Yandex.Market may repeat this request. The merchant is expected to respond by repeating
the confirmation of the order acceptance.
Resource URL:
https://<request URL>/order/accept
Response timeout: 10 seconds.
XML
<order id="{number}" currency="{string}" payment-type="{string}" paymentmethod="{string}" fake="{boolean}">
<items>
<item feed-id="{number}" offer-id="{string}" feed-category-id="{string}" offername="{string}" price="{number}" count="{number}"/>
...
</items>
<notes>{string}</notes>
<delivery id="{string}" type="{string}" price="{number}" service-name="{string}"
outlet-id="{number}">
...
</parent>
</region>
street="{string}" house="{string}" block="{string}" floor="{string}"/>
</delivery>
</order>
JSON
{
"order":
{
"id":{number},
"paymentType":"{string}",
"paymentMethod":"{string}",
"fake":{boolean},
"items":
[
{
"feedId":{number},
"feedCategoryId":"{string}",
"price":{number},
"count":{number}
},
...
],
"notes":"{string}",
Developer's guide
159
"delivery":
{
"id":"{string}",
"type":"{string}",
"price":{number},
"outletId":{number},
"dates":
{
"toDate":"{string}"
},
"region":
{
"id":{number},
"name":"{string}",
"type":"{string}",
"parent":
{
"id":{number},
"name":"{string}",
"type":"{string}",
"parent":
{
...
}
}
},
"address":
{
"city":"{string}",
"house":"{string}",
"block":"{string}",
"floor":"{string}"
},
}
}
}
Parameter
for XML
format
Parameter
for JSON
format
order
order
Type
Value
Order.
Parameters nested in order
id
id
Number
Campaign ID.
currency
currency
String
paymenttype
paymentType String
•
•
Type of payment for the order. Possible values:
•
PREPAID — Prepayment directly to the merchant.
•
POSTPAID — Payment on receipt.
Optional parameter.
paymentmethod
paymentMeth String
od
type:
•
Developer's guide
160
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
•
is received.
•
is received.
Optional parameter.
fake
fake
items
items
notes
notes
delivery
delivery
Logical
Indicates a test order. Possible values:
•
true — Test order.
•
false — Real order that should be fulfilled.
Order contents.
String
Comments on the order.
item
Information about an ordered product.
feed-id
feedId
Number
offer-id
offerId
String
category-id yId
offer-name
offerName
String
price
price
Number
Product price in the order's currency. A dot is used as the decimal
separator.
count
count
Number
Number of products ordered.
String
id
id
Only set if the merchant passed this ID in the response to the POST /
cart request.
type
type
String
•
•
•
POST — Mail.
servicename
serviceName String
price
price
separator.
dates
dates
region
region
Delivery region.
address
address
Delivery address. Specified for the delivery methods DELIVERY
(courier) and POST (mail).
Number
Developer's guide
161
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
outlet-id
outletId
Number
ID of the pick-up point the customer selected for receiving the order.
Specified for the PICKUP delivery method.
from-date
fromDate
String
Soonest delivery date, in the format DD-MM-YYYY.
to-date
toDate
String
Latest delivery date, in the format DD-MM-YYYY.
id
id
Number
ID of the region.
name
name
String
Name of the region.
type
type
String
parent
parent
•
REGION — Region.
•
•
•
•
•
CITY — City.
•
•
•
•
id
id
Number
name
name
String
type
type
String
parent
parent
•
REGION — Region.
•
•
•
•
•
CITY — City.
•
•
•
•
Mandatory
country
country
String
Country.
city
city
String
City or town.
house
house
String
Developer's guide
162
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
postcode
postcode
String
street
street
String
Street.
subway
subway
String
block
block
String
floor
floor
String
Floor.
Optional
Response data from the merchant
Structure of response data:
XML
<order accepted="{boolean}" id="{string}" reason="{string}"/>
JSON
{
"order":
{/* hide:order */
"accepted":{boolean},
"id":"{string}",
"reason":"string"
}
}
Parameter
for XML
format
Parameter
for JSON
format
order
order
Type
Value
Order.
accepted
id
accepted
id
Logical
String
Order flag. Possible values:
•
true — Order has been accepted by the merchant.
•
false — Order was declined by the merchant.
Order ID assigned by the merchant. Specified if the order was accepted.
In the Yandex.Market interface, the user will see two IDs — the one
assigned by Yandex.Market, and the one assigned by the merchant.
The maximum length of the ID is 50 characters.
reason
reason
String
Reason the order was declined. Specified if the order was declined (the
false value for the accepted attribute). Possible values:
•
OUT_OF_DATE — The information about products and/or delivery
options shown in the order is out of date.
Developer's guide
163
Error descriptions
Description
Explanation
Error 500
Error
Internal
Examples
XML
POST /order/accept HTTP/1.1
<order id="12345" currency="RUR" payment-type="POSTPAID" paymentmethod="CASH_ON_DELIVERY" fake="false">
<items>
<item feed-id="12345" offer-id="4609283881" feed-category-id="35" offername="Electric teapot 100W" price="1500" count="1"/>
<item feed-id="12345" offer-id="4607632101" feed-category-id="41" offername="Toaster" price="2200" count="1"/>
</items>
<notes>Deliver asap, please!</notes>
<delivery type="DELIVERY" price="350" service-name="SPSR">
</parent>
</parent>
</region>
Vernadskovo" street="Leninskiy Prospekt" house="90" floor="6"/>
</delivery>
</order>
HTTP/1.1 200 OK
<order id="12345" accepted="true"/>
JSON
POST /order/accept HTTP/1.1
{
"order":{"id":12345, "currency":"RUR", "paymentType":"POSTPAID",
"paymentMethod":"CASH_ON_DELIVERY", "fake":false, "items":
[
{"feedId":12345, "offerId":"4609283881", "feedCategoryId":"35",
"offerName":"Electric teapot 100W", "price":1500, "count":1},
"offerName":"Toaster",
"price":2200, "count":1}
],
"notes":"Deliver asap, please!",
"delivery":{"type":"DELIVERY", "price":350, "serviceName":"SPSR", "dates":
{"fromDate":"03-02-2013", "toDate":"05-02-2013"}, "region":
Developer's guide
164
}
}
},
"floor":"6"}
}
}
}
HTTP/1.1 200 OK
{
"order":{"id":"12345", "accepted":true}
}
Notification of changes to the order status
Attention!
Description
POST order/status
Notifies the merchant about changes to the order status.
Note:
This request is made by Yandex.Market. The merchant may get this request for an unknown order or a rejected
order with the CANCELLED status. This may happen if the merchant received the Yandex.Market POST /
order/accept request and confirmed order acceptance, but due to some technical issue the merchant's
response was not registered by Yandex.Market. Since it is unknown whether the request for order acceptance
reached the merchant or not, when the reservation time expires, Yandex.Market cancels the order and notifies
the merchant. Expected merchant response: HTTP/1.1 200 OK.
Resource URL:
https://<request URL>/order/status
Response timeout: 10 seconds.
Developer's guide
165
XML
<order id="{number}" status="{string}" substatus="{string}" creation-date="{string}"
currency="{string}" items-total="{number}" total="{number}" payment-type="{string}"
payment-method="{string}" fake="{boolean}">
<items>
<item feed-id="{number}" offer-id="{string}" feed-category-id="{string}" offername="{string}" price="{number}" count="{number}" />
...
</items>
<notes>{string}</notes>
<delivery id="{string}" type="{string}" service-name="{string}" price="{number}"
...
</parent>
</region>
<address country="{string}" postcode="{string}" city="{string}"
subway="{string}" street="{string}" house="{string}" block="{string}"
entrance="{string}" entryphone="{string}" floor="{string}" apartment="{string}"
recipient="{string}" phone="{string}"/>
</delivery>
<buyer id="{string}" last-name="{string}" first-name="{string}" middlename="{string}" phone="{string}" email="{string}"/>
</order>
JSON
{
"order":
{
"id":{number},
"substatus":"{string}",
"creationDate":"{string}",
"itemsTotal":{number},
"total":{number},
"fake":{boolean},
"notes":"{string}",
"items":
[
{
"feedId":{number},
"price":{number},
"count":{number}
},
...
],
"notes":"{string}",
"delivery":
{
"id":"{string}",
"type":"{string}",
"price":{number},
"outletId":"{number}",
"region":
{
"id":{number},
"name":"{string}",
"type":"{string}",
"parent":
{
"id":{number},
"name":"{string}",
"type":"{string}",
"parent":
Developer's guide
166
{
...
}
}
},
"address":
{
"city":"{string}",
"house":"{string}",
"block":"{string}",
"entrance":"{string}",
"entryphone":"{string}",
"floor":"{string}",
"apartment":"{string}",
"recipient":"{string}",
"phone":"{string}"
},
"dates":
{
"fromDate":"03-02-2013",
"toDate":"05-02-2013"
}
},
"buyer":
{
"id":"{string}",
"lastName":"{string}",
"firstName":"{string}",
"middleName":"{string}",
"phone":"{string}",
"email":"{string}"
}
}
}
Parameter
for XML
format
Parameter
for JSON
format
order
order
Type
Value
Order.
id
id
Number
Campaign ID.
status
status
String
New order status. Possible values:
•
PROCESSING — Order is being processed.
•
DELIVERY — Order has been sent out for delivery.
•
PICKUP — Order has been delivered to the pick-up point.
•
DELIVERED — Order has been delivered to the buyer.
•
CANCELLED — Order canceled.
Developer's guide
167
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
substatus
substatus
String
Additional parameter for the new status of the order (substatus). If the
status does not have substatuses, this field is not output. Possible
substatuses for the CANCELLED status:
•
RESERVATION_EXPIRED — The customer did not complete
a reserved order within the time limit.
•
USER_NOT_PAID — The customer did not pay for the order (for
the PREPAID payment type).
•
USER_UNREACHABLE — The customer could not be contacted.
•
USER_CHANGED_MIND — The customer canceled the order
for personal reasons.
•
USER_REFUSED_DELIVERY — The customer did not agree
to the delivery conditions.
•
USER_REFUSED_PRODUCT — The product did not suit
the customer.
•
SHOP_FAILED — The merchant could not complete the order.
•
USER_REFUSED_QUALITY — The customer was not satisfied
with the quality of the product.
•
REPLACING_ORDER — The customer is changing the contents
of the order.
•
PROCESSING_EXPIRED — The merchant did not process
the order in time.
creationdate
creationDat String
e
Date the order was created in the format DD-MM-YYYY HH:MM:SS.
currency
currency
String
•
•
items-total itemsTotal
Number
Total amount of the order in the order's currency, excluding delivery cost.
A dot is used as the decimal separator.
total
total
Number
Total amount of the order in the order's currency, including delivery cost.
paymenttype
paymentType String
•
•
Optional parameter.
paymentmethod
paymentMeth String
od
type:
•
•
is received.
•
is received.
Optional parameter.
fake
fake
Logical
•
•
Developer's guide
168
Parameter
for XML
format
Parameter
for JSON
format
Type
items
items
Order contents.
buyer
buyer
Information about the customer.
notes
notes
delivery
delivery
String
Value
Comments on the order. Optional parameter.
item
feed-id
feedId
Number
offer-id
offerId
String
category-id yId
offer-name
offerName
String
price
price
Number
separator.
count
count
Number
Parameters nested in buyer
Mandatory
id
id
String
Buyer ID.
first-name
firstName
String
The customer's first name.
phone
phone
String
The customer's phone number in the format +<country code> <area code>
<phone number>.
email
email
String
The customer's email address.
lastName
String
The customer's last name.
String
The customer's patronymic or middle name.
String
Optional
last-name
middle-name middleName
id
id
cart request.
type
type
String
•
•
•
POST — Mail.
servicename
serviceName Number
Name of the delivery service. Specified for the delivery method
DELIVERY (courier).
price
price
separator.
dates
dates
region
region
Delivery region.
Number
Developer's guide
169
Parameter
for XML
format
Parameter
for JSON
format
address
address
outlet-id
outletId
Type
Value
Number
from-date
fromDate
String
to-date
toDate
String
id
id
Number
ID of the region.
name
name
String
Name of the region.
type
type
String
parent
parent
•
REGION — Region.
•
•
•
•
•
CITY — City.
•
•
•
•
id
id
Number
name
name
String
type
type
String
parent
parent
•
REGION — Region.
•
•
•
•
•
CITY — City.
•
•
•
•
Mandatory
country
country
String
Country.
Developer's guide
170
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
city
city
String
City or town.
house
house
String
postcode
postcode
String
street
street
String
Street.
subway
subway
String
block
block
String
entrance
entrance
String
Entrance number.
entryphone
entryphone
String
Code for the entry phone.
floor
floor
String
Floor.
apartment
apartment
String
Number of the apartment or office.
recipient
recipient
String
Full name of the order recipient.
phone
phone
String
Phone number of the order recipient.
Optional
Attention!
For orders with the RESERVED status, and also with the RESERVATION_EXPIRED or USER_NOT_PAID
substatus of the CANCELLED status, personal information about the customer and order recipient is not
available. The following parameters are not output:
•
The buyer parameter and all its attributes.
•
The entrance, entryphone, apartment, recipient, phone attributes in the address
parameter.
Response data
Not expected.
Error descriptions
Description
Explanation
Error 500
Error
Internal
Examples
XML
Developer's guide
171
POST /order/status HTTP/1.1
<order id="12345" status="PROCESSING" creation-date="01-02-2013 16:35:03" currency="RUR"
items-total="3700" total="4050" payment-type="POSTPAID" paymentmethod="CASH_ON_DELIVERY" fake="false">
<items>
</items>
<notes>Deliver asap, please!</notes>
<delivery type="DELIVERY" service-name="SPSR" price="350">
</parent>
</parent>
</region>
Vernadskovo" street="Leninskiy Prospekt" house="90" entrance="10" entryphone="289"
floor="6" apartment="289" recipient="Ivan Ivanov" phone="+71234567890"/>
</delivery>
<buyer id="LEgMQuxR8" last-name="Ivanov" first-name="Ivan" middle-name="Ivanovich"
phone="+71234567890" email="[email protected]"/>
</order>
HTTP/1.1 200 OK
JSON
POST /order/status HTTP/1.1
{
"order":{"id":12345, "status":"PROCESSING", "creationDate":"01-02-2013 16:35:03",
"currency":"RUR", "itemsTotal":3700, "total":4050, "paymentType":"POSTPAID",
"paymentMethod":"CASH_ON_DELIVERY", "fake":false,
"items":
[
"offerName":"Toaster", "price":2200, "count":1}
],
"notes":"Deliver asap, please!",
"delivery":{"type":"DELIVERY", "serviceName":"SPSR", "price":350,
"region":
{"id":1, "name":"Moscow and Moscow region", "parent":
}
}
},
"entrance":"10", "entryphone":"289", "floor":"6", "apartment":"289", "recipient":"Ivan
Ivanov", "phone":"+71234567890"},
"dates":{"fromDate": "03-02-2013", "toDate": "05-02-2013"}
},
"buyer":{"id":"LEgMQuuxR8", "lastName":"Ivanov", "firstName":"Ivan",
"middleName":"Ivanovich", "phone":"+71234567890", "email":"[email protected]"}
}
}
HTTP/1.1 200 OK
Developer's guide
172
Changing the order status
Description
Changes the status of an order.
PUT /campaigns/{campaignId}/orders/{orderId}/status
Note:
Resource URL:
https://api.partner.market.yandex.ru/v2/campaigns/{campaignId}/orders/{orderId}/
status.[format]
Input data
Parameters in the URL:
Parameter
Type
Value
campaignId
Number
The campaign ID.
orderId
Number
Campaign ID.
format
String
XML or JSON.
Mandatory
XML
<order status="{string}" substatus="{string}"/>
JSON
{
"order":
{
"substatus":"{string}"
}
}
Parameter
for XML
format
Parameter
for JSON
format
order
order
Type
Value
Order.
status
status
String
New order status. It should follow the flow of order status changes (see
the table below).
substatus
substatus
String
Additional parameter for the new status of the order (substatus). It should
follow the flow of order status changes (see the table below).
Developer's guide
173
Flow of changes to order status:
Event
Original status
New status
Order is ready to pass PROCESSING
to the delivery service.
DELIVERY
Order was canceled PROCESSING
during
processing;
the reason is specified
in the substatus.
CANCELLED
Available substatuses:
•
•
•
•
the customer.
•
•
of the order.
Order
has
been DELIVERY
delivered to the pickup point.
PICKUP
Order has been given DELIVERY
to the customer.
or PICKUP
DELIVERED
Order was canceled DELIVERY
during
delivery; or PICKUP
the reason is specified
in the substatus.
CANCELLED
Available substatuses:
•
•
•
•
the customer.
•
•
Output data
If the order status was changed successfully, updated order information is returned. In this case, the output
exactly matches the output of the resource GET /campaigns/{campaignId}/orders/{orderId}.
Error descriptions
If an error occurs, the server returns the HTTP response code and short description of the error (all the codes
and error descriptions are listed in the section Error messages in the documentation for the Yandex.Market
Partner API). Typical errors for this method:
Description
Explanation
Possible solution
Unknown status: 'status' An unknown status was indicated.
Unknown
'substatus'
substatus: An
unknown
was indicated.
Check whether the correct order status
was passed.
substatus Check whether the correct order substatus
was passed.
Developer's guide
174
Description
Order
'substatus'
not
match
'status'
Explanation
Possible solution
substatus The specified substatus does Check whether the correct order status
does not correspond to the current status. and substatus were passed.
status The substatus must be relevant
to the status.
Order
status The status indicated must have Check whether the correct order status
'newStatus'
must a substatus.
and substatus were passed.
be
accompanied
with
a substatus.
Order
'orderId'
with
status 'currentStatus'
is
not
allowed
for status 'status'
The specified status cannot be set Set a status that can be switched to from
because of the current order status the current status.
(does not conform to the chart
of statuses).
Status 'status' is not The specified status cannot be set Set an allowed status for this delivery type,
allowed
for
delivery for an order with the current or change the delivery type.
type 'type'
delivery type.
No permission to set You do not have the necessary Set statuses as appropriate for your rights.
status
'status' permissions to set this status
for
order
'orderId' or substatus.
with
status
'currentStatus'
Error 403 Forbidden
Access denied
Error 404 Not Found
Order
not
'orderId'
found: An order with the specified ID was Check whether the order ID is correct.
not found.
Examples
XML
Sample request:
PUT /v2/campaigns/10003/orders/12345/status.xml HTTP/1.1
<order status="DELIVERY"/>
Sample response:
<response>
<order id="12345" status="PROCESSING" creation-date="01-02-2013 16:35:03"
currency="RUR" items-total="3700" total="4050" payment-type="POSTPAID" paymentmethod="CASH_ON_DELIVERY" fake="false">
<items>
</items>
</parent>
</parent>
</region>
</delivery>
<buyer last-name="Ivanov" first-name="Ivan" middle-name="Ivanovich"
</order>
</response>
Developer's guide
175
JSON
Sample request:
PUT /v2/campaigns/10003/orders/12345/status.json HTTP/1.1
{"order":{"status":"DELIVERY"}}
Sample response:
{
"order": {"id":12345, "status":"PROCESSING", "creationDate":"01-02-2013 16:35:03",
"items":
[
],
"region":
{"id":3,"name":"Center", "type":"COUNTRY_DISTRICT", "parent":
{"id":225,"name":"Russia", "type":"COUNTRY"}
}
}
},
Ivanov", "phone":"+71234567890"},
},
"buyer":{"lastName":"Ivanov", "firstName":"Ivan", "middleName":"Ivanovich",
"phone":"+71234567890", "email":"[email protected]"}
}
}
Changing conditions for order delivery
Description
PUT /campaigns/{campaignId}/orders/{orderId}/delivery
Changes the conditions for order delivery.
Note:
Resource URL:
https://api.partner.market.yandex.ru/v2/{campaignId}/orders/{orderId}/delivery.
[format]
Input data
Parameter
Type
Value
Mandatory
Developer's guide
176
Parameter
Type
Value
campaignId
Number
The campaign ID.
orderId
Number
Campaign ID.
format
String
XML or JSON.
XML
<delivery id="{string}" type="{string}" service-name="{string}" price="{number}" outletid="{number}">
street="{string}" house="{string}" block="{string}" entrance="{string}"
entryphone="{string}" floor="{string}" apartment="{string}" recipient="{string}"
phone="{string}"/>
</delivery>
JSON
{
"delivery":
{
"id":"{string}",
"type":"{string}",
"price":{number},
"address":
{
"city":"{string}",
"house":"{string}",
"block":"{string}",
"floor":"{string}",
"phone":"{string}"
}
"dates":
{
"fromDate":"{string}", "toDate":"{string}"
}
}
}
Parameter
for XML
format
Parameter
for JSON
format
delivery
delivery
Type
Value
New delivery conditions.
id
id
String
New ID of the delivery option; assigned by the merchant. Specified if the
previous delivery option ID has to be changed.
type
type
String
New delivery method for the order.
Developer's guide
177
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
Possible values:
•
•
•
POST — Mail.
When changing the delivery method, you must specify all the parameters
that are mandatory for the new type: for PICKUP, the pick-up point;
for DELIVERY and POST, the delivery address.
If the corresponding mandatory parameter for the new delivery method
is omitted from the order, you must specify it in the request to this method.
servicename
serviceName String
Name of the delivery service. Specified if the delivery service needs to be
changed.
Specified for the delivery method DELIVERY (courier).
price
price
dates
dates
Range of dates for delivery. Specified if the dates need to be changed.
address
address
Delivery address. Specified if the address needs to be changed or if
the delivery method is being changed to DELIVERY (courier) or POST
(mail).
outlet-id
outletId
Number
Number
Cost of delivery in the order's currency. Specified if the cost of delivery
needs to be changed. However, the delivery cost may not be changed if the
payment method is set to prepayment for the order. A dot is used as the
decimal separator.
ID of a pick-up point set in the partner interface. Specified if the pick-up
point needs to be changed or if the delivery method is being changed
to PICKUP.
Note:
If a non-existing ID is specified (it doesn't match any of the IDs set in
the partner interface), an error will be returned in the response.
from-date
fromDate
String
to-date
toDate
String
Optional parameter. If the to-date parameter is omitted, the only
possible delivery date is assumed to be the date specified in the fromdate parameter.
Mandatory
country
country
String
Country.
city
city
String
City or town.
house
house
String
postcode
postcode
String
street
street
String
Street.
subway
subway
String
block
block
String
entrance
entrance
String
Entrance number.
Optional
Developer's guide
178
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
entryphone
entryphone
String
floor
floor
String
Floor.
apartment
apartment
String
recipient
recipient
String
phone
phone
String
Output data
If the delivery conditions were changed successfully, updated order information is returned. In this case, it exactly
matches the output of the resource GET /campaigns/{campaignId}/orders/{orderId}.
Error descriptions
Description
Explanation
Possible solution
Unknown delivery
'delivery-type'.
type An
invalid
is specified.
delivery
type Check whether the correct delivery type is being
passed.
Delivery outlet is not You cannot set a pick-up point Check whether the passed delivery parameters
appropriate
for the specified delivery method. are appropriate for the order's delivery method.
for
delivery
type
'delivery-type'.
Delivery address is not You cannot set an address for the Check whether the passed delivery parameters
appropriate
specified delivery method.
are appropriate for the order's delivery method.
for
delivery
type
'delivery-type'.
Delivery price change You cannot change the cost You can only change the cost of delivery
is
not
allowed of delivery for a prepaid order.
for postpaid orders.
for
prepaid
order
'order-id'.
Action is not allowed The action is forbidden for an order You can only change the order's delivery
for
order
'orderId' with the current status.
conditions when it has the PROCESSING,
with status: 'status'
DELIVERY, or PICKUP status.
Outlet is
'outletId'
not
found: A pick-up point with the specified Check whether the correct pick-up point ID was
ID was not found.
passed. It must match one that is set in the partner
interface.
Error 403 Forbidden
Access denied
Error 404 Not Found
Order
not
'orderId'
not found.
Examples
XML
Sample request:
Developer's guide
179
PUT /v2/campaigns/10003/orders/12345/delivery.xml HTTP/1.1
Vernadskovo"
street="Leninskiy Prospekt" house="90" entrance="10" entryphone="289" floor="6"
apartment="289" recipient="Ivan Ivanov" phone="+71234567890"/>
</delivery>
Sample response:
<response>
<items>
</items>
</parent>
</parent>
</region>
</delivery>
<buyer last-name="Ivanov" first-name="Ivan" middle-name="Ivanovich"
</order>
</response>
JSON
Sample request:
PUT /v2/campaigns/10003/order/12345/delivery.json HTTP/1.1
{
"delivery":
{
"type":"DELIVERY", "serviceName":"In-house delivery service", "price":13810,
"entrance":"10", "entryphone":"289", "floor":"6", "apartment":"289", "recipient": "Ivan
Ivanov", "phone": "+71234567890"}
"dates":{"fromDate":"03-02-2013"}
}
}
Sample response:
{
"order":
{
"id":12345, "status":"PROCESSING", "creationDate":"01-02-2013 16:35:03",
"items":
[
],
"delivery":
{
Developer's guide
180
"type":"DELIVERY", "serviceName":"SPSR", "price":350,
"region":
}
}
},
"entrance":"10", "entryphone":"289", "floor":"6", "apartment":"289", "recipient":"Ivanov
Ivan", "phone":"+71234567890"},
"dates":{"fromDate":"03-02-2013"}
},
"buyer":{"lastName":"Ivanov", "firstName":"Ivan", "middleName":"Ivanovich",
"phone":"+71234567890", "email":"[email protected]"}
}
}
Information about a requested order
Description
GET /campaigns/{campaignId}/orders/{orderId}
Returns information about the requested order.
Note:
Resource URL:
https://api.partner.market.yandex.ru/v2/campaigns/{campaignId}/orders/{orderId}.
[format]
Input data
Parameter
Type
Value
campaignId
Number
The campaign ID.
orderId
Number
Campaign ID.
format
String
XML or JSON.
Mandatory
Output data
Developer's guide
181
XML
payment-method="{string}" fake="{boolean}" notes="{string}">
<items>
<item feed-id="{number}" offer-id="{string}" feed-category-id="{string}" offername="{string}" price="{number}" count="{number}" />
...
</items>
...
</parent>
</region>
recipient="{string}" phone="{string}"/>
</delivery>
<buyer id="{string}" last-name="{string}" first-name="{string}" middlename="{string}" phone="{string}" email="{string}"/>
</order>
JSON
{
"order":
{
"id":{number},
"total":{number},
"fake":{boolean},
"notes":"{string}",
"items":
[
{
"feedId":{number},
"price":{number},
"count":{number}
},
...
],
"delivery":
{
"id":"{string}",
"type":"{string}",
"price":{number},
"outletId":"{number}",
"region":
{
"id":{number},
"name":"{string}",
"type":"{string}",
"parent":
{
"id":{number},
"name":"{string}",
"type":"{string}",
"parent":
{
...
Developer's guide
182
}
}
},
"address":
{
"city":"{string}",
"house":"{string}",
"block":"{string}",
"floor":"{string}",
"phone":"{string}"
},
"dates":
{
"fromDate":"03-02-2013",
"toDate":"05-02-2013"
}
},
"buyer":
{
"id":"{string}",
"phone":"{string}",
"email":"{string}"
}
}
}
Parameter
for XML
format
Parameter
for JSON
format
order
order
Type
Value
Order.
id
id
Number
Campaign ID.
status
status
String
Campaign state. Possible values:
•
RESERVED — Order has been reserved.
•
•
•
•
•
Developer's guide
183
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
substatus
substatus
String
Additional parameter for the order status. If the status does not have
substatuses, this field is not output. Possible substatuses for the
CANCELLED status:
•
•
the PREPAID payment method).
•
•
•
•
the customer.
•
•
•
of the order.
•
the order in time.
creationdate
creationDat String
e
Date the order was created in the format DD-MM-YYYY HH:MM:SS.
currency
currency
String
•
•
Number
total
total
Number
paymenttype
paymentType String
•
•
Optional parameter.
paymentmethod
paymentMeth String
od
type:
•
•
is received.
•
is received.
Optional parameter.
fake
fake
Logical
•
•
Developer's guide
184
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
notes
notes
String
items
items
Order contents.
buyer
buyer
delivery
delivery
Parameters nested in items
item
Parameters nested in item
feed-id
feedId
Number
offer-id
offerId
String
category-id yId
offer-name
offerName
String
price
price
Number
separator.
count
count
Number
Mandatory
id
id
String
Buyer ID.
first-name
firstName
String
phone
phone
String
<phone number>.
email
email
String
lastName
String
String
String
Optional
last-name
id
id
cart request.
type
type
String
•
•
•
POST — Mail.
servicename
serviceName Number
price
price
separator.
dates
dates
region
region
Delivery region.
Number
Developer's guide
185
Parameter
for XML
format
Parameter
for JSON
format
address
address
outlet-id
outletId
Type
Value
Number
from-date
fromDate
String
to-date
toDate
String
id
id
Number
ID of the region.
name
name
String
Name of the region.
type
type
String
parent
parent
•
REGION — Region.
•
•
•
•
•
CITY — City.
•
•
•
•
id
id
Number
name
name
String
type
type
String
parent
parent
•
REGION — Region.
•
•
•
•
•
CITY — City.
•
•
•
•
Mandatory
country
country
String
Country.
Developer's guide
186
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
city
city
String
City or town.
house
house
String
postcode
postcode
String
street
street
String
Street.
subway
subway
String
block
block
String
entrance
entrance
String
Entrance number.
entryphone
entryphone
String
floor
floor
String
Floor.
apartment
apartment
String
recipient
recipient
String
phone
phone
String
Optional
Attention!
•
•
parameter.
Error descriptions
Description
Explanation
Possible solution
Error 403 Forbidden
Access denied
Error 404 Not Found
Order
not
'orderId'
not found.
Examples
XML
Sample request:
GET /v2/campaigns/10003/orders/12345.xml HTTP/1.1
Sample response:
Developer's guide
187
<response>
<items>
</items>
</parent>
</parent>
</region>
</delivery>
<buyer id="LEgMQuuxR8" last-name="Ivanov" first-name="Ivan" middle-name="Ivanovich"
</order>
</response>
JSON
Sample request:
GET /v2/campaigns/10003/orders/12345.json HTTP/1.1
Sample response:
{
"order": {"id":12345, "status":"PROCESSING", "creationDate":"01-02-2013 16:35:03",
"items":
[
],
"region":
}
}
},
Ivanov", "phone":"+71234567890"},
},
}
}
Developer's guide
188
Information about requested orders
Description
Returns information about requested orders. Filtration is available by date of order creation and order status.
The maximum range of dates for a single request to the resource is 30 days.
Note:
Resource URL:
https://api.partner.market.yandex.ru/v2/campaigns/{campaignId}/orders.[format]?
[status={status}]&[fromDate={fromDate}]&[toDate={toDate}]&[pageSize={pageSize}]&
[page={page}]
Input data
Parameter
Type
Value
Number
The campaign ID.
format
String
XML or JSON.
status
String
Order status for filtering by this parameter.
fromDate
String
Start date for filtering orders by creation date. Default date: 30 days from the current
day. Date format: DD-MM-YYYY.
fake
Logical
Order flag for filtering test orders (true) or real orders (false).
Mandatory
campaignId
Optional
If the parameter is omitted, orders are not filtered by this parameter.
toDate
String
End date for filtering orders by creation date. Default date: corresponds to the current
day. Date format: DD-MM-YYYY.
pageSize
Number
The number of results on a page. By default, the maximum value of results is output
— 50.
page
Number
Page number in results. By default, the first page is output. Maximum allowed value:
100.
Output data
Developer's guide
189
XML
<orders>
payment-method="{string}" fake="{boolean}" notes="{string}">
<items>
<item feed-id="{number}" offer-id="{string}" feed-category-id="{string}"
offer-name="{string}" price="{number}" count="{number}"/>
...
</items>
<parent id="{number}" name="{string}" type="{string}"/>
...
</region>
recipient="{string}", phone="{string}"/>
</delivery>
<buyer id="{string}" last-name="{string}" first-name="{string}" middlename="{string}" phone="{string}" email="{string}" />
</order>
...
</orders>
JSON
{
"pager":
{
"total":{number},
"from":{number},
"to":{number},
},
"orders":
[
{
"id":{number},
"total":{number},
"fake":{boolean},
"notes":"{string}",
"items":
[
{
"feedId":{number},
"price":{number},
"count":{number}
},
...
],
"delivery":
{
"id":"{string}",
"type":"{string}",
"price":{number},
Developer's guide
190
"region":
{
"id":{number},
"name":"{string}",
"type":"{string}",
"parent":
{
"id":{number},
"name":"{string}",
"type":"{string}",
"parent":
{
...
},
},
},
"address":
{
"city":"{string}",
"house":"{string}",
"block":"{string}",
"floor":"{string}",
"phone":"{string}"
},
"dates":
{
"toDate": "{string}"
}
},
"buyer":
{
"id":"{string}",
"phone":"{string}",
"email":"{string}"
}
},
...
]
}
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
pager
pager
orders
orders
Orders.
total
total
Number
Number of entries found. The value may increase as the page number
increases. The final number of found entries has been reached when
the value of the total parameter matches the value of the to parameter.
from
from
Number
The sequential number of the first entry on the page in the overall search
Developer's guide
191
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
to
to
Number
The sequential number of the last entry on the page in the overall search
currentpage
currentPage Number
The sequential number of the current page in results. If nothing was found,
Number
The number of pages with search results. The value may increase as the
page number increases. The final number of pages has been reached when
the value of the pages-count parameter matches the value of the
current-page parameter.
page-size
pageSize
Number
The number of entries on the current page. If nothing was found,
Parameters nested in orders
order
Information about an order.
id
id
Number
Campaign ID.
status
status
String
Campaign state. Possible values:
substatus
creationdate
substatus
String
creationDat String
e
•
RESERVED — Order has been reserved.
•
•
•
•
•
Additional parameter for the order status. If the status does not have
substatuses, this parameter is not output. Possible substatuses for the
CANCELLED status:
•
•
the PREPAID payment type).
•
•
•
•
the customer.
•
•
•
of the order.
•
the order in time.
Date the order was created in the format DD-MM-YYYY HH:MM:SS
Developer's guide
192
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
currency
currency
String
•
•
Number
total
total
Number
paymenttype
paymentType String
•
•
Optional parameter.
paymentmethod
paymentMeth String
od
type:
•
•
is received.
•
is received.
Optional parameter.
fake
fake
Logical
•
•
notes
notes
items
items
Order contents.
buyer
buyer
delivery
delivery
String
Parameters nested in items
item
Parameters nested in item
feed-id
feedId
Number
offer-id
offerId
String
category-id yId
offer-name
offerName
String
price
price
String
separator.
count
count
Number
Mandatory
Developer's guide
193
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
id
id
String
Buyer ID.
first-name
firstName
String
phone
phone
String
<phone number>.
email
email
String
lastName
String
String
String
Optional
last-name
id
id
cart request.
type
type
String
•
•
•
POST — Mail.
servicename
serviceName String
price
price
separator.
dates
dates
region
region
Delivery region.
address
address
outlet-id
outletId
Number
Number
from-date
fromDate
String
to-date
toDate
String
id
id
Number
ID of the region.
name
name
String
Name of the region.
Developer's guide
194
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
type
type
String
parent
parent
•
REGION — Region.
•
•
•
•
•
CITY — City.
•
•
•
•
String
id
id
Number
name
name
String
type
type
String
parent
parent
•
REGION — Region.
•
•
•
•
•
CITY — City.
•
•
•
•
Mandatory
country
country
String
Country.
city
city
String
City or town.
house
house
String
postcode
postcode
String
street
street
String
Street.
subway
subway
String
block
block
String
entrance
entrance
String
Entrance number.
entryphone
entryphone
String
Optional
Developer's guide
195
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
floor
floor
String
Floor.
apartment
apartment
String
Apartment number.
recipient
recipient
String
phone
phone
String
Attention!
•
•
parameter.
Error descriptions
Description
Explanation
Possible solution
Invalid
'status'
status: An incorrect status was indicated.
Check the correctness of the status being passed
for filtering orders.
Too long time period. The specified period of dates is too Shorten the range of dates for filtering orders.
Maximum is 'maxPeriod' long.
days
Page
number
must The page number must be a positive Check whether the correct page number is being
be positive: 'page'
integer.
passed.
Page number is too big: The specified page number is too Check whether the correct page number is being
'pageNum'.
Max
page large.
passed.
number is 'maxPageNum'
Page
size
must The page size must be a positive Check whether the correct page size is being
be positive: 'pageSize' integer.
passed.
Page size is too big: The specified page size is too large. Check whether the correct page size is being
'pageSize'.
Max
page
passed.
Error 403 Forbidden
Access denied
Examples
XML
Sample request:
GET /v2/campaigns/10003/orders.xml HTTP/1.1
Sample response:
Developer's guide
196
<response>
<orders>
<items>
<item feed-id="12345" offer-id="4607632101" feed-category-id="41" offername="Тостер" price="2200" count="1"/>
</items>
</parent>
</parent>
</region>
Vernadskovo" street="Leninskiy prospekt" house="90" entrance="10" entryphone="289"
</delivery>
<buyer id="LEgMQuuxR8" last-name="Ivanov" first-name="Ivan" middlename="Ivanovich" phone="+71234567890" email="[email protected]"/>
</order>
<order id="12346" status="PICKUP" creation-date="31-01-2013 21:42:12" currency="RUR"
items-total="30800" total="30800" payment-type="POSTPAID" paymentmethod="CARD_ON_DELIVERY" fake="false">
<items>
<item feed-id="12345" offer-id="4638734829" feed-category-id="22" offername="Sony Xperia Z" price="28900" count="1"/>
<item feed-id="12345" offer-id="4683949391" feed-category-id="23" offername="Memory card microSDHC 32GB" price="1900" count="1"/>
</items>
<delivery type="PICKUP" service-name="In-house delivery service" price="0" outletid="9">
</parent>
</parent>
</region>
</delivery>
<buyer id="LEgMQuuxR10" last-name="Petrov" first-name="Peter" middlename="Petrovich" phone="+70987654321" email="[email protected]"/>
</order>
</orders>
</response>
JSON
Sample request:
GET /v2/campaigns/10003/order/12345.json HTTP/1.1
Sample response:
{
"pager":{"total":2,"from":1,"to":2,"pageSize":2,"pagesCount":1,"currentPage":1},
"orders":
[
{"id":12345, "status":"PROCESSING", "creationDate":"01-02-2013 16:35:03",
"paymentMethod":"CASH_ON_DELIVERY", "fake":false, "items":
[
],
Developer's guide
197
"region":
}
}
},
"entrance":"10", "entryphone":"289", "floor":"6", "apartment":"289", "recipient": "Ivan
Ivanov", "phone": "+71234567890"},
"dates": {"fromDate": "02-02-2013", "toDate": "03-02-2013"}
},
},
{"id":12346, "status":"PICKUP", "creationDate":"31-01-2013 21:42:12",
"currency":"RUR", "itemsTotal":"30800", "total":"30800", "paymentType":"POSTPAID",
"paymentMethod":"CARD_ON_DELIVERY", "fake":false, "items":
[
{"feedId":12345, "offerId":"4638734829", "feedCategoryId":"22", "offerName":"Sony
Xperia Z", "price":28900, "count":1},
"offerName":"Memory card microSDHC 32GB", "price":1900, "count":1}
],
"delivery":{"type":"PICKUP", "price":0, "serviceName":"In-house delivery service",
"outletId":9,
"region":
}
}
},
"dates": {"fromDate": "02-02-2013", "toDate": "02-02-2013"}
},
"buyer":{"id":"LEgMQuuxR10", "lastName":"Petrov", "firstName":"Peter",
"middleName":"Petrovich", "phone":"+70987654321", "email":"[email protected]"}
}
]
}
Developer's guide
198
Practical usage
This section describes how to perform various tasks using the API.
Setting recommended bids on a selection of products
To set recommended bids on a selection of products from a particular campaign:
1. Use the GET campaigns method to get a list of all your campaigns on Yandex.Market. Select the campaign
that you want to set recommended bids for.
Sample request:
GET
https://api.partner.market.yandex.ru/v1/campaigns.json?oauth_token=
4f009f4e680a433dbf6ddb6c39258099&oauth_login=test-login&oauth_client_id=
47e4d0745753440b9d811b409871b876
Sample response:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-RateLimit-Resource-Limit: 10000
X-RateLimit-Resource-Until: Tue, 17 Apr 2012 00:00:00 GMT
X-RateLimit-Resource-Remaining: 9998
{"campaigns": [
{"id":10001,"domain":"nif-nif.yandex.ru","state":2,"stateReason":[9]},
{"id":10002,"domain":"nuf-nuf.yandex.ru","state":2,"stateReason":[6,25]},
{"id":10003,"domain":"naf-naf.yandex.ru","state":1}
]}
2. Get a list of product offers for the selected campaign that are published on Yandex.Market and that need
bids set. In the GET campaigns/{campaignId}/offers method, specify the campaign id and the query
for searching for the desired products.
Sample for campaign 10003 for the query "toaster":
GET
https://api.partner.market.yandex.ru/v1/campaigns/10003/offers.json?
query=toaster&oauth_token=4f009f4e680a433dbf6ddb6c39258099&
oauth_login=test-login&oauth_client_id=47e4d0745753440b9d811b409871b876
Sample response:
Developer's guide
199
HTTP/1.1 200 OK
{"searchSummary":{"totalOffers":2,"fromOffer":1,"toOffer":2,
"pageOffers":100,"pagesCount":1,"currentPage":1},
"offers":[
{"url":"http://nuf-nuf.yandex.ru/product/21003/","modelId":282404,
"name":"Tefal 539625","price":"1215","currency":"RUR","bid":0.12,"cbid":
0.12},
{"url":"http://nuf-nuf.yandex.ru/product/93728/","modelId":0,
"name":"Clatronic CM 3372","price":"1329","currency":"RUR","bid":
0.15,"cbid":0.22}
]
}
3. Set recommended bid values for showing the selected products in the desired position on the Yandex.Market
product profile. In the PUT campaigns/{campaignId}/bids/recommended method, specify the campaign
number, the desired position on the product profile, and the names of the selected product offers.
Sample request for setting recommended bids to show products in the fifth position on the product profile:
PUT
https://api.partner.market.yandex.ru/v1/campaigns/10003/bids/
recommended.json?
position=5&oauth_token=4f009f4e680a433dbf6ddb6c39258099&oauth_login=testlogin&
oauth_client_id=47e4d0745753440b9d811b409871b876
Content-Type application/json
{"offers":[
"Tefal 539625",
"Clatronic CM 3372"
]}
Sample response:
HTTP/1.1 200 OK
{"bids-set":[
{"offerName":"Tefal 539625","cbid":0.33},
{"offerName":"Clatronic CM 3372","cbid":0.27} ]}
See also
Authentication
Method calls
Input data format
Response format
Developer's guide
Developer's guide
Questions on partner API
If you have questions about partner API, send a letter from the feedback form below. We guarantee you will
get a response.
Developer's guide
200
Index
A
Accept order 157
Access token 7, 18
API methods] [Order on Market 149
API version 7
Assortment 46
Authorization 18
B
Basic bid 46, 91
Basic methods 28
Basic statistics 126
Bid for product profile 91
Bid recommendations 103, 114
Bid settings 122
C
GET campaigns/{campaignId}/region 42
GET campaigns/{campaignId}/settings 39
GET campaigns/{campaignId}/stats/main 126
GET campaigns/{campaignId}/stats/offers 131
GET models/ 69
GET models/{modelId} 66
GET models/{modelId}/offers 78
GET regions 137
GET regions/{regionId} 140
GET regions/{regionId}/children 143
Global limits 13
I
Information about an order 180
Information about bids 91
Information about orders 187
Input data format 8
Campaign balance 124
Campaign information 32
Campaign region 42
Campaign settings 39
Campaigns accessible by login 36
Cart 149
Categories of product offers 57, 61
J
D
Managing bids 91, 96
Method calls 7
Method types 7
Debugging token 17
DELETE 7
Delivery conditions][Order 175
E
Error codes 9
Error descriptions 9
Error messages 9
Errors 21
F
Finances 124
Forecast of campaign expenditures 124
Functional limits 13
G
Geobase 137
GET 7, 29, 32, 35, 36, 39, 42, 46, 52, 55, 57, 61, 66, 69, 78,
122, 124, 126, 131, 137, 140, 143, 180, 187
GET /campaigns/{campaignId}/orders 187
GET /campaigns/{campaignId}/orders/{orderId} 180
GET campaigns 29
GET campaigns/by_login/{login} 36
GET campaigns/{campaignId} 32
GET campaigns/{campaignId}/balance 124
GET campaigns/{campaignId}/bids/settings 122
GET campaigns/{campaignId}/feeds 52
GET campaigns/{campaignId}/feeds/categories 61
GET campaigns/{campaignId}/feeds/{feedId} 55
GET campaigns/{campaignId}/feeds/{feedId}/categories 57
GET campaigns/{campaignId}/logins 35
GET campaigns/{campaignId}/offers 46
JSON 8, 9, 20
L
Logins associated with a campaign 35
M
O
OAuth 7
Order status 164, 171
P
Partner API 5
Partner interface 5
Placement settings 42
POST 7, 8, 74, 83, 91, 103, 149, 157, 164
POST /cart 149
POST /order/accept 157
POST campaigns/{campaignId}/bids 91
POST campaigns/{campaignId}/bids/recommended 103
POST models 74
POST models/offers 83
POST order/status 164
Price list 46, 52, 55, 57
Product information 149
Product models 78
Product modifications 66, 69, 74, 83
Product offers 46, 78, 83
Product profile bid 46
PUT 7, 8, 96, 114, 171, 175
PUT /campaigns/{campaignId}/orders/{orderId}/delivery 175
PUT /campaigns/{campaignId}/orders/{orderId}/status 171
PUT campaigns/{campaignId}/bids 96
Developer's guide
202
Index
PUT campaigns/{campaignId}/bids/recommended 114
R
Recommendations for payment 124
Recommended bids 103, 114
Regions 137, 140, 143
Releases 21
Removing bids 96
Request format 7, 20
Request method 20
Request parameters 7
Requests to a merchant 18
Resource limits 13
Resources 5
Response format 7, 9, 20
REST principles 5
Restrictions for methods 13
S
Search for product offers 46
Self-signed certificate 18
Setting bids 96, 114
Setting recommended bids 198
Shop order 180
Shop orders 187
SSL certificate 18
Statistics 126
Statistics for product offers 131
T
Timeout 20
Token 7
U
URL address 20
User campaigns 29
V
Versions 14
X
XML 8, 9, 20
Y
Yandex.Market 5
Developer's guide
Developer's guide
14.10.2016

Yandex.Market Partner API. Developer`s guide

Transcription

Similar documents

The 13th National Chil

Flemish String Board Attachment

sponsorship package

Knotted Friendship Bracelet

Yandex: Webmaster Tools

Load Testing at Yandex

Double Bass Survival Guide By David Gage

Online Shopping in Russia

Whitepages Pro Caller Identification API