Getting information about the fullness of store cards

The method is available for all models.

If you are using an API Key token, one of the accesses in the list is required to call the method

Returns information about the content status for the specified products:

  • whether a product card has been created and what is its status.
  • The rating of the card is how many percent it is filled.
  • transmitted product characteristics;
  • are there any errors or warnings related to the content;
  • recommendations for filling out the card.
, Limit: 600 requests per minute

Request

POST

https://api.partner.market.yandex.ru/businesses/{businessId}/offer-cards

Path parameters

Name

Description

businessId*

Type: integer<int64>

Cabinet ID. To find out, use the request GET campaigns.

ℹ️ What is a cabinet and a store on the Market?

Min value: 1

Query parameters

Name

Description

limit

Type: integer<int32>

The number of values per page.

Min value: 1
Example: 20

page_token

Type: string

ID of the results page.

If the parameter is omitted, the first page is returned.

We recommend transmitting the value of the output parameter nextPageToken, received during the last request.

If set page_token and the request has parameters page and pageSize they are ignored.
Example: eyBuZXh0SWQ6IDIzNDIgfQ==

Body

application/json
{
    "offerIds": [
        "string"
    ],
    "cardStatuses": [
        "HAS_CARD_CAN_NOT_UPDATE"
    ],
    "categoryIds": [
        0
    ]
}

Name

Description

cardStatuses

Type: OfferCardStatusType[]

Filter by card status.

What is a product card?
Product card status:

  • HAS_CARD_CAN_NOT_UPDATE — The Market card.
  • HAS_CARD_CAN_UPDATE — It can be supplemented.
  • HAS_CARD_CAN_UPDATE_ERRORS — The changes have not been accepted.
  • HAS_CARD_CAN_UPDATE_PROCESSING — Changes are under review.
  • NO_CARD_NEED_CONTENT — Create a card.
  • NO_CARD_MARKET_WILL_CREATE — Creates a Marketplace.
  • NO_CARD_ERRORS — It wasn't created because of a mistake.
  • NO_CARD_PROCESSING — We check the data.
  • NO_CARD_ADD_TO_CAMPAIGN — Place the product in the store.

Enum: HAS_CARD_CAN_NOT_UPDATE, HAS_CARD_CAN_UPDATE, HAS_CARD_CAN_UPDATE_ERRORS, HAS_CARD_CAN_UPDATE_PROCESSING, NO_CARD_NEED_CONTENT, NO_CARD_MARKET_WILL_CREATE, NO_CARD_ERRORS, NO_CARD_PROCESSING, NO_CARD_ADD_TO_CAMPAIGN

Min items: 1

Unique items  

categoryIds

Type: integer<int32>[]

Filter by category on the Market.
The ID of the category on the Market.

When changing the category, make sure that the product characteristics and their values in the parameter parameterValues you are submitting for a new category.

You can get a list of Market categories using a request. POST categories/tree.

Min value: 1

Min items: 1

Max items: 200

Unique items  

offerIds

Type: string[]

The IDs of the products that information is needed about.

Do not use this field at the same time as filters based on card statuses, categories, brands, or tags. If you want to use filters, leave the field empty.
Your SKU is the product identifier in your system.

SKU Usage Rules:

  • Each product must have its own SKU.

  • An already set SKU cannot be released and reused for another product. Each product should receive a new identifier that has never been used in your catalog before.

The SKU of the product can be changed in the seller's account on the Market. Read about how to do this. in the Help of the Market for sellers.

What is a SKU and how to assign it

Min length: 1

Max length: 255

Pattern: ^(?=.*\S.*)[^\x00-\x08\x0A-\x1f\x7f]{1,255}$

Min items: 1

Max items: 200

Unique items  

OfferCardStatusType

Product card status:

  • HAS_CARD_CAN_NOT_UPDATE — The Market card.
  • HAS_CARD_CAN_UPDATE — It can be supplemented.
  • HAS_CARD_CAN_UPDATE_ERRORS — The changes have not been accepted.
  • HAS_CARD_CAN_UPDATE_PROCESSING — Changes are under review.
  • NO_CARD_NEED_CONTENT — Create a card.
  • NO_CARD_MARKET_WILL_CREATE — Creates a Marketplace.
  • NO_CARD_ERRORS — It wasn't created because of a mistake.
  • NO_CARD_PROCESSING — We check the data.
  • NO_CARD_ADD_TO_CAMPAIGN — Place the product in the store.

Type

Description

