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: [email protected] Headquarters: 16 L'va Tolstogo St., Moscow, Russia 119021 Contents Introduction .......................................................................................................................................................................................... 5 Overview .............................................................................................................................................................................................. 5 Requests to Yandex.Market .............................................................................................................................................................. 7 Authentication .............................................................................................................................................................................. 7 Method calls ................................................................................................................................................................................. 8 Input data format .......................................................................................................................................................................... 8 Response format ........................................................................................................................................................................... 9 Error messages ............................................................................................................................................................................. 9 Restrictions for requests ............................................................................................................................................................. 13 Versions ..................................................................................................................................................................................... 14 Debugging the API .................................................................................................................................................................... 17 Requests to the merchant ................................................................................................................................................................ 18 Authentication ............................................................................................................................................................................ 18 SSL certificate ............................................................................................................................................................................ 18 Request method .......................................................................................................................................................................... 20 Data format in the request and response .................................................................................................................................... 20 Error messages ........................................................................................................................................................................... 21 Versions ..................................................................................................................................................................................... 21 Debugging the API .................................................................................................................................................................... 21 Verification tests ........................................................................................................................................................................ 25 API methods ..................................................................................................................................................................................... 28 Basic methods ........................................................................................................................................................................... 28 User campaigns .................................................................................................................................................................. 29 Information about a campaign ........................................................................................................................................... 32 Logins associated with a campaign .................................................................................................................................... 35 Campaigns accessible by login .......................................................................................................................................... 36 Campaign settings .............................................................................................................................................................. 39 Placement settings .................................................................................................................................................................... 42 Campaign region ................................................................................................................................................................ 42 Assortment ................................................................................................................................................................................ 46 Product offers in a campaign ............................................................................................................................................. 46 List of the campaign's price lists ........................................................................................................................................ 52 Price list information .......................................................................................................................................................... 55 Price list category ............................................................................................................................................................... 57 Campaign categories .......................................................................................................................................................... 61 Product modifications .............................................................................................................................................................. 66 Information about a product modification ......................................................................................................................... 66 Search for product modifications ....................................................................................................................................... 69 Information about multiple modifications ......................................................................................................................... 74 List of offers for a modification ......................................................................................................................................... 79 List of offers for multiple modifications ............................................................................................................................ 83 Managing bids .......................................................................................................................................................................... 91 Information about bids ....................................................................................................................................................... 92 Setting bids for offers ......................................................................................................................................................... 96 Bid recommendations ...................................................................................................................................................... 103 Setting recommended bids ............................................................................................................................................... 114 Bid settings ....................................................................................................................................................................... 122 Finances .................................................................................................................................................................................. 124 Campaign balance and forecast of expenditures .............................................................................................................. 124 Statistics .................................................................................................................................................................................. 126 Basic statistics .................................................................................................................................................................. 126 Statistics for product offers .............................................................................................................................................. 131 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®ionId=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®ionId=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="[email protected]"/> </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":"[email protected]"} } } 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="[email protected]"/> </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":"[email protected]"} } } 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="[email protected]"/> </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":"[email protected]"} } } 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="[email protected]"/> </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":"[email protected]"} } } 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="[email protected]"/> </order> <order id="12346" status="PICKUP" creation-date="31-01-2013 21:42:12" currency="RUR" items-total="30800" total="30800" payment-type="POSTPAID" paymentmethod="CARD_ON_DELIVERY" fake="false"> <items> <item feed-id="12345" offer-id="4638734829" feed-category-id="22" offername="Sony Xperia Z" price="28900" count="1"/> <item feed-id="12345" offer-id="4683949391" feed-category-id="23" offername="Memory card microSDHC 32GB" price="1900" count="1"/> </items> <delivery type="PICKUP" service-name="In-house delivery service" price="0" outletid="9"> <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="[email protected]"/> </order> </orders> </response> JSON Sample request: GET /v2/campaigns/10003/order/12345.json HTTP/1.1 Sample response: { "pager":{"total":2,"from":1,"to":2,"pageSize":2,"pagesCount":1,"currentPage":1}, "orders": [ {"id":12345, "status":"PROCESSING", "creationDate":"01-02-2013 16:35:03", "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":"[email protected]"} }, {"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":"[email protected]"} } ] } 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
© Copyright 2024