1. No category

Yandex.Market Partner API
Developer's guide
11.06.2015
Yandex.Market Partner API. Developer's guide. Version 2.0
Document build date: 11.06.2015.
This volume is a part of Yandex technical documentation.
Yandex helpdesk site: http://help.yandex.ru
© 2008—2015 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: pr@yandex-team.ru
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
Yandex.Market Partner API
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
Index ................................................................................................................................................................................................ 200
Yandex.Market Partner API
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.
Yandex.Market Partner API
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)
Yandex.Market Partner API
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
Yandex.Market Partner API
Developer's guide
Requests to Yandex.Market 8
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
Yandex.Market Partner API
Developer's guide
Requests to Yandex.Market 9
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.
Yandex.Market Partner API
Developer's guide
Requests to Yandex.Market 10
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.
Check whether the data passed in the request
body is formatted correctly for JSON.
XML: {message}
Error in the formatting of XML
data.
Check whether the data passed in the request
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'.
Check the correctness of the parameter
value.
Value of field must
match the pattern:
'regExp'.
The parameter value must match
the regular expression.
Check the correctness of the parameter
value.
Value of field has too
high scale: 'price'.
The parameter is too precise.
Set parameter values with fewer decimal
points.
Yandex.Market Partner API
Developer's guide
Requests to Yandex.Market 11
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.
Check that authentication data is correct.
OAuth credentials
are not specified
Authentication data was not
specified in the request.
Check that authentication data is correct.
OAuth token is not
specified
The request does not specify
an access token (the
oauth_token parameter).
Check that authentication data is correct.
OAuth client id is
not specified
The request does not specify
the application identifier
(oauth_client_id
parameter).
Check that authentication data is correct.
OAuth login is not
specified
The request does not specify
the user login (the
oauth_login parameter).
Check that authentication data is correct.
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.
Check that authentication data is correct.
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:
Yandex.Market Partner API
Developer's guide
Requests to Yandex.Market 12
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
request was not found.
Check whether the correct order ID was
passed.
Feed not found:
'feedId'
The price list specified in the
request was not found.
Check whether the correct price list ID was
passed.
Model not found:
'modelId'
The model specified in the
request was not found.
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:
Yandex.Market Partner API
Developer's guide
Requests to Yandex.Market 13
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
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.
Yandex.Market Partner API
Developer's guide
Requests to Yandex.Market 14
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.
Yandex.Market Partner API
Developer's guide
Requests to Yandex.Market 15
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
Yandex.Market Partner API
Developer's guide
Requests to Yandex.Market 16
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.
Yandex.Market Partner API
Developer's guide
Requests to Yandex.Market 17
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.
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.
Yandex.Market Partner API
Developer's guide
Requests to the merchant 19
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.
Yandex.Market Partner API
Developer's guide
Requests to the merchant 20
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.
Yandex.Market Partner API
Developer's guide
Requests to the merchant 21
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.
Yandex.Market Partner API
Developer's guide
Requests to the merchant 22
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.
Yandex.Market Partner API
Developer's guide
Requests to the merchant 23
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.
Yandex.Market Partner API
Developer's guide
Requests to the merchant 24
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.
Yandex.Market Partner API
Developer's guide
Requests to the merchant 25
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) → Параметры
Yandex.Market Partner API
Developer's guide
Requests to the merchant 26
размещения (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.
Yandex.Market Partner API
Developer's guide
Requests to the merchant 27
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).
Yandex.Market Partner API
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
Yandex.Market Partner API
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.
10000 requests per day.
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>
Yandex.Market Partner API
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:
•
2 — Inactive campaign.
•
4 — Campaign is being deactivated.
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
Yandex.Market Partner API
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.
•
21 — The campaign is inactive or is being deactivated because
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.
•
25 — The campaign is inactive or is being deactivated because
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:
<?xml version="1.0" encoding="UTF-8"?>
<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:
Yandex.Market Partner API
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
Structure of output data:
XML
<campaign id="{number}" domain="{string}" state="{number}">
<state-reasons>
<reason id="{number}"/>
...
</state-reasons>
</campaign>
Output data structure for XML format prior to version 2.0 of the Yandex.Market Partner API
<campaign>
<campaign id="{number}" domain="{string}" state="{number}">
<state-reasons>
<reason id="{number}"/>
...
</state-reasons>
</campaign>
</campaign>
Yandex.Market Partner API
Developer's guide
33
JSON
{
"campaign":
{
"id":{number},
"domain":"{string}",
"state":{number},
"stateReasons":
[
{number},
...
]
}
}
Parameter descriptions:
Parameter
for XML
format
Parameter
for JSON
format
campaign
campaign
Type
Value
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:
•
2 — Inactive campaign.
•
4 — Campaign is being deactivated.
Parameters nested in state-reasons/stateReasons
reason
Description of a reason. Each reason is explained in a separate
reason parameter.
Parameters nested in campaign
id
Yandex.Market Partner API
Number
Reason code.
Developer's guide
34
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.
•
21 — The campaign is inactive or is being deactivated because
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.
•
25 — The campaign is inactive or is being deactivated because
of outdated information.
Error descriptions
If an error occurs, the server returns the HTTP response code and a brief error description.
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:
<?xml version="1.0" encoding="UTF-8"?>
<response>
<campaign id="10001" domain="nif-nif.yandex.ru" state="2">
<state-reasons>
<reason id="6"/>
<reason id="9"/>
</state-reasons>
</campaign>
</response>
Yandex.Market Partner API
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
Structure of output data:
XML
<logins>
<login>{string}</login>
...
</logins>
Output data structure for XML format prior to version 2.0 of the Yandex.Market Partner API
<logins>
<string>{string}</string>
...
</logins>
JSON
{
"logins":
[
"{string}",
...
]
}
Yandex.Market Partner API
Developer's guide
36
Parameter descriptions:
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
If an error occurs, the server returns the HTTP response code and a brief error description.
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/logins.xml
Sample response:
<?xml version="1.0" encoding="UTF-8"?>
<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.
Yandex.Market Partner API
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
Structure of output data:
XML
<campaigns>
<campaign id="{number}" domain="{string}" state="{number}">
<state-reasons>
<reason id="{number}"/>
...
</state-reasons>
</campaign>
...
</campaigns>
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.
Yandex.Market Partner API
Developer's guide
38
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
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:
•
2 — Inactive campaign.
•
4 — Campaign is being deactivated.
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.
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.
•
21 — The campaign is inactive or is being deactivated because
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.
•
25 — The campaign is inactive or is being deactivated because
of outdated information.
Error descriptions
If an error occurs, the server returns the HTTP response code and a brief error description.
Errors containing brief descriptions typical for this method:
Description
Explanation
Possible solution
Error 403 Forbidden
Yandex.Market Partner API
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
request was not found.
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:
<?xml version="1.0" encoding="UTF-8"?>
<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]
Yandex.Market Partner API
Developer's guide
40
Input data
Parameter
Type
Value
Number
The campaign ID.
Mandatory
campaignId
Output data
Structure of 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 descriptions:
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
Yandex.Market Partner API
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
If an error occurs, the server returns the HTTP response code and a brief error description.
Errors containing brief descriptions typical for this method:
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:
<?xml version="2.0" encoding="UTF-8"?>
<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}}
Yandex.Market Partner API
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.
10000 requests per day.
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:
This method is available starting from version 1.2 of the Yandex.Market Partner API.
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
Structure of output data:
XML
<region id="{number}" name="{string}" type="{string}">
<parent id="{number}" name="{string}" type="{string}">
...
</parent>
</region>
Yandex.Market Partner API
Developer's guide
43
JSON
{
"region":
{
"id":{number},
"name":"{string}",
"type":"{string}",
"parent":
{
"id":{number},
"name":"{string}",
"type":"{string}",
"parent":
{
...
}
}
}
}
Parameter descriptions:
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.
Yandex.Market Partner API
Developer's guide
44
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
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.
Recursively nested element for specifying higher-level "parent" regions.
Error descriptions
If an error occurs, the server returns the HTTP response code and a brief error description.
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/region.xml
Sample response:
<?xml version="1.0" encoding="UTF-8"?>
<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:
Yandex.Market Partner API
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"}}}}
}
}
Yandex.Market Partner API
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.
10000 requests per day.
GET campaigns/{campaignId}/feeds/
{feedId}
Returns information about the price list 10000 requests per day.
of a campaign on Yandex.Market.
GET campaigns/{campaignId}/feeds/
{feedId}/categories
Returns a list of price list categories for a Individual number of requests per day;
campaign on Yandex.Market.
1000 categories per request.
GET campaigns/{campaignId}/feeds/
categories
Returns a list of categories for a
campaign on Yandex.Market.
Individual number of requests per day;
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]
Yandex.Market Partner API
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.
This parameter is available starting in version 2.0 of the Yandex.Market Partner API.
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
Structure of output data:
Yandex.Market Partner API
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 descriptions:
Parameter
for XML
format
Parameter
for JSON
format
pager
pager
Type
Value
Summary of search results.
Prior to version 2.0 of the Yandex.Market Partner API, the parameter
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.
Prior to version 2.0 of the Yandex.Market Partner API, the parameter
was called total-offers in XML format, and totalOffers
in JSON format.
from
Yandex.Market Partner API
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
Prior to version 2.0 of the Yandex.Market Partner API, the parameter
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,
the value of the parameter is 0.
Prior to version 2.0 of the Yandex.Market Partner API, the parameter
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
Prior to version 2.0 of the Yandex.Market Partner API, the parameter
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.
This parameter is available starting in version 2.0 of the Yandex.Market
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
Yandex.Market Partner API
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.
This parameter is available starting in version 2.0 of the Yandex.Market
Partner API.
Error descriptions
If an error occurs, the server returns the HTTP response code and a brief error description.
Errors containing brief descriptions typical for this method:
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
Check whether the correct data is being passed
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'
Yandex.Market Partner API
The price list specified in the Check whether the correct data is being passed
request was not found.
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:
<?xml version="1.0" encoding="UTF-8"?>
<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">
<url>http://nuf-nuf.yandex.ru/product/93728/</url>
<name>Clatronic CM 3372</name>
</offer>
<offer id="122" feed-id="29392" model-id="4999699" price="2555" currency="RUR"
bid="0.12" cbid="0.12" shop-category-id="12345678">
<url>http://nuf-nuf.yandex.ru/product/27381/</url>
<name>DeLonghi CTO 2003.B</name>
</offer>
<offer id="123" feed-id="29392" model-id="7146186" price="638" currency="RUR"
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>
<offer id="124" feed-id="29392" model-id="0" price="1131" currency="RUR" bid="0.12"
cbid="0.12" shop-category-id="87654321">
<url>http://nuf-nuf.yandex.ru/product/29101/</url>
<name>Moulinex SM1511</name>
</offer>
<offer id="125" feed-id="29392" model-id="956896" price="1163" currency="RUR"
bid="0.12" cbid="0.12" shop-category-id="87654321">
<url>http://nuf-nuf.yandex.ru/product/50955/</url>
<name>Bosch TAT 6104</name>
</offer>
<offer id="126" feed-id="29392" model-id="0" price="1064" currency="RUR" bid="0.12"
cbid="0.12" shop-category-id="87654321">
Yandex.Market Partner API
Developer's guide
52
<url>http://nuf-nuf.yandex.ru/product/76477/</url>
<name>Brand 33102, Green</name>
</offer>
<offer id="127" feed-id="29392" model-id="928393" price="1206" currency="RUR"
bid="0.12" cbid="0.12" shop-category-id="87654321">
<url>http://nuf-nuf.yandex.ru/product/37701/</url>
<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"},
{"id":"121", "feedId":29392, "url":"http://nuf-nuf.yandex.ru/product/
93728/","modelId":0,
"name":"Clatronic CM 3372","price":1329,"currency":"RUR","bid":
0.15,"cbid":0.22, "shopCategoryId":"12345678"},
{"id":"122", "feedId":29392, "url":"http://nuf-nuf.yandex.ru/product/
27381/","modelId":4999699,
"name":"DeLonghi CTO 2003.B","price":
2555,"currency":"RUR","bid":0.12,"cbid":0.12, "shopCategoryId":"12345678"},
{"id":"123", "feedId":29392, "url":"http://nuf-nuf.yandex.ru/product/
84958/","modelId":7146186,
"name":"Clatronic TA 3287, White","price":
638,"currency":"RUR","bid":0.12,"cbid":0.12, "shopCategoryId":"87654321"},
{"id":"124", "feedId":29392, "url":"http://nuf-nuf.yandex.ru/product/
29101/","modelId":0,
"name":"Moulinex SM1511","price":1131,"currency":"RUR","bid":
0.12,"cbid":0.12, "shopCategoryId":"87654321"},
{"id":"125", "feedId":"29392", "url":"http://nuf-nuf.yandex.ru/product/
50955/","modelId":956896,
"name":"Bosch TAT 6104","price":1163,"currency":"RUR","bid":
0.12,"cbid":0.12, "shopCategoryId":"87654321"},
{"id":"126", "feedId":29392, "url":"http://nuf-nuf.yandex.ru/product/
76477/","modelId":0,
"name":"Brand 33102, Green","price":1064,"currency":"RUR","bid":
0.12,"cbid":0.12, "shopCategoryId":"87654321"},
{"id":"127", "feedId":29392, "url":"http://nuf-nuf.yandex.ru/product/
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.
Yandex.Market Partner API
Developer's guide
53
Note:
This method is available starting from version 2.0 of the Yandex.Market Partner API.
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
Structure of 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 descriptions:
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
Yandex.Market Partner API
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.
This parameter is output when the price list is published on your shop's
site with restricted access.
password
password
String
Password for authentication when downloading the price list.
This parameter is output when the price list is published on your shop's
site with restricted access.
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.
This parameter is output when the price list is published on the
Yandex.Market server.
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.
This parameter is output when the price list is published on the
Yandex.Market server.
Error descriptions
If an error occurs, the server returns the HTTP response code and a brief error description.
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/feeds.xml
Sample response:
<?xml version="1.0" encoding="UTF-8"?>
<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>
Yandex.Market Partner API
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:
This method is available starting from version 2.0 of the Yandex.Market Partner API.
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
Structure of output data:
Yandex.Market Partner API
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 descriptions:
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.
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.
This parameter is output when the price list is published on your shop's
site with restricted access.
password
password
String
Password for authentication when downloading the price list.
This parameter is output when the price list is published on your shop's
site with restricted access.
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.
This parameter is output when the price list is published on the
Yandex.Market server.
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.
This parameter is output when the price list is published on the
Yandex.Market server.
Yandex.Market Partner API
Developer's guide
57
Error descriptions
If an error occurs, the server returns the HTTP response code and a brief error description.
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
Error 404 Not Found
Feed not found:
'feedId'
The price list specified in the Check whether the price list ID is correct.
request was not found.
Examples
XML
Sample request:
GET https://api.partner.market.yandex.ru/v2/campaigns/10001/feeds/12345.xml
Sample response:
<?xml version="1.0" encoding="UTF-8"?>
<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.
Yandex.Market Partner API
Developer's guide
58
Note:
This method is available starting from version 2.0 of the Yandex.Market Partner API.
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
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, an error message
is returned.
Output data
Structure of output data:
XML
<pager total="{number}" from="{number}" to="{number}" current-page="{number}" pagescount="{number}" page-size="{number}"/>
<categories>
<category feed-id="{number}" id="{string}" parent-id="{string}" name="{string}"/>
...
</categories>
JSON
{
"pager":
{
"total":{number},
"from":{number},
"to":{number},
"pageSize":{number},
"pagesCount":{number},
"currentPage":{number}
},
"categories":
Yandex.Market Partner API
Developer's guide
59
[
{
"id":"{string}",
"feedId":{number},
"parentId":"{string}",
"name":"{string}"
},
...
]
}
Parameter descriptions:
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
pager
pager
Summary of search results.
categories
categories
List of categories.
Parameters nested in search-pager
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,
the value of the parameter is 0.
to
to
Number
The index number within search results for the last category on the page
that is output in the response. If the desired categories were not found,
the value of the parameter is 0.
currentpage
currentPage Number
The index number of the page with search results that is output in the
response. If the desired categories were not found, the value of the
parameter is 0.
pages-count pagesCount
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.
If the desired categories were not found, the value of the parameter is 0.
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
If an error occurs, the server returns the HTTP response code and a brief error description.
Errors containing brief descriptions typical for this method:
Description
Explanation
Possible solution
Error 400 Bad Request
Yandex.Market Partner API
Developer's guide
60
Description
Explanation
Possible solution
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.
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 categories to output Check whether the correct number of categories
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 categories to output Check whether the correct number of categories
per page exceeds the maximum
to output per page is being passed in the request.
value maxPageSize.
Error 403 Forbidden
Access denied
Information about the campaign
specified in the request is not
accessible.
Check whether the campaign ID is correct.
Error 404 Not Found
Feed not found:
'feedId'
The price list specified in the Check whether the price list ID is correct.
request was not found.
Restrictions
For the methods GET campaigns/{campaignId}/feeds/{feedId}/categories and GET campaigns/{campaignId}/
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
and depends on the following factors:
•
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:
<?xml version="1.0" encoding="UTF-8"?>
<response>
<pager total="3" from="1" to="3" current-page="1" pages-count="1" page-size="3"/>
<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:
Yandex.Market Partner API
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:
This method is available starting from version 2.0 of the Yandex.Market Partner API.
Resource URL:
https://api.partner.market.yandex.ru/v2/campaigns/{campaignId}/feeds/categories.
[format]
Input data
Parameter
Type
Value
Mandatory
Yandex.Market Partner API
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
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, an error message
is returned.
Output data
Structure of output data:
XML
<pager total="{number}" from="{number}" to="{number}" current-page="{number}" pagescount="{number}" page-size="{number}"/>
<categories>
<category feed-id="{number}" id="{string}" parent-id="{string}" name="{string}"/>
...
</categories>
JSON
{
"pager":
{
"total":{number},
"from":{number},
"to":{number},
"pageSize":{number},
"pagesCount":{number},
"currentPage":{number}
},
"categories":
[
{
"id":"{string}",
"feedId":{number},
"parentId":"{string}",
"name":"{string}"
},
...
]
}
Parameter descriptions:
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
pager
pager
Summary of search results.
categories
categories
List of categories.
Parameters nested in search-pager
total
Yandex.Market Partner API
total
Number
If the desired categories were not found, the value of the parameter is 0.
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
that is output in the response. If the desired categories were not found,
the value of the parameter is 0.
to
to
Number
The index number within search results for the last category on the page
that is output in the response. If the desired categories were not found,
the value of the parameter is 0.
currentpage
currentPage Number
The index number of the page with search results that is output in the
response. If the desired categories were not found, the value of the
parameter is 0.
pages-count pagesCount
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.
If the desired categories were not found, the value of the parameter is 0.
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
If an error occurs, the server returns the HTTP response code and a brief error description.
Errors containing brief descriptions typical for this method:
Description
Explanation
Possible solution
Error 400 Bad 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.
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 categories to output Check whether the correct number of categories
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 categories to output Check whether the correct number of categories
per page exceeds the maximum
to output per page is being passed in the request.
value maxPageSize.
Error 403 Forbidden
Access denied
Information about the campaign
specified in the request is not
accessible.
Check whether the campaign ID is correct.
Restrictions
For the methods GET campaigns/{campaignId}/feeds/{feedId}/categories and GET campaigns/{campaignId}/
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.
Yandex.Market Partner API
Developer's guide
64
The volume 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 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:
<?xml version="1.0" encoding="UTF-8"?>
<response>
<pager total="6" from="1" to="6" current-page="1" pages-count="1" page-size="6"/>
<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"/>
<category feed-id="12345" id="1" name="Televisions"/>
<category feed-id="12345" id="2" parent-id="1" name="LCD"/>
<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,
"name":"Televisions"
},
{
"id":"2",
"feedId":12347,
"parentId":"1",
"name":"LCD"
},
{
"id":"3",
"feedId":12347,
"parentId":"1",
"name":"Plasma"
},
{
"id":"1",
Yandex.Market Partner API
Developer's guide
65
"feedId":12345,
"name":"Televisions"
},
{
"id":"2",
"feedId":12345,
"parentId":"1",
"name":"LCD"
},
{
"id":"4",
"feedId":12345,
"parentId":"1",
"name":"CRT"
}
]
}
Yandex.Market Partner API
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
Returns information about product
offers for the specified modification.
Individual number of requests per day.
POST models/offers
Returns information about product
offers for the specified modifications.
Individual number of requests per day;
100 modifications per request.
Individual number of requests per day;
100 modifications per request.
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:
This method is available starting from version 1.2 of the Yandex.Market Partner API.
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
Yandex.Market Partner API
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
Structure of 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 descriptions:
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
The currency used for prices of product offers for the modification.
Possible values:
•
RUR (Russian ruble)
•
UAH (Ukrainian hrivna)
•
BYR (Belarusian ruble)
•
KZT (Kazakhstani tenge)
Parameters nested in models
Yandex.Market Partner API
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.
Use the GET regions/{regionId} method to get region information by ID.
currency
String
The currency used for prices of product offers for the modification.
Possible values:
model
•
RUR (Russian ruble)
•
UAH (Ukrainian hrivna)
•
BYR (Belarusian ruble)
•
KZT (Kazakhstani tenge)
Description of a modification.
Parameters nested in model
id
id
Number
ID of the product modification.
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
If an error occurs, the server returns the HTTP response code and a brief error description.
Errors containing brief descriptions typical for this method:
Description
Explanation
Possible solution
Unsupported currency:
'currency'
The currency specified in the
request is not supported.
Check whether the correct currency code
is being passed in the request.
Invalid regionId:
'regionId'
The region with the specified
regionId was not found.
Check whether the region ID is correct.
Error 400 Bad Request
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}, GET models, and POST models, a group resource limit is applied.
The limit is applied to the total number of modifications 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
and depends on the following factors:
•
The number of offers on product profiles.
•
How many active campaigns the client has.
Yandex.Market Partner API
Developer's guide
69
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.
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:
<?xml version="1.0" encoding="UTF-8"?>
<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:
This method is available starting from version 1.2 of the Yandex.Market Partner API.
Resource URL:
Yandex.Market Partner API
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
Use the GET regions method to get the region ID.
Optional
page
Number
Page number in results.
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)
•
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
Structure of output data:
XML
<models region-id="{number}" currency="{string}">
<model id="{number}" name="{string}">
<prices min="{number}" max="{number}" avg="{number}">
</model>
...
</models>
<pager total="{number}" from="{number}" to="{number}" current-page="{number}" pagescount="{number}" page-size="{number}"/>
JSON
{
"models":
[
{
"id":{number},
"name":"{string}",
"prices":
{
"min":{number},
"max":{number},
Yandex.Market Partner API
Developer's guide
71
"avg":{number}
}
},
...
],
"pager":
{
"total":{number},
"from":{number},
"to":{number},
"currentPage":{number},
"pagesCount":{number},
"pageSize":{number}
},
"regionId":{number},
"currency":"{string}"
}
Parameter descriptions:
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.
Prior to version 2.0 of the Yandex.Market Partner API, the parameter
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.
Use the GET regions/{regionId} method to get region information by ID.
currency
String
The currency used for prices of product offers for modifications.
Possible values:
•
RUR (Russian ruble)
•
UAH (Ukrainian hrivna)
•
BYR (Belarusian ruble)
•
KZT (Kazakhstani tenge)
Parameters nested in models
region-id
Number
ID of the region that information about product modifications is being
output for.
Use the GET regions/{regionId} method to get region information by ID.
currency
String
The currency used for prices of product offers for modifications.
Possible values:
model
•
RUR (Russian ruble)
•
UAH (Ukrainian hrivna)
•
BYR (Belarusian ruble)
•
KZT (Kazakhstani tenge)
Description of a modification.
Parameters nested in model
id
id
Number
ID of the product modification.
name
name
String
Name of the product modification.
Yandex.Market Partner API
Developer's guide
72
Parameter
for XML
format
Parameter
for JSON
format
prices
prices
Type
Value
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.
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.
If no modifications were found that meet the search conditions, the value
of the parameter is "0".
to
to
Number
Index number of the modification at the end of the search results page
to output.
If no modifications were found that meet the search conditions, the value
of the parameter is "0".
currentpage
currentPage Number
Page number in search results to output.
If no modifications were found that meet the search conditions, the value
of the parameter is "0".
pages-count pagesCount
Number
The number of pages with results.
If no modifications were found that meet the search conditions, the value
of the parameter is "0".
page-size
pageSize
Number
The number of modifications to output on a page.
If no modifications were found that meet the search conditions, the value
of the parameter is "0".
Prior to version 2.0 of the Yandex.Market Partner API, the parameter
was called on-page in XML format, and onPage in JSON format.
Error descriptions
If an error occurs, the server returns the HTTP response code and a brief error description.
Errors containing brief descriptions typical for this method:
Description
Explanation
Possible solution
Unsupported currency:
'currency'
The currency specified in the
request is not supported.
Check whether the correct currency code
is being passed in the request.
Invalid regionId:
'regionId'
The region with the specified
regionId was not found.
Check whether the region ID is correct.
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.
Error 400 Bad 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.
Yandex.Market Partner API
Developer's guide
73
Restrictions
For the methods GET models/{modelId}, GET models, and POST models, a group resource limit is applied.
The limit is applied to the total number of modifications 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
and depends on the following factors:
•
The number of offers on product profiles.
•
How many active campaigns the client has.
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.
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.xml?query=iPhone+4s&regionId=2
Sample response:
<?xml version="1.0" encoding="UTF-8"?>
<response>
<models region-id="2" currency="RUR">
<model id="7717706" name="Apple iPhone 4S 16Gb">
<prices min="21500" max="68400" avg="24990">
</model>
<model id="7717686" name="Apple iPhone 4S 32Gb">
<prices min="24450" max="46000" avg="28500">
</model>
<model id="7717687" name="Apple iPhone 4S 64Gb">
<prices min="27200" max="89950" avg="32500">
</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:
Yandex.Market Partner API
Developer's guide
74
{"models":
[
{"id":7717706,
"name":"Apple iPhone 4S 16Gb",
"prices":{"min":21500,"max":68400,"avg":24990}
},
{"id":7717686,
"name":"Apple iPhone 4S 32Gb",
"prices":{"min":24450,"max":46000,"avg":28500}
},
{"id":7717687,
"name":"Apple iPhone 4S 64Gb",
"prices":{"min":27200,"max":89950,"avg":32500}
}
],
"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:
This method is available starting from version 1.2 of the Yandex.Market Partner API.
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
Use the GET regions method to get the region ID.
Optional
currency
String
The currency used for product offer prices for modifications.
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.
Structure of the body of the POST request:
Yandex.Market Partner API
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.
Parameters nested in models
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.
Structure of output data:
XML
<models region-id="{number}" currency="{string}">
<model id="{number}" name="{string}">
<prices min="{number}" max="{number}" avg="{number}">
</model>
...
</models>
Yandex.Market Partner API
Developer's guide
76
JSON
{
"models":
[
{
"id":{number},
"name":"{string}",
"prices":
{
"min":{number},
"max":{number},
"avg":{number}
}
},
...
],
"regionId":{number},
"currency":"{string}"
}
Parameter descriptions:
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
ID of the region that information about product modifications is being
output for.
Use the GET regions/{regionId} method to get region information by ID.
currency
String
The currency used for prices of product offers for modifications.
Possible values:
•
RUR (Russian ruble)
•
UAH (Ukrainian hrivna)
•
BYR (Belarusian ruble)
•
KZT (Kazakhstani tenge)
Parameters nested in models
region-id
Number
ID of the region that information about product modifications is being
output for.
Use the GET regions/{regionId} method to get region information by ID.
currency
String
The currency used for prices of product offers for modifications.
Possible values:
model
•
RUR (Russian ruble)
•
UAH (Ukrainian hrivna)
•
BYR (Belarusian ruble)
•
KZT (Kazakhstani tenge)
Description of a modification.
Parameters nested in model
id
id
Number
ID of the product modification.
name
name
String
Name of the product modification.
Yandex.Market Partner API
Developer's guide
77
Parameter
for XML
format
Parameter
for JSON
format
prices
prices
Type
Value
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
If an error occurs, the server returns the HTTP response code and a brief error description.
Errors containing brief descriptions typical for this method:
Description
Explanation
Possible solution
Unsupported currency:
'currency'
The currency specified in the
request is not supported.
Check whether the correct currency code
is being passed in the request.
Invalid regionId:
'regionId'
The region with the specified
regionId was not found.
Check whether the region ID is correct.
Models ids not
specified
The request body does not specify
the modification IDs.
Check the validity of the request body.
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.
Error 400 Bad Request
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}, GET models, and POST models, a group resource limit is applied.
The limit is applied to the total number of modifications 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
and depends on the following factors:
•
The number of offers on product profiles.
•
How many active campaigns the client has.
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.
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.
Yandex.Market Partner API
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:
<?xml version="1.0" encoding="UTF-8"?>
<response>
<models region-id="2" currency="RUR">
<model id="7717706" name="Apple iPhone 4S 16Gb">
<prices min="21500" max="68400" avg="24990">
</model>
<model id="7717686" name="Apple iPhone 4S 32Gb">
<prices min="24450" max="46000" avg="28500">
</model>
<model id="7717687" name="Apple iPhone 4S 64Gb">
<prices min="27200" max="89950" avg="32500">
</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,
"name":"Apple iPhone 4S 16Gb",
"prices":{"min":21500,"max":68400,"avg":24990}
},
{"id":7717686,
"name":"Apple iPhone 4S 32Gb",
"prices":{"min":24450,"max":46000,"avg":28500}
},
{"id":7717687,
"name":"Apple iPhone 4S 64Gb",
"prices":{"min":27200,"max":89950,"avg":32500}
}
],
"regionId":2,
"currency":"RUR"
}
Yandex.Market Partner API
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:
This method is available starting from version 1.2 of the Yandex.Market Partner API.
Resource URL:
https://api.partner.market.yandex.ru/v2/models/{modelId}/offers.[format]
Input data
Parameter
Type
Value
modelId
Number
ID of the product modification.
regionId
Number
ID of the region that information about product offers for a modification is being requested
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.
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
Structure of output data:
Yandex.Market Partner API
Developer's guide
80
XML
<models region-id="{number}" currency="{string}">
<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},
"regionId":{number},
"shippingCost":{number},
"inStock":{number},
"shopName":"{string}",
"shopRating":{number}
},
...
],
"onlineOffers":{number},
"offlineOffers":{number}
}
],
"regionId":{number},
"currency":"{string}"
}
Parameter descriptions:
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).
Use the GET regions/{regionId} method to get region information by ID.
currency
String
The currency used for prices of product offers for the modification.
Possible values:
•
RUR (Russian ruble)
•
UAH (Ukrainian hrivna)
•
BYR (Belarusian ruble)
•
KZT (Kazakhstani tenge)
Parameters nested in models
region-id
Yandex.Market Partner API
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
Use the GET regions/{regionId} method to get region information by ID.
currency
String
The currency used for prices of product offers for the modification.
Possible values:
model
•
RUR (Russian ruble)
•
UAH (Ukrainian hrivna)
•
BYR (Belarusian ruble)
•
KZT (Kazakhstani tenge)
Description of a modification.
Parameters nested in model
id
id
offers
offers
Number
ID of the product modification.
List of the top ten product offers placed on the product profile.
Parameters nested in offers
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.
Parameters nested in offer
pos
pos
Number
The product offer's position in Yandex.Market output on the product
profile.
name
name
String
Name of the product offer.
price
price
Number
Price of the product offer.
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.
Yandex.Market Partner API
Developer's guide
82
Error descriptions
If an error occurs, the server returns the HTTP response code and a brief error description.
Errors containing brief descriptions typical for this method:
Description
Explanation
Possible solution
Unsupported currency:
'currency'
The currency specified in the
request is not supported.
Check whether the correct currency code
is being passed in the request.
Invalid regionId:
'regionId'
The region with the specified
regionId was not found.
Check whether the region ID is correct.
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 400 Bad Request
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.
The limit is applied to the total number of modifications 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
and depends on the following factors:
•
The number of offers on product profiles.
•
How many active campaigns the client has.
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.
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/offers.xml?regionId=213
Sample response:
<?xml version="1.0" encoding="UTF-8"?>
<response>
<models region-id="213" currency="RUR">
<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"
Yandex.Market Partner API
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"/>
<offer pos="5" name="Samsung I9100 Galaxy S II" price="21770" region-id="213"
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},
{"pos":5,"name":"Samsung I9100 Galaxy S II","price":21770,"regionId":
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
Yandex.Market Partner API
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:
This method is available starting from version 1.2 of the Yandex.Market Partner API.
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
Use the GET regions method to get the region ID.
Optional
currency
String
The currency used for product offer prices for modifications.
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.
Structure of the body of the POST request:
XML
<models>
<id>{number}</id>
...
</models>
JSON
{
"models":
[
{number},
...
]
}
Yandex.Market Partner API
Developer's guide
85
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.
Parameters nested in models
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.
Structure of output data:
XML
<models region-id="{number}" currency="{string}">
<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},
"regionId":{number},
"shippingCost":{number},
"inStock":{number},
"shopName":"{string}",
"shopRating":{number}
},
...
],
"onlineOffers":{number},
"offlineOffers":{number}
},
...
],
"regionId":{number},
"currency":"{string}"
}
Yandex.Market Partner API
Developer's guide
86
Parameter descriptions:
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.
Use the GET regions/{regionId} method to get region information by ID.
currency
String
The currency used for prices of product offers for modifications.
Possible values:
•
RUR (Russian ruble)
•
UAH (Ukrainian hrivna)
•
BYR (Belarusian ruble)
•
KZT (Kazakhstani tenge)
Parameters nested in models
region-id
Number
ID of the region that information about product offers for modifications
is output for.
Use the GET regions/{regionId} method to get region information by ID.
currency
String
The currency used for prices of product offers for modifications.
Possible values:
model
•
RUR (Russian ruble)
•
UAH (Ukrainian hrivna)
•
BYR (Belarusian ruble)
•
KZT (Kazakhstani tenge)
Description of a modification.
Parameters nested in model
id
id
offers
offers
Number
ID of the product modification.
List of the top ten product offers placed on the product profile.
Parameters nested in offers
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.
Parameters nested in offer
pos
pos
Number
The product offer's position in Yandex.Market output on the product
profile.
name
name
String
Name of the product offer.
price
price
Number
Price of the product offer.
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.
Yandex.Market Partner API
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
If an error occurs, the server returns the HTTP response code and a brief error description.
Errors containing brief descriptions typical for this method:
Description
Explanation
Possible solution
Unsupported currency:
'currency'
The currency specified in the
request is not supported.
Check whether the correct currency code
is being passed in the request.
Invalid regionId:
'regionId'
The region with the specified
regionId was not found.
Check whether the region ID is correct.
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.
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.
Error 400 Bad Request
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.
The limit is applied to the total number of modifications 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
and depends on the following factors:
•
The number of offers on product profiles.
•
How many active campaigns the client has.
Yandex.Market Partner API
Developer's guide
88
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.
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:
POST https://api.partner.market.yandex.ru/v2/models/offers.xml?regionId=213
Content-Type: application/xml
POST request body:
<models>
<id>7012977</id>
<id>7717686</id>
</models>
Sample response:
<?xml version="1.0" encoding="UTF-8"?>
<response>
<models region-id="213" currency="RUR">
<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"
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"/>
<offer pos="5" name="Samsung I9100 Galaxy S II" price="21770" region-id="213"
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>
<model id="7717686">
<offers online="729" offline="508">
<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"
shipping-cost="0" in-stock="1" shop-name="Piggier.Ru" shop-rating="5"/>
<offer pos="4" name="Apple iPhone 4S 32Gb (white)" price="33990" region-id="213"
shipping-cost="300" in-stock="1" shop-name="Piggiest.Ru" shop-rating="3"/>
<offer pos="5" name="Apple iPhone 4S 32Gb White" price="27700" region-id="213"
shipping-cost="280" in-stock="1" shop-name="Wolf.Ru" shop-rating="5"/>
<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"/>
Yandex.Market Partner API
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
Content-Type: application/json
POST request body:
{"models":
[7012977,7717686]
}
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},
{"pos":5,"name":"Samsung I9100 Galaxy S II","price":21770,"regionId":
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
},
{
"id":7012977,
"offers":
[
{"pos":1,"name":"Smartphone Apple iPhone 4S 32 Gb black","price":38990,"regionId":
213,"shippingCost":290,"inStock":1,"shopName":"Store.Com","shopRating":4},
{"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":
213,"shippingCost":0,"inStock":1,"shopName":"Piggier.Ru","shopRating":5},
{"pos":4,"name":"Apple iPhone 4S 32Gb white","price":33990,"regionId":
213,"shippingCost":300,"inStock":1,"shopName":"Piggiest.Ru","shopRating":3},
{"pos":5,"name":"Apple iPhone 4S 32Gb White","price":27700,"regionId":
213,"shippingCost":280,"inStock":1,"shopName":"Wolf.Ru","shopRating":5},
Yandex.Market Partner API
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":
213,"shippingCost":300,"inStock":1,"shopName":"Cinderella.Ru","shopRating":5},
{"pos":8,"name":"Smartphone Apple iPhone 4S 32Gb White","price":40990,"regionId":
213,"shippingCost":0,"inStock":1,"shopName":"Rapunzel.Ru","shopRating":5},
{"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"
}
Yandex.Market Partner API
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
POST campaigns/{campaignId}/bids
Returns information about bids set for
product offers for the campaign
specified in the request.
Individual number of requests per day;
500 recommendations per request.
PUT campaigns/{campaignId}/bids
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.
Individual number of requests per day;
500 recommendations per request.
PUT campaigns/{campaignId}/bids/
recommended
Sets the recommended bid values
on product offers.
Individual number of requests per day;
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.
Yandex.Market Partner API
Developer's guide
92
Information about bids
Description
POST campaigns/{campaignId}/bids
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:
This method is available starting from version 2.0 of the Yandex.Market Partner API.
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 POST request:
XML
<offers>
<offer id="{string}" feed-id="{number}" name="{string}"/>
...
</offers>
JSON
{
"offers":
[
{
"name":"{string}",
"id":"{string}",
"feedId":{number}
},
...
]
}
The following parameters are passed in the body of the POST request:
Parameter
for XML
format
Parameter
for JSON
format
offers
offers
Type
Value
List of product offers.
Parameters nested in offers
Yandex.Market Partner API
Developer's guide
93
Parameter
for XML
format
Parameter
for JSON
format
Type
offer
Value
Product offer.
Parameters nested in offer
name
name
String
Name of the product offer.
This parameter is specified when getting information about a bid based
on the product offer name.
id
id
String
Product offer ID from the price list.
This parameter is specified when getting information about a bid based
on the product offer ID.
feed-id
feedId
Number
ID of the price list containing the product offer.
This parameter is specified when getting information about a bid based
on the product offer ID, when the campaign has more than one registered
price list.
Output data
Structure of 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 descriptions:
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
Yandex.Market Partner API
offerName
String
Name of the product offer.
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
Product offer ID from the price list.
This parameter is output when getting information about a bid based
on the product offer ID.
feed-id
feedId
Number
ID of the price list containing the product offer.
This parameter is specified when getting information about a bid based
on the product offer ID.
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
If an error occurs, the server returns the HTTP response code and a brief error description.
Errors containing brief descriptions typical for this method:
Description
Explanation
Possible solution
Error 400 Bad Request
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.
Check whether the correct data is being passed
in the request.
Duplicate offers
are not allowed:
'offerName'/'offerId'
The same product offer cannot
be specified more than once.
Check whether the correct data is being passed
in the request.
Feed-id should
be specified
The ID of the price list was not
specified.
Check whether the correct data is being passed
in the request.
Yandex.Market Partner API
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.
Check whether the correct data is being passed
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
access to bid management.
Error 404 Not Found
Feed not found:
'feedId'
The price list specified in the Check whether the correct data is being passed
request was not found.
in the request.
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.
Yandex.Market Partner API
Developer's guide
96
Examples
XML
Sample request:
POST https://api.partner.market.yandex.ru/v2/campaigns/10001/bids.xml
Content-Type: application/xml
POST request body:
<?xml version="1.0" encoding="UTF-8"?>
<offers>
<offer id="120" feed-id="31920"/>
<offer id="121" feed-id="31920"/>
<offer id="122" feed-id="31920"/>
</offers>
Sample response:
<?xml version="1.0" encoding="UTF-8"?>
<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
Content-Type: application/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
PUT campaigns/{campaignId}/bids
Sets or removes bids on product offers.
Yandex.Market Partner API
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":
[
{
"offerId":"{string}",
"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}"
},
...
]
}
Yandex.Market Partner API
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
Name of the product offer.
This parameter is specified when setting a bid based on the product offer
name.
offer-id
offerId
String
Product offer ID from the price list.
This parameter is specified when setting a bid based on the product offer
ID.
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.
This parameter is specified when setting a bid based on the product offer
ID, when the campaign has more than one registered price list.
This parameter is available starting in version 2.0 of the Yandex.Market
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
Structure of output data:
Yandex.Market Partner API
Developer's guide
99
XML
<bids-set>
<offer-bid offer-name="{string}" offer-id="{string}" feed-id="{number}" bid="{number}"
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-name>{string}</offer-name>
</offer-bid>
...
</bids-set>
JSON
{
"bidsSet":
[
{
"offerId":"239982",
"feedId":30919,
"offerName":"{string}",
"bid":{number},
"cbid":{number},
"error":"{string}"
},
...
]
}
Output data structure prior to version 2.0 of the Yandex.Market Partner API
{
"bids-set":
[
{
"offerName":"{string}",
"bid":{number},
"cbid":{number},
"error":"{string}"
},
...
]
}
Parameter descriptions:
Parameter
for XML
format
Parameter
for JSON
format
bids-set
bidsSet
Type
Value
List of set bids.
Prior to version 2.0 of the Yandex.Market Partner API, the parameter
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
Name of the product offer.
This parameter is output when setting a bid based on the product offer
ID.
offer-id
Yandex.Market Partner API
offerId
String
Product offer ID from the price list.
Developer's guide
100
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
This parameter is output when setting a bid based on the product offer
ID.
feed-id
feedId
Number
ID of the price list containing the product offer.
This parameter is specified when setting a bid based on the product offer
ID.
bid
bid
Number
The set basic bid, in Yandex units.
cbid
cbid
Number
The set bid for the product profile, in Yandex units.
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
If an error occurs, the server returns the HTTP response code and a brief error description.
Errors containing brief descriptions typical for this method:
Description
Explanation
Possible solution
Error 400 Bad Request
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.
Offer name should not be The name of the product offer
empty
passed in the request body must
not be empty.
Check whether the correct data is being passed
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
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 and the
selected bid setting mode uses
the product offer ID.
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.
Check for duplicated product offers in the data
being passed in the request body.
Error 403 Forbidden
Auction is not allowed
for campaign
'campaignId'. Reason:
'reason'
Yandex.Market Partner API
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.
Developer's guide
101
Description
Explanation
Possible solution
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
access to bid management.
Error 404 Not Found
Feed not found:
'feedId'
The price list specified in the Check whether the correct data is being passed
request was not found.
in the request.
Restrictions
For the methods PUT campaigns/{campaignId}/bids, POST campaigns/{campaignId}/bids/recommended,
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.
The volume 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 offers on product profiles.
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 when setting bids by product offer ID:
PUT https://api.partner.market.yandex.ru/v2/campaigns/10001/bids.xml
Content-Type: application/xml
Body of the PUT request:
<?xml version="1.0" encoding="UTF-8"?>
<offer-bids>
<offer-bid offer-id="239982" feed-id="30919" bid="0.22" cbid="0.33"/>
<offer-bid offer-id="239983" feed-id="30919" bid="0.22" cbid="0.27"/>
<offer-bid offer-id="239984" feed-id="30919" bid="0.22" cbid="0.15"/>
</offer-bids>
Sample response:
Yandex.Market Partner API
Developer's guide
102
<?xml version="1.0" encoding="UTF-8"?>
<response>
<bids-set>
<offer-bid offer-id="239982" feed-id="30919" bid="0.22" cbid="0.33"/>
<offer-bid offer-id="239983" feed-id="30919" bid="0.22" cbid="0.27"/>
<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
Content-Type: application/xml
Body of the PUT request:
<?xml version="1.0" encoding="UTF-8"?>
<offer-bids>
<offer-bid bid="0.4" cbid="0.33">
<offer-name>Bosch MSM 6B300</offer-name>
</offer-bid>
<offer-bid bid="0.35" cbid="0.27">
<offer-name>Tefal HB 7151</offer-name>
</offer-bid>
<offer-bid bid="0.18" cbid="0.15">
<offer-name>Philips HR 1371</offer-name>
</offer-bid>
</offer-bids>
Sample response:
<?xml version="1.0" encoding="UTF-8"?>
<response>
<bids-set>
<offer-bid bid="0.4" cbid="0.33">
<offer-name>Bosch MSM 6B300</offer-name>
</offer-bid>
<offer-bid bid="0.35" cbid="0.27">
<offer-name>Tefal HB 7151</offer-name>
</offer-bid>
<offer-bid bid="0.18" cbid="0.15" error="OFFER_NOT_FOUND">
<offer-name>Philips HR 1371</offer-name>
</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
Content-Type: application/json
Body of the PUT request:
{"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"}
]}
Sample request prior to version 2.0 of the Yandex.Market Partner API
PUT https://api.partner.market.yandex.ru/v1/campaigns/10001/bids.json
Content-Type: application/json
Body of the PUT request:
Yandex.Market Partner API
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.
This parameter is available starting in version 2.0 of the Yandex.Market Partner API.
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.
Yandex.Market Partner API
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.
Structure of the body of the POST request:
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>
<name>{string}</name>
...
</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}",
...
]
}
The following parameters are passed in the body of the POST request:
Parameter
for XML
format
Parameter
for JSON
format
offers
offers
Type
Value
List of product offers.
Parameters nested in offers
offer
Product offer.
Parameters nested in offer
name
name
String
Name of the product offer.
This parameter is specified when requesting bids based on the product
offer name.
Yandex.Market Partner API
Developer's guide
105
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
id
id
String
Product offer ID from the price list.
This parameter is specified when requesting bids based on the product
offer ID.
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.
This parameter is specified when requesting bids based on the product
offer ID, when the campaign has more than one registered price list.
This parameter is available starting in version 2.0 of the Yandex.Market
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.
This parameter is available starting in version 2.0 of the Yandex.Market
Partner API.
Output data
Structure of output data:
XML
<recommendations>
<offer id="{string}" feed-id="{number}" error="{string}">
<name>{string}</name>
<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>
Output data structure for XML format prior to version 2.0 of the Yandex.Market Partner API
<recommendations>
<offer error="{string}">
<name>{string}</name>
<model-card offer-position="{number}">
<position pos="{number}" cbid="{number}" error="{string}"></position>
...
</model-card>
</offer>
...
</recommendations>
JSON
{
"recommendations":
[
{
"offerId":"{string}",
"feedId":{number},
"offerName":"{string}",
"modelCard":
{
"error":"{string}",
Yandex.Market Partner API
Developer's guide
106
"offerPosition":{number},
"posRecommendations":
{
"{number}":
{
"cbid":{number},
"error":"{string}"
},
...
}
},
"search":
{
"error":"{string}",
"posRecommendations":
{
"{number}":
{
"bid":{number},
"error":"{string}"
},
...
}
}
},
...
]
}
Output data structure for JSON format prior to version 2.0 of the Yandex.Market Partner API
{
"recommendations":
[
{
"offerName":"{string}",
"modelCard":
{
"error":"{string}",
"offerPosition":{number},
"posRecommendations":
{
"{number}":
{
"cbid":{number},
"error":"{string}"
},
...
}
}
},
...
]
}
Parameter descriptions:
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.
Parameters nested in offer
name
offerName
String
Name of the product offer.
This parameter is output when requesting bids based on the product offer
name.
Yandex.Market Partner API
Developer's guide
107
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
offer-id
offerId
String
Product offer ID from the price list.
This parameter is output when requesting bids based on the product offer
ID.
feed-id
feedId
Number
ID of the price list containing the product offer.
This parameter is specified when requesting bids based on the product
offer ID.
error
String
Code of the error that occurred. The parameter is output only if an error
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.
•
OFFER_NOT_FOUND — The product offer has not been
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
Code of the error that occurred. The parameter is output only if an error
occurred.
Possible values:
•
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.
•
OFFER_NOT_FOUND — The product offer has not been
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
Yandex.Market Partner API
String
Code of the error that occurred. The parameter is output only if an error
occurred.
Developer's guide
108
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
Possible values:
position
posRecommen
dations
•
OFFER_NOT_DELIVERED — The position indicated in the
request is impossible because the product offer is not delivered to the
region.
•
OFFER_NOT_FOUND — The product offer has not been
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
Code of the error that occurred. The parameter is output only if an error
occurred.
Possible values:
•
BID_UPPER_LIMIT — The position indicated in the request
is impossible because a competitor has set the maximum bid.
Error descriptions
If an error occurs, the server returns the HTTP response code and a brief error description.
Errors containing brief descriptions typical for this method:
Description
Explanation
Possible solution
Error 400 Bad Request
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.
Check whether the correct data is being passed
in the request.
Too many positions
specified
Reduce the number of positions in the
positions parameter.
Yandex.Market Partner API
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.
Position number should
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.
correctly in the request.
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 and the
selected bid setting mode uses
the product offer ID.
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.
Error 403 Forbidden
Auction is not allowed
for campaign
'campaignId'. Reason:
'reason'
Bids cannot be set or removed Bid management is not available.
for the campaign campaignId
because of reason.
Possible reasons:
•
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
access to bid management.
Error 404 Not Found
Feed not found:
'feedId'
The price list specified in the Check whether the correct data is being passed
request was not found.
in the request.
Restrictions
For the methods PUT campaigns/{campaignId}/bids, POST campaigns/{campaignId}/bids/recommended,
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.
The volume 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 offers on product profiles.
Note:
The number of product offers is based on data from the past seven days (not including today).
Yandex.Market Partner API
Developer's guide
110
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.
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
Content-Type: application/xml
POST request body:
<?xml version="1.0" encoding="UTF-8"?>
<offers>
<offer name="Pioneer AVH-P6300BT"/>
<offer name="Mystery MCD-695MPU"/>
<offer name="Braun HD750"/>
</offers>
Sample response:
<?xml version="1.0" encoding="UTF-8"?>
<response>
<recommendations>
<offer>
<name>Pioneer AVH-P6300BT</name>
<model-card offer-position="4">
<position pos="1" cbid="0.21"></position>
<position pos="2" cbid="0.16"></position>
<position pos="3" cbid="0.13"></position>
<position pos="4" cbid="0.12"></position>
<position pos="5" cbid="0.12"></position>
</model-card>
</offer>
<offer>
<name>Mystery MCD-695MPU</name>
<model-card offer-position="3">
<position pos="1" cbid="0.15"></position>
<position pos="2" cbid="0.13"></position>
<position pos="3" cbid="0.12"></position>
<position pos="4" cbid="0.12"></position>
<position pos="5" cbid="0.11"></position>
</model-card>
</offer>
<offer>
<name>Braun HD750</name>
<model-card offer-position="8">
<position pos="1" cbid="0.67"></position>
<position pos="2" cbid="0.63"></position>
<position pos="3" cbid="0.41"></position>
<position pos="4" cbid="0.31"></position>
<position pos="5" cbid="0.31"></position>
</model-card>
</offer>
</recommendations>
</response>
Sample request for getting recommended bids by product offer ID:
POST https://api.partner.market.yandex.ru/v2/campaigns/10001/bids/
recommended.xml?target=model-card
Content-Type: application/xml
POST request body:
Yandex.Market Partner API
Developer's guide
111
<?xml version="1.0" encoding="UTF-8"?>
<offers>
<offer id="239982" feed-id="30919"/>
<offer id="239983" feed-id="30919"/>
<offer id="239984" feed-id="30919"/>
</offers>
Sample response:
<?xml version="1.0" encoding="UTF-8"?>
<response>
<recommendations>
<offer id="239982" feed-id="30919">
<model-card offer-position="4">
<position pos="1" cbid="0.21"></position>
<position pos="2" cbid="0.16"></position>
<position pos="3" cbid="0.13"></position>
<position pos="4" cbid="0.12"></position>
<position pos="5" cbid="0.12"></position>
</model-card>
</offer>
<offer id="239983" feed-id="30919">
<name>Mystery MCD-695MPU</name>
<model-card offer-position="3">
<position pos="1" cbid="0.15"></position>
<position pos="2" cbid="0.13"></position>
<position pos="3" cbid="0.12"></position>
<position pos="4" cbid="0.12"></position>
<position pos="5" cbid="0.11"></position>
</model-card>
</offer>
<offer id="239984" feed-id="30919">
<name>Braun HD750</name>
<model-card offer-position="8">
<position pos="1" cbid="0.67"></position>
<position pos="2" cbid="0.63"></position>
<position pos="3" cbid="0.41"></position>
<position pos="4" cbid="0.31"></position>
<position pos="5" cbid="0.31"></position>
</model-card>
</offer>
</recommendations>
</response>
Sample request prior to version 2.0 of the Yandex.Market Partner API
POST https://api.partner.market.yandex.ru/v1/campaigns/10001/bids/
recommended.xml
Content-Type: application/xml
POST request body:
<?xml version="1.0" encoding="UTF-8"?>
<offers>
<name>Pioneer AVH-P6300BT</name>
<name>Mystery MCD-695MPU</name>
<name>Braun HD750</name>
</offers>
Sample response:
<?xml version="1.0" encoding="UTF-8"?>
<response>
<recommendations>
<offer>
<name>Pioneer AVH-P6300BT</name>
<model-card offer-position="4">
<position pos="1" cbid="0.21"></position>
<position pos="2" cbid="0.16"></position>
<position pos="3" cbid="0.13"></position>
<position pos="4" cbid="0.12"></position>
Yandex.Market Partner API
Developer's guide
112
<position pos="5" cbid="0.12"></position>
</model-card>
</offer>
<offer>
<name>Mystery MCD-695MPU</name>
<model-card offer-position="3">
<position pos="1" cbid="0.15"></position>
<position pos="2" cbid="0.13"></position>
<position pos="3" cbid="0.12"></position>
<position pos="4" cbid="0.12"></position>
<position pos="5" cbid="0.11"></position>
</model-card>
</offer>
<offer>
<name>Braun HD750</name>
<model-card offer-position="8">
<position pos="1" cbid="0.67"></position>
<position pos="2" cbid="0.63"></position>
<position pos="3" cbid="0.41"></position>
<position pos="4" cbid="0.31"></position>
<position pos="5" cbid="0.31"></position>
</model-card>
</offer>
</recommendations>
</response>
Sample for JSON format
Sample request for getting recommended bids by product offer name:
POST https://api.partner.market.yandex.ru/v2/campaigns/10001/bids/
recommended.json?target=model-card
Content-Type: application/json
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,
"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":3,
"posRecommendations":
Yandex.Market Partner API
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,
"posRecommendations":
{
"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:
POST https://api.partner.market.yandex.ru/v2/campaigns/10001/bids/
recommended.json?target=model-card
Content-Type: application/json
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,
"posRecommendations":
{
"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,
"posRecommendations":
Yandex.Market Partner API
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,
"posRecommendations":
{
"1":{"cbid":0.67},
"2":{"cbid":0.63},
"3":{"cbid":0.41},
"4":{"cbid":0.31},
"5":{"cbid":0.31}
}
}
}
]
}
Sample request prior to version 2.0 of the Yandex.Market Partner API
POST https://api.partner.market.yandex.ru/v1/campaigns/10001/bids/
recommended.json
Content-Type: application/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":
3,"posRecommendations":{"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,"posRecommendations":{"1":{"cbid":0.67},"2":{"cbid":0.63},"3":{"cbid":
0.41},"4":{"cbid":0.31},"5":{"cbid":0.31}}}}
]
}
Setting recommended bids
Description
PUT campaigns/{campaignId}/bids/recommended
Yandex.Market Partner API
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.
This parameter is available starting in version 2.0 of the Yandex.Market Partner API.
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
Yandex.Market Partner API
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>
<name>{string}</name>
...
</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
List of product offers.
Parameters nested in offers
offer
Product offer.
Parameters nested in offer
name
name
String
Name of the product offer.
This parameter is specified when setting a bid based on the product offer
name.
id
id
String
Product offer ID from the price list.
This parameter is specified when setting a bid based on the product offer
ID.
Yandex.Market Partner API
Developer's guide
117
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
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.
This parameter is specified when setting a bid based on the product offer
ID, when the campaign has more than one registered price list.
This parameter is available starting in version 2.0 of the Yandex.Market
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.
This parameter is available starting in version 2.0 of the Yandex.Market
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
Structure of output data:
XML
<bids-set>
<offer-bid offer-name="{string}" offer-id="{string}" feed-id="{number}" bid="{number}"
cbid="{number}" error="{string}"/>
...
</bids-set>
Output data structure for XML format prior to version 2.0 of the Yandex.Market Partner API
<bids-set>
<offer-bid cbid="{number}" error="{string}">
<offer-name>{string}</offer-name>
</offer-bid>
...
</bids-set>
Yandex.Market Partner API
Developer's guide
118
JSON
{
"bidsSet":
[
{
"id":"{string}",
"feedId":{number},
"offerName":"{string}",
"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":
[
{
"offerName":"{string}",
"cbid":{number},
"error":"{string}"
},
...
]
}
Parameter descriptions:
Parameter
for XML
format
Parameter
for JSON
format
bids-set
bidsSet
Type
Value
List of set bids.
Prior to version 2.0 of the Yandex.Market Partner API, the parameter
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 of the product offer.
This parameter is output when setting a bid based on the product offer
name.
offer-id
offerId
String
Product offer ID from the price list.
This parameter is output when setting a bid based on the product offer
ID.
feed-id
feedId
Number
ID of the price list containing the product offer.
This parameter is specified when setting a bid based on the product offer
ID.
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.
Yandex.Market Partner API
Developer's guide
119
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
error
error
String
Code of the error that occurred. The parameter is output only if an error
occurred.
Possible values:
•
BID_UPPER_LIMIT — The position indicated in the request
is impossible because a competitor has set the maximum bid.
•
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.
•
OFFER_NOT_FOUND — The product offer has not been
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
If an error occurs, the server returns the HTTP response code and a brief error description.
Errors containing brief descriptions typical for this method:
Description
Explanation
Possible solution
Error 400 Bad Request
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.
Check whether the correct data is being passed
in the request.
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.
Invalid position
number: 'position'
The position specified in the request Check whether the positions are specified
is not a number.
correctly in the request.
Invalid maxBid value:
'maxBid'
The value of the maxBid
parameter specified in the request
is invalid.
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 and the
selected bid setting mode uses
the product offer ID.
Yandex.Market Partner API
Check whether the maxBid parameter is set
correctly in the request.
Developer's guide
120
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.
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
access to bid management.
Error 404 Not Found
Feed not found:
'feedId'
The price list specified in the Check whether the correct data is being passed
request was not found.
in the request.
Restrictions
For the methods PUT campaigns/{campaignId}/bids, POST campaigns/{campaignId}/bids/recommended,
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.
The volume 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 offers on product profiles.
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 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
Content-Type: application/xml
Body of the PUT request:
Yandex.Market Partner API
Developer's guide
121
<?xml version="1.0" encoding="UTF-8"?>
<offers>
<offer id="239982" feed-id="30919"/>
<offer id="239983" feed-id="30919"/>
<offer id="239984" feed-id="30919"/>
</offers>
Sample response:
<?xml version="1.0" encoding="UTF-8"?>
<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>
Sample request prior to version 2.0 of the Yandex.Market Partner API
PUT https://api.partner.market.yandex.ru/v1/campaigns/10001/bids/recommended.xml?
position=5
Content-Type: application/xml
Body of the PUT request:
<?xml version="1.0" encoding="UTF-8"?>
<offers>
<name>Bosch MSM 6B300</name>
<name>Tefal HB 7151</name>
<name>Philips HR 1371</name>
</offers>
Sample response:
<?xml version="1.0" encoding="UTF-8"?>
<response>
<bids-set>
<offer-bid cbid="0.33">
<offer-name>Bosch MSM 6B300</offer-name>
</offer-bid>
<offer-bid cbid="0.27">
<offer-name>Tefal HB 7151</offer-name>
</offer-bid>
<offer-bid error="OFFER_NOT_FOUND">
<offer-name>Philips HR 1371</offer-name>
</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
Content-Type: application/json
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"}
]}
Sample request prior to version 2.0 of the Yandex.Market Partner API
PUT https://api.partner.market.yandex.ru/v1/campaigns/10001/bids/recommended.json?
position=5
Content-Type: application/json
Yandex.Market Partner API
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:
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}/bids/settings.
[format]
Input data
Parameter
Type
Value
Number
The campaign ID.
Mandatory
campaignId
Output data
Structure of output data:
XML
<settings bids-from="{string}" offer-id-by="{string}" autobroker-enabled="{boolean}"/>
JSON
{
"settings":
{
bidsFrom:"{string}",
offerIdBy:"{string}",
autobrokerEnabled:{boolean}
}
}
Yandex.Market Partner API
Developer's guide
123
Parameter descriptions:
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
If an error occurs, the server returns the HTTP response code and a brief error description.
Errors containing brief descriptions typical for this method:
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 http://api.partner.market.yandex.ru/v2/campaigns/10001/bids/settings.xml
Sample response:
<?xml version="2.0" encoding="UTF-8"?>
<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}}
Yandex.Market Partner API
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
10000 requests per day.
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
Structure of output data:
XML
<balance balance="{number}" days-left="{number}" recommended-payment="{number}"></
balance>
Output data structure for XML format prior to version 2.0 of the Yandex.Market Partner API
<balance>
<balance balance="{number}" days-left="{number}" recommended-payment="{number}"/>
</balance>
JSON
{
"balance":
{
"balance":{number},
"daysLeft":{number},
"recommendedPayment":{number}
}
}
Yandex.Market Partner API
Developer's guide
125
Parameter descriptions:
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
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/10002/balance.xml
Sample response:
<?xml version="1.0" encoding="UTF-8"?>
<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}}
Yandex.Market Partner API
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
10000 requests per day.
(clicks and expenditures) for the
specified period of time. Statistics
are output for each day. Maximum time
period that may be specified: 180 days.
GET campaigns/{campaignId}/stats/
main-daily
Returns basic campaign statistics
10000 requests per day.
(clicks and expenditures) for the
specified period of time. Statistics
are output for each day. Maximum time
period that may be specified: 180 days.
GET campaigns/{campaignId}/stats/
main-weekly
Returns basic campaign statistics
10000 requests per day.
(clicks and expenditures) for the
specified period of time. Statistics
are output by week. Maximum time
period that may be specified: 180 days.
GET campaigns/{campaignId}/stats/
main-monthly
Returns basic campaign statistics
10000 requests per day.
(clicks and expenditures) for the
specified period of time. Statistics
are output by month. Maximum time
period that may be specified: 180 days.
GET campaigns/{campaignId}/stats/
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.
Yandex.Market Partner API
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.
Date format: DD-MM-YYYY.
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
Structure of output data:
Yandex.Market Partner API
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 descriptions:
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).
Prior to version 2.0 of the Yandex.Market Partner API, the parameter
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.
Yandex.Market Partner API
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
If an error occurs, the server returns the HTTP response code and a brief error description.
Errors containing brief descriptions typical for this method:
Description
Explanation
Possible solution
The report period that statistics
were requested for exceeds
the maximum report period:
maxPeriod.
Make the report period shorter.
Error 400 Bad Request
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:
<?xml version="1.0" encoding="UTF-8"?>
<response>
<main-stats>
<main-stats-item date="2011-11-22"
spending="11452.41"/>
<main-stats-item date="2011-11-23"
spending="11805.57"/>
<main-stats-item date="2011-11-24"
spending="11730.09"/>
<main-stats-item date="2011-11-25"
spending="10206.59"/>
<main-stats-item date="2011-11-26"
>
<main-stats-item date="2011-11-27"
>
<main-stats-item date="2011-11-28"
>
</main-stats>
</response>
place-group="0" clicks="39251"
place-group="0" clicks="39578"
place-group="0" clicks="39123"
place-group="0" clicks="36857"
place-group="0" clicks="30635" spending="7516.03"/
place-group="0" clicks="33455" spending="8336.42"/
place-group="0" clicks="14487" spending="3798.01"/
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:
Yandex.Market Partner API
Developer's guide
130
{"mainStats":[
{"date":"2011-11-22","placeGroup":0,"clicks":39251,"spending":11452.41},
{"date":"2011-11-23","placeGroup":0,"clicks":39578,"spending":11805.57},
{"date":"2011-11-24","placeGroup":0,"clicks":39123,"spending":11730.09},
{"date":"2011-11-25","placeGroup":0,"clicks":36857,"spending":10206.59},
{"date":"2011-11-26","placeGroup":0,"clicks":30635,"spending":7516.03},
{"date":"2011-11-27","placeGroup":0,"clicks":33455,"spending":8336.42},
{"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:
<?xml version="1.0" encoding="UTF-8"?>
<response>
<main-stats>
<main-stats-item date="2011-11-22"
spending="11452.41"/>
<main-stats-item date="2011-11-23"
spending="11805.57"/>
<main-stats-item date="2011-11-24"
spending="11730.09"/>
<main-stats-item date="2011-11-25"
spending="10206.59"/>
<main-stats-item date="2011-11-26"
>
<main-stats-item date="2011-11-27"
>
<main-stats-item date="2011-11-28"
>
</main-stats>
</response>
place-group="0" clicks="39251"
place-group="0" clicks="39578"
place-group="0" clicks="39123"
place-group="0" clicks="36857"
place-group="0" clicks="30635" spending="7516.03"/
place-group="0" clicks="33455" spending="8336.42"/
place-group="0" clicks="14487" spending="3798.01"/
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":[
{"date":"2011-11-22","placeGroup":0,"clicks":39251,"spending":11452.41},
{"date":"2011-11-23","placeGroup":0,"clicks":39578,"spending":11805.57},
{"date":"2011-11-24","placeGroup":0,"clicks":39123,"spending":11730.09},
{"date":"2011-11-25","placeGroup":0,"clicks":36857,"spending":10206.59},
{"date":"2011-11-26","placeGroup":0,"clicks":30635,"spending":7516.03},
{"date":"2011-11-27","placeGroup":0,"clicks":33455,"spending":8336.42},
{"date":"2011-11-28","placeGroup":0,"clicks":14487,"spending":3798.01}
]}
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:
Yandex.Market Partner API
Developer's guide
131
<?xml version="1.0" encoding="UTF-8"?>
<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":[
{"date":"2011-11-21","placeGroup":0,"clicks":218899,"spending":61047.11},
{"date":"2011-11-28","placeGroup":0,"clicks":14487,"spending":3798.01}
]}
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:
<?xml version="1.0" encoding="UTF-8"?>
<response>
<main-stats>
<main-stats-item date="2011-11-01" place-group="0" clicks="328791"
spending="740217.05"/>
<main-stats-item date="2011-12-01" place-group="0" clicks="412203"
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":[
{"date":"2011-11-01","placeGroup":0,"clicks":328791,"spending":740217.05},
{"date":"2011-12-01","placeGroup":0,"clicks":412203,"spending":93305.33}
]}
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.
Yandex.Market Partner API
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
Date format: DD-MM-YYYY.
Optional
toDate
Date
End date of the report period.
Date format: DD-MM-YYYY.
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.
This parameter is available starting in version 2.0 of the Yandex.Market Partner API.
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.
This parameter is available starting in version 2.0 of the Yandex.Market Partner API.
pageSize
Number
The number of offers to output on the page with search results in the response.
Default value: 10 offers.
page
Number
Page number in results.
If omitted, the first page is output.
Output data
Structure of output data:
Yandex.Market Partner API
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-name>{string}</offer-name>
</offer-stats>
...
</offers-stats>
Output data structure prior to version 2.0 of the Yandex.Market Partner API
<offers-stats>
<offers-stats total-offers-count="{number}" from-offer="{number}" tooffer="{number}">
<offer-stats clicks="{number}" spending="{number}">
<offer-name>{string}</offer-name>
</offer-stats>
...
</offers-stats>
</offers-stats>
JSON
{
"offersStats":
{
"offerStats":
[
{
"offerName":"{string}",
"clicks":{number},
"spending":{number},
"offerId":{number},
"feedId":{number}
},
...
],
"totalOffersCount":{number},
"fromOffer":{number},
"toOffer":{number}
}
}
Output data structure prior to version 2.0 of the Yandex.Market Partner API
{
"offersStats":
{
"offerStats":
[
{
"offerName":"{string}",
"clicks":{number},
"spending":{number}
},
...
],
"totalOffersCount":{number},
"fromOffer":{number},
"toOffer":{number}
}
}
Parameter descriptions:
Parameter
for XML
format
Parameter
for JSON
format
offersstats
offersStats
Yandex.Market Partner API
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
Name of the product offer.
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
Product offer ID from the price list.
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.
This parameter is available starting in version 2.0 of the Yandex.Market
Partner API.
Error descriptions
If an error occurs, the server returns the HTTP response code and a brief error description.
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/10002/stats/offers.xml?
fromDate=22-11-2011&toDate=28-11-2011
Sample response:
Yandex.Market Partner API
Developer's guide
135
<?xml version="1.0" encoding="UTF-8"?>
<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-stats clicks="204" spending="174.04" feed-id="323204" offerid="002000000009984">
<offer-name>Nokia N9 16GB, Black</offer-name>
</offer-stats>
<offer-stats clicks="203" spending="20.30" feed-id="323204" offerid="002000000002944">
<offer-name>PocketBook IQ 701, Glossy White</offer-name>
</offer-stats>
<offer-stats clicks="194" spending="161.02" feed-id="323204" offerid="002000000004735">
<offer-name>Samsung GT-S5830 Galaxy Ace, Black</offer-name>
</offer-stats>
<offer-stats clicks="172" spending="213.56" feed-id="323204" offerid="002000000001136">
<offer-name>Samsung GT-i9100 Galaxy S II, Noble Black</offer-name>
</offer-stats>
<offer-stats clicks="165" spending="81.67" feed-id="323204" offerid="002000000007564">
<offer-name>Samsung GT-N7000 Galaxy Note</offer-name>
</offer-stats>
<offer-stats clicks="160" spending="78.37" feed-id="323204" offerid="002000000001607">
<offer-name>Samsung GT-i9001 Galaxy S Plus 8GB, Metallic Black</offer-name>
</offer-stats>
<offer-stats clicks="96" spending="10.17" feed-id="323204" offerid="002000000000243">
<offer-name>Tamara Globa "Complete horoscope for 2012"</offer-name>
</offer-stats>
<offer-stats clicks="92" spending="18.40" feed-id="323204" offerid="002000000006157">
<offer-name>Santa Claus costume, size 48-54</offer-name>
</offer-stats>
<offer-stats clicks="88" spending="16.26" feed-id="323204" offerid="002000000002920">
<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
<?xml version="1.0" encoding="UTF-8"?>
<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-stats clicks="204" spending="174.04">
<offer-name>Nokia N9 16GB, Black</offer-name>
</offer-stats>
<offer-stats clicks="203" spending="20.30">
<offer-name>PocketBook IQ 701, Glossy White</offer-name>
</offer-stats>
<offer-stats clicks="194" spending="161.02">
<offer-name>Samsung GT-S5830 Galaxy Ace, Black</offer-name>
</offer-stats>
<offer-stats clicks="172" spending="213.56">
<offer-name>Samsung GT-i9100 Galaxy S II, Noble Black</offer-name>
</offer-stats>
<offer-stats clicks="165" spending="81.67">
<offer-name>Samsung GT-N7000 Galaxy Note</offer-name>
</offer-stats>
<offer-stats clicks="160" spending="78.37">
<offer-name>Samsung GT-i9001 Galaxy S Plus 8GB, Metallic Black</offer-name>
</offer-stats>
<offer-stats clicks="96" spending="10.17">
Yandex.Market Partner API
Developer's guide
136
<offer-name>Tamara Globa "Complete horoscope for 2012"</offer-name>
</offer-stats>
<offer-stats clicks="92" spending="18.40">
<offer-name>Santa Claus costume, size 48-54</offer-name>
</offer-stats>
<offer-stats clicks="88" spending="16.26">
<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}
}
Yandex.Market Partner API
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.
on the total number of regions.
GET /regions/{regionId}/children
Returns information about child regions The number of requests per day depends
for the specified parent region.
on the total number of regions.
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:
This method is available starting from version 1.2 of the Yandex.Market Partner API.
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
Structure of output data:
Yandex.Market Partner API
Developer's guide
138
XML
<regions>
<region id="{number}" name="{string}" type="{string}">
<parent id="{number}" name="{string}" type="{string}">
...
</parent>
</region>
...
</regions>
JSON
{
"regions":
[
{
"id":{number},
"name":"{string}",
"type":"{string}",
"parent":
{
"id":{number},
"name":"{string}",
"type":"{string}",
"parent":
{
...
}
}
},
...
]
}
Parameter descriptions:
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.
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:
Yandex.Market Partner API
•
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.
Developer's guide
139
Parameter
for XML
format
Parameter
for JSON
format
parent
parent
Type
Value
"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.
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.
Recursively nested element for specifying higher-level "parent" regions.
Error descriptions
If an error occurs, the server returns the HTTP response code and a brief error description.
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:
<?xml version="1.0" encoding="UTF-8"?>
<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 id="225" name="Russia" type="COUNTRY"/>
</parent>
</parent>
</parent>
</region>
<region id="28630" name="Ivanovka" type="VILLAGE">
Yandex.Market Partner API
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:
This method is available starting from version 1.2 of the Yandex.Market Partner API.
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
Structure of output data:
Yandex.Market Partner API
Developer's guide
141
XML
<regions>
<region id="{number}" name="{string}" type="{string}">
<parent id="{number}" name="{string}" type="{string}">
...
</parent>
</region>
</regions>
JSON
{
"regions":
[
{
"id":{number},
"name":"{string}",
"type":"{string}",
"parent":
{
"id":{number},
"name":"{string}",
"type":"{string}",
"parent":
{
...
}
}
}
]
}
Parameter descriptions:
Parameter
for XML
format
Parameter
for JSON
format
regions
regions
Type
Value
The region specified in the request.
Parameters nested in regions
region
Description of the region.
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
Yandex.Market Partner API
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.
Developer's guide
142
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
"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.
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.
Recursively nested element for specifying higher-level "parent" regions.
Error descriptions
If an error occurs, the server returns the HTTP response code and a brief error description.
Errors containing brief descriptions typical for this method:
Description
Explanation
Possible solution
The region with the specified
regionId was not found.
Check whether the region ID is correct.
Error 404 Not Found
Region not found:
'regionId'
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 100000 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/213.xml
Sample response:
Yandex.Market Partner API
Developer's guide
143
<?xml version="1.0" encoding="UTF-8"?>
<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 id="225" name="Russia" type="COUNTRY"/>
</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:
This method is available starting from version 2.3 of the Yandex.Market Partner API.
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
Yandex.Market Partner API
Developer's guide
144
Output data
Structure of output data:
XML
<regions>
<region id="{number}" name="{string}" type="{string}">
<parent id="{number}" name="{string}" type="{string}">
...
</parent>
<children>
<region id="{number}" name="{string}" type="{string}"/>
...
</children>
</region>
</regions>
<pager total="{number}" from="{number}" to="{number}" current-page="{number}" pagescount="{number}" page-size="{number}"/>
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},
"pagesCount":{number},
"pageSize":{number}
}
}
Parameter descriptions:
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
regions
regions
Information about regions.
pager
pager
Summary of search results.
Parameters nested in regions
Yandex.Market Partner API
Developer's guide
145
Parameter
for XML
format
Parameter
for JSON
format
Type
region
Value
Description of the region.
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.
children
children
Child regions.
Parameters nested in parent
id
id
Number
ID of the parent region.
name
name
String
Name of the parent 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.
Recursively nested element for specifying higher-level parent regions.
Parameters nested in children
region
Description of a child region
Parameters nested in region
id
id
Number
ID of the child region
name
name
String
Name of the child region
Yandex.Market Partner API
Developer's guide
146
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
type
type
String
Type of region. Possible values:
•
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.
Parameters nested in pager
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
results. If nothing was found, the parameter value is 0.
currentpage
currentPage Number
The sequential number of the current page in results. If nothing was found,
the parameter value is 0.
pages-count pagesCount
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.
If nothing was found, the parameter value is 0.
page-size
pageSize
Number
The number of entries on the current page. If nothing was found,
the parameter value is 0.
Error descriptions
If an error occurs, the server returns the HTTP response code and a brief error description.
Errors containing brief descriptions typical for this method:
Description
Explanation
Possible solution
Error 400 Bad Request
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.
Page size is too big:
'pageSize'. Max page
size is 'maxPageSize'
Yandex.Market Partner API
The specified page size is too large. Check whether the correct page size is being
passed.
Developer's guide
147
Description
Explanation
Possible solution
The region with the specified
regionId was not found.
Check whether the region ID is correct.
Error 404 Not Found
Region not found:
'regionId'
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 100000 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/1/children.xml?pageSize=20&page=2
Sample response:
<?xml version="1.0" encoding="UTF-8"?>
<response>
<regions>
<region id="1" name="Moscow and Moscow region" type="REPUBLIC">
<parent id="3" name="Center" type="COUNTRY_DISTRICT">
<parent id="225" name="Russia" type="COUNTRY"/>
</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>
<pager total="75" from="21" to="40" current-page="2" pages-count="4" page-size="20"/>
</response>
JSON
Sample request:
GET https://api.partner.market.yandex.ru/v2/regions/1/children.json?pageSize=20&page=2
Sample response:
Yandex.Market Partner API
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
}
}
Yandex.Market Partner API
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.
GET /campaigns/{campaignId}/orders
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
Yandex.Market Partner API
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>
<region id="{number}" name="{string}" type="{string}">
<parent id="{number}" name="{string}" type="{string}">
...
</parent>
</region>
<address country="{string}" postcode="{string}" city="{string}" subway="{string}"
street="{string}" house="{string}" block="{string}" floor="{string}"/>
</delivery>
</cart>
JSON
{
"cart":
{
"currency":"{string}",
"items":
[
{
"feedId":{number},
"offerId":"{string}",
"offerName":"{string}",
"count":{number},
"feedCategoryId":"{string}"
},
...
],
"delivery":
{
"region":
{
"id":{number},
"name":"{string}",
Yandex.Market Partner API
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 descriptions:
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.
Parameters nested in region
id
id
Number
ID of the region.
name
name
String
Name of the region.
Yandex.Market Partner API
Developer's guide
152
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
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.
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.
Recursively nested element for specifying higher-level parent regions.
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
Yandex.Market Partner API
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},
"offerId":"{string}",
"price":{number},
"count":{number},
"delivery":{boolean}
},
...
],
"deliveryOptions":
[
{
"id":"{string}",
"type":"{string}",
"serviceName":"{string}",
"price":{number},
"dates":
{
"fromDate":"{string}",
"toDate":"{string}"
},
"outlets":
[
{
"id":{number}
Yandex.Market Partner API
Developer's guide
154
},
...
]
},
...
],
"paymentMethods":
[
"{string}",
...
]
}
}
Parameter descriptions:
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.
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.
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:
•
Yandex.Market Partner API
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.
Yandex.Market Partner API
Developer's guide
156
Error descriptions
The merchant can return the following response statuses:
Description
Explanation
Error 400 Bad Request
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>
<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 id="225" name="Russia" type="COUNTRY"/>
</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>
Yandex.Market Partner API
Developer's guide
157
JSON
Sample request from Yandex.Market:
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":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"}
}
}
},
"address":{"country":"Russia", "postcode":"119313", "city":"Moscow",
"subway":"Prospekt Vernadskovo", "street":"Leninskiy Prospekt", "house":"90",
"floor":"6"}
}
}
}
Sample merchant response:
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!
This request is made by Yandex.Market.
Description
POST /order/accept
Yandex.Market Partner API
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.
Data passed to the merchant
Data structure in the request body:
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}">
<dates from-date="{string}" to-date="{string}"/>
<region id="{number}" name="{string}" type="{string}">
<parent id="{number}" name="{string}" type="{string}">
...
</parent>
</region>
<address country="{string}" postcode="{string}" city="{string}" subway="{string}"
street="{string}" house="{string}" block="{string}" floor="{string}"/>
</delivery>
</order>
JSON
{
"order":
{
"id":{number},
"currency":"{string}",
"paymentType":"{string}",
"paymentMethod":"{string}",
"fake":{boolean},
"items":
[
{
"feedId":{number},
"offerId":"{string}",
"feedCategoryId":"{string}",
"offerName":"{string}",
"price":{number},
"count":{number}
},
...
],
"notes":"{string}",
Yandex.Market Partner API
Developer's guide
159
"delivery":
{
"id":"{string}",
"type":"{string}",
"price":{number},
"serviceName":"{string}",
"outletId":{number},
"dates":
{
"fromDate":"{string}",
"toDate":"{string}"
},
"region":
{
"id":{number},
"name":"{string}",
"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 descriptions:
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
Currency used for the product prices in the order. Possible values:
paymenttype
paymentType String
•
RUR — Russian ruble
•
UAH — Ukrainian hrivna
Type of payment for the order. Possible values:
•
PREPAID — Prepayment directly to the merchant.
•
POSTPAID — Payment on receipt.
Optional parameter.
paymentmethod
paymentMeth String
od
How the order will be paid for. Possible values for the PREPAID payment
type:
•
Yandex.Market Partner API
SHOP_PREPAID — Prepayment directly to the merchant.
Developer's guide
160
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.
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.
Information about delivery.
Parameters nested in items(XML)
item
Information about an ordered product.
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.
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 of the delivery option; assigned by the merchant.
Parameters nested in delivery
id
id
Only set if the merchant passed this ID in the response to the POST /
cart request.
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.
region
region
Delivery region.
address
address
Delivery address. Specified for the delivery methods DELIVERY
(courier) and POST (mail).
Yandex.Market Partner API
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.
Parameters nested in dates
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.
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.
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.
Recursively nested element for specifying higher-level parent regions.
Parameters nested in address
Mandatory
country
country
String
Country.
city
city
String
City or town.
house
house
String
Number of the house or building.
Yandex.Market Partner API
Developer's guide
162
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
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
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.
Parameters nested in 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:
•
Yandex.Market Partner API
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
The merchant can return the following response statuses:
Description
Explanation
Error 400 Bad Request
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 /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">
<dates from-date="03-02-2013" to-date="05-02-2013"/>
<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 id="225" name="Russia" type="COUNTRY"/>
</parent>
</parent>
</region>
<address country="Russia" postcode="119313" city="Moscow" subway="Prospekt
Vernadskovo" street="Leninskiy Prospekt" house="90" floor="6"/>
</delivery>
</order>
Sample merchant response:
HTTP/1.1 200 OK
<order id="12345" accepted="true"/>
JSON
Sample request from Yandex.Market:
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},
{"feedId":12345, "offerId":"4607632101", "feedCategoryId":"41",
"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":
{"id":213, "name":"Moscow", "type":"CITY", "parent":
{"id":1, "name":"Moscow and Moscow region", "type":"REPUBLIC", "parent":
Yandex.Market Partner API
Developer's guide
164
{"id":3, "name":"Center", "type":"COUNTRY_DISTRICT", "parent":
{"id":225, "name":"Russia", "type":"COUNTRY"}
}
}
},
"address":{"country":"Russia", "postcode":"119313", "city":"Moscow",
"subway":"Prospekt Vernadskovo", "street":"Leninskiy Prospekt", "house":"90",
"floor":"6"}
}
}
}
Sample merchant response:
HTTP/1.1 200 OK
{
"order":{"id":"12345", "accepted":true}
}
Notification of changes to the order status
Attention!
This request is made by Yandex.Market.
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.
Data passed to the merchant
Data structure in the request body:
Yandex.Market Partner API
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}"
outlet-id="{number}">
<region id="{number}" name="{string}" type="{string}">
<parent id="{number}" name="{string}" type="{string}">
...
</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}"/>
<dates from-date="03-02-2013" to-date="05-02-2013"/>
</delivery>
<buyer id="{string}" last-name="{string}" first-name="{string}" middlename="{string}" phone="{string}" email="{string}"/>
</order>
JSON
{
"order":
{
"id":{number},
"status":"{string}",
"substatus":"{string}",
"creationDate":"{string}",
"currency":"{string}",
"itemsTotal":{number},
"total":{number},
"paymentType":"{string}",
"paymentMethod":"{string}",
"fake":{boolean},
"notes":"{string}",
"items":
[
{
"feedId":{number},
"offerId":"{string}",
"feedCategoryId":"{string}",
"offerName":"{string}",
"price":{number},
"count":{number}
},
...
],
"notes":"{string}",
"delivery":
{
"id":"{string}",
"type":"{string}",
"serviceName":"{string}",
"price":{number},
"outletId":"{number}",
"region":
{
"id":{number},
"name":"{string}",
"type":"{string}",
"parent":
{
"id":{number},
"name":"{string}",
"type":"{string}",
"parent":
Yandex.Market Partner API
Developer's guide
166
{
...
}
}
},
"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}"
},
"dates":
{
"fromDate":"03-02-2013",
"toDate":"05-02-2013"
}
},
"buyer":
{
"id":"{string}",
"lastName":"{string}",
"firstName":"{string}",
"middleName":"{string}",
"phone":"{string}",
"email":"{string}"
}
}
}
Parameter descriptions:
Parameter
for XML
format
Parameter
for JSON
format
order
order
Type
Value
Order.
Parameters nested in order
id
id
Number
Campaign ID.
status
status
String
New order status. Possible values:
Yandex.Market Partner API
•
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
Currency used for the product prices in the order. Possible values:
String
•
RUR — Russian ruble
•
UAH — Ukrainian hrivna
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.
A dot is used as the decimal separator.
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
How the order will be paid for. Possible values for the PREPAID payment
type:
•
SHOP_PREPAID — Prepayment directly to the merchant.
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.
Optional parameter.
fake
Yandex.Market Partner API
fake
Logical
Indicates a test order. Possible values:
•
true — Test order.
•
false — Real order that should be fulfilled.
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.
Information about delivery.
Parameters nested in items(XML)
item
Information about an ordered product.
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.
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.
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
ID of the delivery option; assigned by the merchant.
Optional
last-name
middle-name middleName
Parameters nested in delivery
id
id
Only set if the merchant passed this ID in the response to the POST /
cart request.
type
type
String
How the order will be delivered. Possible values:
•
DELIVERY — Courier delivery.
•
PICKUP — Pick-up by the customer.
•
POST — Mail.
servicename
serviceName Number
Name of the delivery service. Specified for the delivery method
DELIVERY (courier).
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.
region
region
Delivery region.
Yandex.Market Partner API
Number
Developer's guide
169
Parameter
for XML
format
Parameter
for JSON
format
address
address
outlet-id
outletId
Type
Value
Delivery address. Specified for the delivery methods DELIVERY
(courier) and POST (mail).
Number
ID of the pick-up point the customer selected for receiving the order.
Specified for the PICKUP delivery method.
Parameters nested in dates
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.
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.
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.
Recursively nested element for specifying higher-level parent regions.
Parameters nested in address
Mandatory
country
Yandex.Market Partner API
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
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.
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
The merchant can return the following response statuses:
Description
Explanation
Error 400 Bad Request
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:
Yandex.Market Partner API
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>
<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" service-name="SPSR" price="350">
<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 id="225" name="Russia" type="COUNTRY"/>
</parent>
</parent>
</region>
<address country="Russia" postcode="119313" city="Moscow" subway="Prospekt
Vernadskovo" street="Leninskiy Prospekt" house="90" entrance="10" entryphone="289"
floor="6" apartment="289" recipient="Ivan Ivanov" phone="+71234567890"/>
<dates from-date="03-02-2013" to-date="05-02-2013"/>
</delivery>
<buyer id="LEgMQuxR8" last-name="Ivanov" first-name="Ivan" middle-name="Ivanovich"
phone="+71234567890" email="ivanov.ivan@yandex.ru"/>
</order>
Sample merchant response:
HTTP/1.1 200 OK
JSON
Sample request from Yandex.Market:
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":
[
{"feedId":12345, "offerId":"4609283881", "feedCategoryId":"35",
"offerName":"Electric teapot 100W", "price":1500, "count":1},
{"feedId":12345, "offerId":"4607632101", "feedCategoryId":"41",
"offerName":"Toaster", "price":2200, "count":1}
],
"notes":"Deliver asap, please!",
"delivery":{"type":"DELIVERY", "serviceName":"SPSR", "price":350,
"region":
{"id":213, "name":"Moscow", "type":"CITY", "parent":
{"id":1, "name":"Moscow and Moscow region", "parent":
{"id":3, "name":"Center", "type":"COUNTRY_DISTRICT", "parent":
{"id":225, "name":"Russia", "type":"COUNTRY"}
}
}
},
"address":{"country":"Russia", "postcode":"119313", "city":"Moscow",
"subway":"Prospekt Vernadskovo", "street":"Leninskiy Prospekt", "house":"90",
"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":"ivanov.ivan@yandex.ru"}
}
}
Sample merchant response:
HTTP/1.1 200 OK
Yandex.Market Partner API
Developer's guide
172
Changing the order status
Description
Changes the status of an order.
PUT /campaigns/{campaignId}/orders/{orderId}/status
Note:
This method is available starting from version 2.2 of the Yandex.Market Partner API.
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
Data structure in the request body:
XML
<order status="{string}" substatus="{string}"/>
JSON
{
"order":
{
"status":"{string}",
"substatus":"{string}"
}
}
Parameter descriptions:
Parameter
for XML
format
Parameter
for JSON
format
order
order
Type
Value
Order.
Parameters nested in 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).
Yandex.Market Partner API
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:
•
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.
•
REPLACING_ORDER — The customer is changing the contents
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:
•
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.
•
USER_REFUSED_QUALITY — The customer was not satisfied
with the quality of the product.
•
SHOP_FAILED — The merchant could not complete the order.
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
Error 400 Bad Request
Unknown status: 'status' An unknown status was indicated.
Unknown
'substatus'
Yandex.Market Partner API
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
The campaign cannot be accessed. Check whether the campaign ID is correct.
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:
<?xml version="2.0" encoding="UTF-8"?>
<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>
<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>
<delivery type="DELIVERY" service-name="SPSR" price="350">
<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 id="225" name="Russia" type="COUNTRY"/>
</parent>
</parent>
</region>
<address country="Russia" postcode="119313" city="Moscow" subway="Prospekt
Vernadskovo" street="Leninskiy Prospekt" house="90" entrance="10" entryphone="289"
floor="6" apartment="289" recipient="Ivan Ivanov" phone="+71234567890"/>
<dates from-date="03-02-2013" to-date="05-02-2013"/>
</delivery>
<buyer last-name="Ivanov" first-name="Ivan" middle-name="Ivanovich"
phone="+71234567890" email="ivanov.ivan@yandex.ru"/>
</order>
</response>
Yandex.Market Partner API
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",
"currency":"RUR", "itemsTotal":3700, "total":4050, "paymentType":"POSTPAID",
"paymentMethod":"CASH_ON_DELIVERY", "fake":false,
"items":
[
{"feedId":12345, "offerId":"4609283881", "feedCategoryId":"35",
"offerName":"Electric teapot 100W", "price":1500, "count":1},
{"feedId":12345, "offerId":"4607632101", "feedCategoryId":"41",
"offerName":"Toaster", "price":2200, "count":1}
],
"delivery":{"type":"DELIVERY", "serviceName":"SPSR", "price":350,
"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":
{"id":225,"name":"Russia", "type":"COUNTRY"}
}
}
},
"address":{"country":"Russia", "postcode":"119313", "city":"Moscow",
"subway":"Prospekt Vernadskovo", "street":"Leninskiy Prospekt", "house":"90",
"entrance":"10", "entryphone":"289", "floor":"6", "apartment":"289", "recipient":"Ivan
Ivanov", "phone":"+71234567890"},
"dates":{"fromDate": "03-02-2013", "toDate": "05-02-2013"}
},
"buyer":{"lastName":"Ivanov", "firstName":"Ivan", "middleName":"Ivanovich",
"phone":"+71234567890", "email":"ivanov.ivan@yandex.ru"}
}
}
Changing conditions for order delivery
Description
PUT /campaigns/{campaignId}/orders/{orderId}/delivery
Changes the conditions for order delivery.
Note:
This method is available starting from version 2.2 of the Yandex.Market Partner API.
Resource URL:
https://api.partner.market.yandex.ru/v2/{campaignId}/orders/{orderId}/delivery.
[format]
Input data
Parameters in the URL:
Parameter
Type
Value
Mandatory
Yandex.Market Partner API
Developer's guide
176
Parameter
Type
Value
campaignId
Number
The campaign ID.
orderId
Number
Campaign ID.
format
String
XML or JSON.
Data structure in the request body:
XML
<delivery id="{string}" type="{string}" service-name="{string}" price="{number}" outletid="{number}">
<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}"/>
<dates from-date="{string}" to-date="{string}"/>
</delivery>
JSON
{
"delivery":
{
"id":"{string}",
"type":"{string}",
"serviceName":"{string}",
"price":{number},
"outletId":{number},
"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}"
}
"dates":
{
"fromDate":"{string}", "toDate":"{string}"
}
}
}
Parameter descriptions:
Parameter
for XML
format
Parameter
for JSON
format
delivery
delivery
Type
Value
New delivery conditions.
Parameters nested in delivery
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.
Yandex.Market Partner API
Developer's guide
177
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
Possible values:
•
DELIVERY — Courier delivery.
•
PICKUP — Pick-up by the customer.
•
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.
Parameters nested in dates
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.
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 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.
entrance
entrance
String
Entrance number.
Optional
Yandex.Market Partner API
Developer's guide
178
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
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.
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
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
Error 400 Bad Request
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
The campaign cannot be accessed. Check whether the campaign ID is correct.
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:
Yandex.Market Partner API
Developer's guide
179
PUT /v2/campaigns/10003/orders/12345/delivery.xml HTTP/1.1
<delivery type="DELIVERY" service-name="SPSR" price="350">
<address country="Russia" postcode="119313" city="Moscow" subway="Prospekt
Vernadskovo"
street="Leninskiy Prospekt" house="90" entrance="10" entryphone="289" floor="6"
apartment="289" recipient="Ivan Ivanov" phone="+71234567890"/>
<dates from-date="03-02-2013"/>
</delivery>
Sample response:
<?xml version="2.0" encoding="UTF-8"?>
<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>
<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>
<delivery type="DELIVERY" service-name="SPSR" price="350">
<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 id="225" name="Russia" type="COUNTRY"/>
</parent>
</parent>
</region>
<address country="Russia" postcode="119313" city="Moscow" subway="Prospekt
Vernadskovo" street="Leninskiy Prospekt" house="90" entrance="10" entryphone="289"
floor="6" apartment="289" recipient="Ivan Ivanov" phone="+71234567890"/>
<dates from-date="03-02-2013"/>
</delivery>
<buyer last-name="Ivanov" first-name="Ivan" middle-name="Ivanovich"
phone="+71234567890" email="ivanov.ivan@yandex.ru"/>
</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,
"address":{"country":"Russia", "postcode":"119313", "city":"Moscow",
"subway":"Prospekt Vernadskovo", "street":"Leninskiy Prospekt", "house":"90",
"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",
"currency":"RUR", "itemsTotal":3700, "total":4050, "paymentType":"POSTPAID",
"paymentMethod":"CASH_ON_DELIVERY", "fake":false,
"items":
[
{"feedId":12345, "offerId":"4609283881", "feedCategoryId":"35",
"offerName":"Electric teapot 100W", "price":1500, "count":1},
{"feedId":12345, "offerId":"4607632101", "feedCategoryId":"41",
"offerName":"Toaster", "price":2200, "count":1}
],
"delivery":
{
Yandex.Market Partner API
Developer's guide
180
"type":"DELIVERY", "serviceName":"SPSR", "price":350,
"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":
{"id":225, "name":"Russia", "type":"COUNTRY"}
}
}
},
"address":{"country":"Russia", "postcode":"119313", "city":"Moscow",
"subway":"Prospekt Vernadskovo", "street":"Leninskiy Prospekt", "house":"90",
"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":"ivanov.ivan@yandex.ru"}
}
}
Information about a requested order
Description
GET /campaigns/{campaignId}/orders/{orderId}
Returns information about the requested order.
Note:
This method is available starting from version 2.2 of the Yandex.Market Partner API.
Resource URL:
https://api.partner.market.yandex.ru/v2/campaigns/{campaignId}/orders/{orderId}.
[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
Output data
Structure of output data:
Yandex.Market Partner API
Developer's guide
181
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}" notes="{string}">
<items>
<item feed-id="{number}" offer-id="{string}" feed-category-id="{string}" offername="{string}" price="{number}" count="{number}" />
...
</items>
<delivery id="{string}" type="{string}" service-name="{string}" price="{number}"
outlet-id="{number}">
<region id="{number}" name="{string}" type="{string}">
<parent id="{number}" name="{string}" type="{string}">
...
</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}"/>
<dates from-date="03-02-2013" to-date="05-02-2013"/>
</delivery>
<buyer id="{string}" last-name="{string}" first-name="{string}" middlename="{string}" phone="{string}" email="{string}"/>
</order>
JSON
{
"order":
{
"id":{number},
"status":"{string}",
"substatus":"{string}",
"creationDate":"{string}",
"currency":"{string}",
"itemsTotal":{number},
"total":{number},
"paymentType":"{string}",
"paymentMethod":"{string}",
"fake":{boolean},
"notes":"{string}",
"items":
[
{
"feedId":{number},
"offerId":"{string}",
"feedCategoryId":"{string}",
"offerName":"{string}",
"price":{number},
"count":{number}
},
...
],
"delivery":
{
"id":"{string}",
"type":"{string}",
"serviceName":"{string}",
"price":{number},
"outletId":"{number}",
"region":
{
"id":{number},
"name":"{string}",
"type":"{string}",
"parent":
{
"id":{number},
"name":"{string}",
"type":"{string}",
"parent":
{
...
Yandex.Market Partner API
Developer's guide
182
}
}
},
"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}"
},
"dates":
{
"fromDate":"03-02-2013",
"toDate":"05-02-2013"
}
},
"buyer":
{
"id":"{string}",
"lastName":"{string}",
"firstName":"{string}",
"middleName":"{string}",
"phone":"{string}",
"email":"{string}"
}
}
}
Parameter descriptions:
Parameter
for XML
format
Parameter
for JSON
format
order
order
Type
Value
Order.
Parameters nested in order
id
id
Number
Campaign ID.
status
status
String
Campaign state. Possible values:
Yandex.Market Partner API
•
RESERVED — Order has been reserved.
•
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
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:
•
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 method).
•
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
Currency used for the product prices in the order. Possible values:
String
•
RUR — Russian ruble
•
UAH — Ukrainian hrivna
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.
A dot is used as the decimal separator.
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
How the order will be paid for. Possible values for the PREPAID payment
type:
•
SHOP_PREPAID — Prepayment directly to the merchant.
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.
Optional parameter.
fake
Yandex.Market Partner API
fake
Logical
Indicates a test order. Possible values:
•
true — Test order.
•
false — Real order that should be fulfilled.
Developer's guide
184
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
notes
notes
String
Comments on the order. Optional parameter.
items
items
Order contents.
buyer
buyer
Information about the customer.
delivery
delivery
Information about delivery.
Parameters nested in items
item
Information about an ordered product.
Parameters nested in item
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.
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.
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
ID of the delivery option; assigned by the merchant.
Optional
last-name
middle-name middleName
Parameters nested in delivery
id
id
Only set if the merchant passed this ID in the response to the POST /
cart request.
type
type
String
How the order will be delivered. Possible values:
•
DELIVERY — Courier delivery.
•
PICKUP — Pick-up by the customer.
•
POST — Mail.
servicename
serviceName Number
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.
region
region
Delivery region.
Yandex.Market Partner API
Number
Developer's guide
185
Parameter
for XML
format
Parameter
for JSON
format
address
address
outlet-id
outletId
Type
Value
Delivery address. Specified for the delivery methods DELIVERY
(courier) and POST (mail).
Number
ID of the pick-up point the customer selected for receiving the order.
Specified for the PICKUP delivery method.
Parameters nested in dates
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.
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.
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.
Recursively nested element for specifying higher-level parent regions.
Parameters nested in address
Mandatory
country
Yandex.Market Partner API
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
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.
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.
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
Error 403 Forbidden
Access denied
The campaign cannot be accessed. Check whether the campaign ID is correct.
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:
GET /v2/campaigns/10003/orders/12345.xml HTTP/1.1
Sample response:
Yandex.Market Partner API
Developer's guide
187
<?xml version="2.0" encoding="UTF-8"?>
<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>
<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>
<delivery type="DELIVERY" service-name="SPSR" price="350">
<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 id="225" name="Russia" type="COUNTRY"/>
</parent>
</parent>
</region>
<address country="Russia" postcode="119313" city="Moscow" subway="Prospekt
Vernadskovo" street="Leninskiy Prospekt" house="90" entrance="10" entryphone="289"
floor="6" apartment="289" recipient="Ivan Ivanov" phone="+71234567890"/>
<dates from-date="03-02-2013" to-date="05-02-2013"/>
</delivery>
<buyer id="LEgMQuuxR8" last-name="Ivanov" first-name="Ivan" middle-name="Ivanovich"
phone="+71234567890" email="ivanov.ivan@yandex.ru"/>
</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",
"currency":"RUR", "itemsTotal":3700, "total":4050, "paymentType":"POSTPAID",
"paymentMethod":"CASH_ON_DELIVERY", "fake":false,
"items":
[
{"feedId":12345, "offerId":"4609283881", "feedCategoryId":"35",
"offerName":"Electric teapot 100W", "price":1500, "count":1},
{"feedId":12345, "offerId":"4607632101", "feedCategoryId":"41",
"offerName":"Toaster", "price":2200, "count":1}
],
"delivery":{"type":"DELIVERY", "serviceName":"SPSR", "price":350,
"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":
{"id":225, "name":"Russia", "type":"COUNTRY"}
}
}
},
"address":{"country":"Russia", "postcode":"119313", "city":"Moscow",
"subway":"Prospekt Vernadskovo", "street":"Leninskiy Prospekt", "house":"90",
"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":"ivanov.ivan@yandex.ru"}
}
}
Yandex.Market Partner API
Developer's guide
188
Information about requested orders
Description
GET /campaigns/{campaignId}/orders
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:
This method is available starting from version 2.2 of the Yandex.Market Partner API.
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
Parameters in the URL:
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
Structure of output data:
Yandex.Market Partner API
Developer's guide
189
XML
<pager total="{number}" from="{number}" to="{number}" current-page="{number}" pagescount="{number}" page-size="{number}"/>
<orders>
<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}" notes="{string}">
<items>
<item feed-id="{number}" offer-id="{string}" feed-category-id="{string}"
offer-name="{string}" price="{number}" count="{number}"/>
...
</items>
<delivery id="{string}" type="{string}" service-name="{string}" price="{number}"
outlet-id="{number}">
<region id="{number}" name="{string}" type="{string}">
<parent id="{number}" name="{string}" type="{string}"/>
...
</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}"/>
<dates from-date="{string}" to-date="{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},
"pageSize":{number},
"pagesCount":{number},
"currentPage":{number}
},
"orders":
[
{
"id":{number},
"status":"{string}",
"substatus":"{string}",
"creationDate":"{string}",
"currency":"{string}",
"itemsTotal":{number},
"total":{number},
"paymentType":"{string}",
"paymentMethod":"{string}",
"fake":{boolean},
"notes":"{string}",
"items":
[
{
"feedId":{number},
"offerId":"{string}",
"feedCategoryId":"{string}",
"offerName":"{string}",
"price":{number},
"count":{number}
},
...
],
"delivery":
{
"id":"{string}",
"type":"{string}",
"serviceName":"{string}",
"price":{number},
Yandex.Market Partner API
Developer's guide
190
"outletId":{number},
"region":
{
"id":{number},
"name":"{string}",
"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}",
"entrance":"{string}",
"entryphone":"{string}",
"floor":"{string}",
"apartment":"{string}",
"recipient":"{string}",
"phone":"{string}"
},
"dates":
{
"fromDate":"{string}",
"toDate": "{string}"
}
},
"buyer":
{
"id":"{string}",
"lastName":"{string}",
"firstName":"{string}",
"middleName":"{string}",
"phone":"{string}",
"email":"{string}"
}
},
...
]
}
Parameter descriptions:
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
pager
pager
Summary of search results.
orders
orders
Orders.
Parameters nested in pager
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
Yandex.Market Partner API
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.
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
results. If nothing was found, the parameter value is 0.
currentpage
currentPage Number
The sequential number of the current page in results. If nothing was found,
the parameter value is 0.
pages-count pagesCount
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.
If nothing was found, the parameter value is 0.
page-size
pageSize
Number
The number of entries on the current page. If nothing was found,
the parameter value is 0.
Parameters nested in orders
order
Information about an order.
Parameters nested in order
id
id
Number
Campaign ID.
status
status
String
Campaign state. Possible values:
substatus
creationdate
Yandex.Market Partner API
substatus
String
creationDat String
e
•
RESERVED — Order has been reserved.
•
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.
Additional parameter for the order status. If the status does not have
substatuses, this parameter 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.
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
Currency used for the product prices in the order. Possible values:
•
RUR — Russian ruble
•
UAH — Ukrainian hrivna
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.
A dot is used as the decimal separator.
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
How the order will be paid for. Possible values for the PREPAID payment
type:
•
SHOP_PREPAID — Prepayment directly to the merchant.
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.
Optional parameter.
fake
fake
Logical
Indicates a test order. Possible values:
•
true — Test order.
•
false — Real order that should be fulfilled.
notes
notes
items
items
Order contents.
buyer
buyer
Information about the customer.
delivery
delivery
Information about delivery.
String
Comments on the order. Optional parameter.
Parameters nested in items
item
Information about an ordered product.
Parameters nested in item
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.
price
price
String
Product price in the order's currency. A dot is used as the decimal
separator.
count
count
Number
Number of products ordered.
Parameters nested in buyer
Mandatory
Yandex.Market Partner API
Developer's guide
193
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
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
ID of the delivery option; assigned by the merchant.
Optional
last-name
middle-name middleName
Parameters nested in delivery
id
id
Only set if the merchant passed this ID in the response to the POST /
cart request.
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.
region
region
Delivery region.
address
address
Delivery address. Specified for the delivery methods DELIVERY
(courier) and POST (mail).
outlet-id
outletId
Number
Number
ID of the pick-up point the customer selected for receiving the order.
Specified for the PICKUP delivery method.
Parameters nested in dates
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.
Parameters nested in region
id
id
Number
ID of the region.
name
name
String
Name of the region.
Yandex.Market Partner API
Developer's guide
194
Parameter
for XML
format
Parameter
for JSON
format
Type
Value
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.
String
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.
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.
Recursively nested element for specifying higher-level parent regions.
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.
entrance
entrance
String
Entrance number.
entryphone
entryphone
String
Code for the entry phone.
Optional
Yandex.Market Partner API
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
Full name of the order recipient.
phone
phone
String
Phone number of the order recipient.
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.
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
Error 400 Bad Request
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.
size is 'maxPageSize'
Error 403 Forbidden
Access denied
The campaign cannot be accessed. Check whether the campaign ID is correct.
Examples
XML
Sample request:
GET /v2/campaigns/10003/orders.xml HTTP/1.1
Sample response:
Yandex.Market Partner API
Developer's guide
196
<?xml version="2.0" encoding="UTF-8"?>
<response>
<pager total="2" from="1" to="2" current-page="1" pages-count="1" page-size="2"/>
<orders>
<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>
<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="Тостер" price="2200" count="1"/>
</items>
<delivery type="DELIVERY" service-name="SPSR" price="350">
<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 id="225" name="Russia" type="COUNTRY"/>
</parent>
</parent>
</region>
<address country="Russia" postcode="119313" city="Moscow" subway="Prospekt
Vernadskovo" street="Leninskiy prospekt" house="90" entrance="10" entryphone="289"
floor="6" apartment="289" recipient="Ivan Ivanov" phone="+71234567890"/>
<dates from-date="02-02-2013" to-date="03-02-2013"/>
</delivery>
<buyer id="LEgMQuuxR8" last-name="Ivanov" first-name="Ivan" middlename="Ivanovich" phone="+71234567890" email="ivanov.ivan@yandex.ru"/>
</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">
<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 id="225" name="Russia" type="COUNTRY"/>
</parent>
</parent>
</region>
<dates from-date="02-02-2013" to-date="02-02-2013"/>
</delivery>
<buyer id="LEgMQuuxR10" last-name="Petrov" first-name="Peter" middlename="Petrovich" phone="+70987654321" email="petrov.petr@yandex.ru"/>
</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",
"currency":"RUR", "itemsTotal":3700, "total":4050, "paymentType":"POSTPAID",
"paymentMethod":"CASH_ON_DELIVERY", "fake":false, "items":
[
{"feedId":12345, "offerId":"4609283881", "feedCategoryId":"35",
"offerName":"Electric teapot 100W", "price":1500, "count":1},
{"feedId":12345, "offerId":"4607632101", "feedCategoryId":"41",
"offerName":"Toaster", "price":2200, "count":1}
],
Yandex.Market Partner API
Developer's guide
197
"delivery":{"type":"DELIVERY", "serviceName":"SPSR", "price":350,
"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":
{"id":225, "name":"Russia", "type":"COUNTRY"}
}
}
},
"address":{"country":"Russia", "postcode":"119313", "city":"Moscow",
"subway":"Prospekt Vernadskovo", "street":"Leninskiy Prospekt", "house":"90",
"entrance":"10", "entryphone":"289", "floor":"6", "apartment":"289", "recipient": "Ivan
Ivanov", "phone": "+71234567890"},
"dates": {"fromDate": "02-02-2013", "toDate": "03-02-2013"}
},
"buyer":{"id":"LEgMQuuxR8", "lastName":"Ivanov", "firstName":"Ivan",
"middleName":"Ivanovich", "phone":"+71234567890", "email":"ivanov.ivan@yandex.ru"}
},
{"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},
{"feedId":12345, "offerId":"4683949391", "feedCategoryId":"23",
"offerName":"Memory card microSDHC 32GB", "price":1900, "count":1}
],
"delivery":{"type":"PICKUP", "price":0, "serviceName":"In-house delivery service",
"outletId":9,
"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":
{"id":225, "name":"Russia", "type":"COUNTRY"}
}
}
},
"dates": {"fromDate": "02-02-2013", "toDate": "02-02-2013"}
},
"buyer":{"id":"LEgMQuuxR10", "lastName":"Petrov", "firstName":"Peter",
"middleName":"Petrovich", "phone":"+70987654321", "email":"petrov.petr@yandex.ru"}
}
]
}
Yandex.Market Partner API
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
Host api.partner.market.yandex.ru
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
Host api.partner.market.yandex.ru
Sample response:
Yandex.Market Partner API
Developer's guide
199
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: 9996
{"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
Host api.partner.market.yandex.ru
Content-Type application/json
{"offers":[
"Tefal 539625",
"Clatronic CM 3372"
]}
Sample response:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
X-RateLimit-Resource-Limit: 5000
X-RateLimit-Resource-Until: Tue, 17 Apr 2012 00:00:00 GMT
X-RateLimit-Resource-Remaining: 4994
{"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
Restrictions for requests
Yandex.Market Partner API
Developer's guide
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
Yandex.Market Partner API
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
201
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
Yandex.Market Partner API
Developer's guide
Yandex.Market Partner API
Developer's guide
11.06.2015