OfferCardStatusType

Enum: HAS_CARD_CAN_NOT_UPDATE, HAS_CARD_CAN_UPDATE, HAS_CARD_CAN_UPDATE_ERRORS, HAS_CARD_CAN_UPDATE_PROCESSING, NO_CARD_NEED_CONTENT, NO_CARD_MARKET_WILL_CREATE, NO_CARD_ERRORS, NO_CARD_PROCESSING, NO_CARD_ADD_TO_CAMPAIGN

Responses

200 OK

Information about the cards of the specified products.

Body

application/json
{
    "status": "OK",
    "result": {
        "offerCards": [
            {
                "offerId": "string",
                "mapping": {
                    "marketSku": 0,
                    "marketSkuName": "string",
                    "marketModelId": 0,
                    "marketModelName": "string",
                    "marketCategoryId": 0,
                    "marketCategoryName": "string"
                },
                "parameterValues": [
                    {
                        "parameterId": 0,
                        "unitId": 0,
                        "valueId": 0,
                        "value": "string"
                    }
                ],
                "cardStatus": "HAS_CARD_CAN_NOT_UPDATE",
                "contentRating": 0,
                "averageContentRating": 0,
                "contentRatingStatus": "UPDATING",
                "recommendations": [
                    {
                        "type": "HAS_VIDEO",
                        "percent": 0,
                        "remainingRatingPoints": 0
                    }
                ],
                "errors": [
                    {
                        "message": "string",
                        "comment": "string"
                    }
                ],
                "warnings": [
                    {
                        "message": "string",
                        "comment": "string"
                    }
                ]
            }
        ],
        "paging": {
            "nextPageToken": "string"
        }
    }
}

Name

Description

result

Type: OfferCardsContentStatusDTO

A list of products with information about the status of the cards.

status

Type: ApiResponseStatusType

The type of response. Possible values:

  • OK — there are no mistakes.
  • ERROR — an error occurred while processing the request.

Enum: OK, ERROR

OfferCardsContentStatusDTO

A list of products with information about the status of the cards.

Name

Description

offerCards*

Type: OfferCardDTO[]

The product list page with information about the status of the cards.
Information about the status of the product card.

If the field mapping missing in the response, the Market has not yet managed to process the product information. To determine the category of such an item, repeat the request in a few minutes.

paging

Type: ForwardScrollingPagerDTO

The ID of the next page.

ApiResponseStatusType

The type of response. Possible values:

  • OK — there are no mistakes.
  • ERROR — an error occurred while processing the request.

Type

Description

ApiResponseStatusType

Enum: OK, ERROR

OfferCardDTO

Information about the status of the product card.

If the field mapping missing in the response, the Market has not yet managed to process the product information. To determine the category of such an item, repeat the request in a few minutes.

Name

Description

offerId*

Type: string

Your SKU is the product identifier in your system.

SKU Usage Rules:

  • Each product must have its own SKU.

  • An already set SKU cannot be released and reused for another product. Each product should receive a new identifier that has never been used in your catalog before.

The SKU of the product can be changed in the seller's account on the Market. Read about how to do this. in the Help of the Market for sellers.

What is a SKU and how to assign it

Min length: 1

Max length: 255

Pattern: ^(?=.*\S.*)[^\x00-\x08\x0A-\x1f\x7f]{1,255}$

averageContentRating

Type: integer<int32>

The average rating of the card for products of the category indicated in marketCategoryId.

cardStatus

Type: OfferCardStatusType

Product card status:

  • HAS_CARD_CAN_NOT_UPDATE — The Market card.
  • HAS_CARD_CAN_UPDATE — It can be supplemented.
  • HAS_CARD_CAN_UPDATE_ERRORS — The changes have not been accepted.
  • HAS_CARD_CAN_UPDATE_PROCESSING — Changes are under review.
  • NO_CARD_NEED_CONTENT — Create a card.
  • NO_CARD_MARKET_WILL_CREATE — Creates a Marketplace.
  • NO_CARD_ERRORS — It wasn't created because of a mistake.
  • NO_CARD_PROCESSING — We check the data.
  • NO_CARD_ADD_TO_CAMPAIGN — Place the product in the store.

Enum: HAS_CARD_CAN_NOT_UPDATE, HAS_CARD_CAN_UPDATE, HAS_CARD_CAN_UPDATE_ERRORS, HAS_CARD_CAN_UPDATE_PROCESSING, NO_CARD_NEED_CONTENT, NO_CARD_MARKET_WILL_CREATE, NO_CARD_ERRORS, NO_CARD_PROCESSING, NO_CARD_ADD_TO_CAMPAIGN

contentRating

Type: integer<int32>

The rating of the card.

contentRatingStatus

Type: OfferCardContentStatusType

The status of calculating the card's rating and recommendations.

Enum: UPDATING, ACTUAL

errors

Type: OfferErrorDTO[]

Errors in the content that prevent the product from being placed in the showcase.
An error message related to the product placement.

Min items: 1

mapping

Type: GetMappingDTO

Basic information about the product card.
The ID of the card on the Market. Shows the current product link to the card.

It may not be included in the response if the product is not linked to the card yet. Check the card's status or correct any errors.

parameterValues

Type: ParameterValueDTO[]

A list of characteristics with their values.
The value of the characteristic.

You can specify multiple values of the same characteristic, provided that:

To do this, in parameterValues pass each value separately — multiple objects with parameters parameterId, valueId and value. Parameter parameterId it must be the same.

Min items: 1

recommendations

Type: OfferCardRecommendationDTO[]

A list of recommendations for filling out the card.

Yandex.Market recommendations help you fill out the card so that it is easier for customers to find your product and decide to make a purchase.
Recommendation for filling out the product card.

Min items: 1

warnings

Type: OfferErrorDTO[]

Content-related warnings that do not prevent the product from being placed in the showcase.
An error message related to the product placement.

Min items: 1

ForwardScrollingPagerDTO

The ID of the next page.

Name

Description

nextPageToken

Type: string

ID of the next results page.

OfferCardContentStatusType

The status of calculating the rating of the product card and recommendations:

  • UPDATING — the rating is updated.
  • ACTUAL — the rating is current.

Type

Description

OfferCardContentStatusType

Enum: UPDATING, ACTUAL

OfferErrorDTO

An error message related to the product placement.

Name

Description

comment

Type: string

Explanation.

message

Type: string

The type of error.

GetMappingDTO

Information about the products in the catalog.

Name

Description

marketCategoryId

Type: integer<int64>

ID of the category on the Market that the product belongs to.

It may be missing from the response if the Market has not yet determined the product category.

marketCategoryName

Type: string

The name of the card's category on the Market.

It may be missing from the response if the Market has not yet determined the product category.

marketModelId

⦸

Type: integer<int64>

The ID of the model on the Market.

It may not be included in the response if the product is not linked to the card yet.

marketModelName

⦸

Type: string

The name of the model on the Market.

It may not be included in the response if the product is not linked to the card yet.

marketSku

Type: integer<int64>

The ID of the card on the Market.

Min value: 1

marketSkuName

Type: string

The name of the product card.

It may not be included in the response if the product is not linked to the card yet.

ParameterValueDTO

The value of the characteristic.

You can specify multiple values of the same characteristic, provided that:

To do this, in parameterValues pass each value separately — multiple objects with parameters parameterId, valueId and value. Parameter parameterId it must be the same.

Name

Description

parameterId*

Type: integer<int64>

The identifier of the characteristic.

Min value: 1

unitId

Type: integer<int64>

ID of the unit of measurement. If you did not pass the parameter unitId, the default unit of measurement is used.

value

Type: string

Meaning.

For type characteristics ENUM transmit along with valueId.

valueId

Type: integer<int64>

ID of the value.

Be sure to specify the identifier if you are transmitting a value from the list of acceptable values received from the Market.

Transmit along with value.

Only for type characteristics ENUM.

OfferCardRecommendationDTO

Recommendation for filling out the product card.

Name

Description

type*

Type: OfferCardRecommendationType

A recommendation for adding or replacing content. It is not refunded for cards that are filled with the Market or contain used goods.

Some of the recommendations relate to the main parameters, which are available for products of any category. Others belong to those characteristics which the product has because it belongs to a certain category.

1. Recommendations related to the main parameters

Each such recommendation applies to the only parameter. To fill in this parameter, use the request POST businesses/{businessId}/offer-mappings/update.

Recommendations for filling in the parameters in updateOfferMappings:

  • RECOGNIZED_VENDOR — write the manufacturer's name as the manufacturer himself writes it (parameter vendor).

  • PICTURE_COUNT — add images (parameter pictures). Requirements

    The percentage of its completion is sent for the recommendation.

  • FIRST_PICTURE_SIZE— replace the first image with a larger one (parameter pictures). Requirements

  • TITLE_LENGTH — change the name (parameter name). Make a name according to the scheme: type + brand or manufacturer + model + features, if any (size, weight, color). Requirements

  • DESCRIPTION_LENGTH — add a description of the recommended size (parameter description). Requirements

  • AVERAGE_PICTURE_SIZE — replace all images with high-quality images (parameter pictures). Requirements

  • FIRST_VIDEO_LENGTH — add the first video of the recommended length (parameter videos). Requirements

  • FIRST_VIDEO_SIZE — replace the first video with a high-quality video (parameter videos). Requirements

  • AVERAGE_VIDEO_SIZE — replace all videos with high-quality videos (parameter videos). Requirements

  • VIDEO_COUNT — add at least one video (parameter videos). Requirements

    The percentage of its completion is sent for the recommendation.

2. Recommendations related to characteristics by category

Each such recommendation involves filling out one or more characteristics. To find out exactly which characteristics you need to fill out, use the request POST category/{categoryId}/parameters. For example, if you have received a recommendation MAIN, you need to fill in the characteristics that have MAIN in the array recommendationTypes.

Recommendations:

  • MAIN — fill in the key product characteristics that are used in the search and filters.

    The percentage of its completion is sent for the recommendation.

  • ADDITIONAL — fill in additional product specifications.

    The percentage of its completion is sent for the recommendation.

  • DISTINCTIVE — fill in the characteristics that distinguish the product options from each other.

    The percentage of its completion is sent for the recommendation.

3. Outdated recommendations

  • HAS_VIDEO.
  • FILTERABLE.
  • HAS_DESCRIPTION.
  • HAS_BARCODE.

Enum: HAS_VIDEO, RECOGNIZED_VENDOR, MAIN, ADDITIONAL, DISTINCTIVE, FILTERABLE, PICTURE_COUNT, HAS_DESCRIPTION, HAS_BARCODE, FIRST_PICTURE_SIZE, TITLE_LENGTH, DESCRIPTION_LENGTH, AVERAGE_PICTURE_SIZE, FIRST_VIDEO_SIZE, FIRST_VIDEO_LENGTH, AVERAGE_VIDEO_SIZE, VIDEO_COUNT

percent

Type: integer<int32>

Percentage of implementation of the recommendation.

Specified for certain types of recommendations:

  • PICTURE_COUNT.
  • VIDEO_COUNT.
  • MAIN.
  • ADDITIONAL.
  • DISTINCTIVE.

Min value: 0

Max value (exclusive): 100

remainingRatingPoints

Type: integer<int32>

The maximum number of card rating points that can be obtained for following recommendations.

Min value: 1

Max value: 100

OfferCardRecommendationType

A recommendation for adding or replacing content. It is not refunded for cards that are filled with the Market or contain used goods.

Some of the recommendations relate to the main parameters, which are available for products of any category. Others belong to those characteristics which the product has because it belongs to a certain category.

1. Recommendations related to the main parameters

Each such recommendation applies to the only parameter. To fill in this parameter, use the request POST businesses/{businessId}/offer-mappings/update.

Recommendations for filling in the parameters in updateOfferMappings:

  • RECOGNIZED_VENDOR — write the manufacturer's name as the manufacturer himself writes it (parameter vendor).

  • PICTURE_COUNT — add images (parameter pictures). Requirements

    The percentage of its completion is sent for the recommendation.

  • FIRST_PICTURE_SIZE— replace the first image with a larger one (parameter pictures). Requirements

  • TITLE_LENGTH — change the name (parameter name). Make a name according to the scheme: type + brand or manufacturer + model + features, if any (size, weight, color). Requirements

  • DESCRIPTION_LENGTH — add a description of the recommended size (parameter description). Requirements

  • AVERAGE_PICTURE_SIZE — replace all images with high-quality images (parameter pictures). Requirements

  • FIRST_VIDEO_LENGTH — add the first video of the recommended length (parameter videos). Requirements

  • FIRST_VIDEO_SIZE — replace the first video with a high-quality video (parameter videos). Requirements

  • AVERAGE_VIDEO_SIZE — replace all videos with high-quality videos (parameter videos). Requirements

  • VIDEO_COUNT — add at least one video (parameter videos). Requirements

    The percentage of its completion is sent for the recommendation.

2. Recommendations related to characteristics by category

Each such recommendation involves filling out one or more characteristics. To find out exactly which characteristics you need to fill out, use the request POST category/{categoryId}/parameters. For example, if you have received a recommendation MAIN, you need to fill in the characteristics that have MAIN in the array recommendationTypes.

Recommendations:

  • MAIN — fill in the key product characteristics that are used in the search and filters.

    The percentage of its completion is sent for the recommendation.

  • ADDITIONAL — fill in additional product specifications.

    The percentage of its completion is sent for the recommendation.

  • DISTINCTIVE — fill in the characteristics that distinguish the product options from each other.

    The percentage of its completion is sent for the recommendation.

3. Outdated recommendations

  • HAS_VIDEO.
  • FILTERABLE.
  • HAS_DESCRIPTION.
  • HAS_BARCODE.

Type

Description

OfferCardRecommendationType

Enum: HAS_VIDEO, RECOGNIZED_VENDOR, MAIN, ADDITIONAL, DISTINCTIVE, FILTERABLE, PICTURE_COUNT, HAS_DESCRIPTION, HAS_BARCODE, FIRST_PICTURE_SIZE, TITLE_LENGTH, DESCRIPTION_LENGTH, AVERAGE_PICTURE_SIZE, FIRST_VIDEO_SIZE, FIRST_VIDEO_LENGTH, AVERAGE_VIDEO_SIZE, VIDEO_COUNT

400 Bad Request

The request contains incorrect data. More information about the error

Body

application/json
{
    "status": "OK",
    "errors": [
        {
            "code": "string",
            "message": "string"
        }
    ]
}

Name

Description

errors

Type: ApiErrorDTO[]

A list of errors.
The general error format.

Min items: 1

status

Type: ApiResponseStatusType

The type of response. Possible values:

  • OK — there are no mistakes.
  • ERROR — an error occurred while processing the request.

Enum: OK, ERROR

ApiErrorDTO

The general error format.

Name

Description

code*

Type: string

The error code.

message

Type: string

Description of the error.

401 Unauthorized

The authorization data is not specified in the request. More information about the error

Body

application/json
{
    "status": "OK",
    "errors": [
        {
            "code": "string",
            "message": "string"
        }
    ]
}

Name

Description

errors

Type: ApiErrorDTO[]

A list of errors.
The general error format.

Min items: 1

status

Type: ApiResponseStatusType

The type of response. Possible values:

  • OK — there are no mistakes.
  • ERROR — an error occurred while processing the request.

Enum: OK, ERROR

403 Forbidden

The authorization data is incorrect or access to the resource is prohibited. More information about the error

Body

application/json
{
    "status": "OK",
    "errors": [
        {
            "code": "string",
            "message": "string"
        }
    ]
}

Name

Description

errors

Type: ApiErrorDTO[]

A list of errors.
The general error format.

Min items: 1

status

Type: ApiResponseStatusType

The type of response. Possible values:

  • OK — there are no mistakes.
  • ERROR — an error occurred while processing the request.

Enum: OK, ERROR

404 Not Found

The requested resource was not found. More information about the error

Body

application/json
{
    "status": "OK",
    "errors": [
        {
            "code": "string",
            "message": "string"
        }
    ]
}

Name

Description

errors

Type: ApiErrorDTO[]

A list of errors.
The general error format.

Min items: 1

status

Type: ApiResponseStatusType

The type of response. Possible values:

  • OK — there are no mistakes.
  • ERROR — an error occurred while processing the request.

Enum: OK, ERROR

420 Method Failure

The resource access limit has been exceeded. More information about the error

Body

application/json
{
    "status": "OK",
    "errors": [
        {
            "code": "string",
            "message": "string"
        }
    ]
}

Name

Description

errors

Type: ApiErrorDTO[]

A list of errors.
The general error format.

Min items: 1

status

Type: ApiResponseStatusType

The type of response. Possible values:

  • OK — there are no mistakes.
  • ERROR — an error occurred while processing the request.

Enum: OK, ERROR

500 Internal Server Error

Internal error in Yandex. Market. More information about the error

Body

application/json
{
    "status": "OK",
    "errors": [
        {
            "code": "string",
            "message": "string"
        }
    ]
}

Name

Description

errors

Type: ApiErrorDTO[]

A list of errors.
The general error format.

Min items: 1

status

Type: ApiResponseStatusType

The type of response. Possible values:

  • OK — there are no mistakes.
  • ERROR — an error occurred while processing the request.

Enum: OK, ERROR

No longer supported, please use an alternative and newer version.

Previous
Changing the terms of sale
Next
Editing product category characteristics