Getting information about the fullness of store cards

Info

Console

The method is available for models: FBY, FBS, Express and DBS.

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

offers-and-cards-management — Manage products and cards
offers-and-cards-management:read-only — View products and cards
all-methods — Full account management
all-methods:read-only — View all data

Returns information about the content status for the specified products:

whether a product card has been created and what is its status.
card rating — how many percent is it filled;
transmitted product characteristics;
are there any errors or warnings related to the content;
recommendations for filling out the card.

To get other product characteristics, use the method POST v2/businesses/{businessId}/offer-mappings.

⚙️ Limit: 600 requests per minute

Request

POST

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

Path parameters

Name

Description

businessId

Type: integer

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

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

Min value: 1

Query parameters

Name

Description

limit

Type: integer

The number of values per page.

Min value: 1

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": [
    "example"
  ],
  "cardStatuses": [
    "HAS_CARD_CAN_NOT_UPDATE"
  ],
  "categoryIds": [
    0
  ],
  "withRecommendations": false
}

Name	Description
cardStatuses	Type: string[] \| null Filter by card status. What is a product card? Min items: `1` Unique items: `true` Example `[ "HAS_CARD_CAN_NOT_UPDATE" ]`
categoryIds	Type: integer[] \| null Filter by category on the Market. Min items: `1` Max items: `200` Unique items: `true` Example `[ 0 ]`
offerIds	Type: string[] \| null 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. Min items: `1` Max items: `200` Unique items: `true` Example `[ "example" ]`
withRecommendations	Type: boolean Should I return the list of recommendations for filling out the card and the average rating of the card for products of the category indicated in `marketCategoryId`. Default value: `false`. If the information is needed, pass the value `true`. Default: `false`

Responses

200 OK

Information about the cards of the specified products.

Body

application/json

{
  "status": "OK",
  "result": {
    "offerCards": [
      {
        "offerId": "example",
        "mapping": {},
        "parameterValues": [
          null
        ],
        "cardStatus": "HAS_CARD_CAN_NOT_UPDATE",
        "contentRating": 0,
        "averageContentRating": 0,
        "contentRatingStatus": "UPDATING",
        "recommendations": [
          null
        ],
        "groupId": "example",
        "errors": [
          null
        ],
        "warnings": [
          null
        ]
      }
    ],
    "paging": {
      "nextPageToken": "example"
    }
  }
}

Type: object

All of 2 types

Type: object
status

Type: string

The type of response. Possible values:

OK — There are no errors.

ERROR — an error occurred while processing the request.

Enum: OK, ERROR
The standard wrapper for server responses.
Example
```
{
  "status": "OK"
}
```

Type: object

result

Type: object

offerCards

Type: object[]

offerId

Type: string

Your SKU — the product ID in your system.

Usage rules SKU:

For each product SKU there must be one.
Already set SKU it cannot be released and reused for another product. Each product should receive a new identifier that has never been used in your catalog before.

SKU 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.

Warning

Spaces at the beginning and end of the value are automatically deleted. For example, " SKU123 " and "SKU123" they will be treated as identical values.

What is SKU and how to assign it

Min length: 1

Max length: 255

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

Example: example

averageContentRating

Type: integer

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

Returned only if the parameter withRecommendations it matters true.

cardStatus

Type: string

Product card status:

HAS_CARD_CAN_NOT_UPDATE — The Market card.
HAS_CARD_CAN_UPDATE — You can add it.
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 was not created due to an error.
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

The rating of the card.

contentRatingStatus

Type: string

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

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

Enum: UPDATING, ACTUAL

errors

Type: object[]

comment

Type: string

Explanation.

Example: example

message

Type: string

The type of error.

Example: example

Errors in the content that prevent the product from being placed in the showcase.

Min items: 1

Example

[
  {
    "message": "example",
    "comment": "example"
  }
]

groupId

Type: string

The identifier of the product group.

Products that are grouped together will have the same identifier.

How to combine products on a card

Example: example

mapping

Type: object

All of 2 types

Type: object

marketSku

Type: integer

The ID of the product card on the Market.

Min value: 1

A card on the Market that, from your point of view, fits the product. To determine the ID of the appropriate card, use the search in the cabinet (Products → Catalog → Upload products).

Based on the verification results, the Market can link the product to a more suitable card.
Example
```
{
  "marketSku": 1
}
```

Type: object

marketCategoryId	Type: integer The ID of the category on the Market that the product is in. 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. Example: `example`
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. Example: `example`
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. Example: `example`

Example

{
  "marketSkuName": "example",
  "marketModelName": "example",
  "marketCategoryId": 0,
  "marketCategoryName": "example"
}

Information about the products in the catalog.

Example

{
  "marketSku": 1,
  "marketSkuName": "example",
  "marketModelName": "example",
  "marketCategoryId": 0,
  "marketCategoryName": "example"
}

parameterValues

Type: object[]

parameterId	Type: integer The identifier of the characteristic. Min value: `1`
unitId	Type: integer 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` send: Together with `valueId`, if you take the value from the directory; without `valueId`, if the value is its own. Example: `example`
valueId	Type: integer 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. Do not specify for your own values. Only for type characteristics `ENUM`.

A list of characteristics with their values.

Min items: 1

Example

[
  {
    "parameterId": 1,
    "unitId": 0,
    "valueId": 0,
    "value": "example"
  }
]

recommendations

Type: object[]

type

Type: string

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 that products of any category have. Other — to those characteristics which the product has because it belongs to a certain category.

1. Recommendations related to the main parameters

Each such recommendation refers to a single parameter. To fill in this parameter, use the request POST v2/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 requires filling in one or more characteristics **. To find out exactly which characteristics you need to fill out, use the request POST v2/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

Percentage of implementation of the recommendation.

Specified for certain types of recommendations:

PICTURE_COUNT.
VIDEO_COUNT.
MAIN.
ADDITIONAL.
DISTINCTIVE.

Min value: 0

Max value: 100

Exclusive max: true

remainingRatingPoints

Type: integer

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

Min value: 1

Max value: 100

A list of recommendations for filling out the card.

Returned only if the parameter withRecommendations it matters true.

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.

Min items: 1

Example

[
  {
    "type": "HAS_VIDEO",
    "percent": 0,
    "remainingRatingPoints": 1
  }
]

warnings

Type: object[]

comment

Type: string

Explanation.

Example: example

message

Type: string

The type of error.

Example: example

Content-related warnings that do not prevent the product from being placed in the showcase.

Min items: 1

Example

[
  {
    "message": "example",
    "comment": "example"
  }
]

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

Example

[
  {
    "offerId": "example",
    "mapping": {
      "marketSku": 1,
      "marketSkuName": "example",
      "marketModelName": "example",
      "marketCategoryId": 0,
      "marketCategoryName": "example"
    },
    "parameterValues": [
      {
        "parameterId": 1,
        "unitId": 0,
        "valueId": 0,
        "value": "example"
      }
    ],
    "cardStatus": "HAS_CARD_CAN_NOT_UPDATE",
    "contentRating": 0,
    "averageContentRating": 0,
    "contentRatingStatus": "UPDATING",
    "recommendations": [
      {
        "type": "HAS_VIDEO",
        "percent": 0,
        "remainingRatingPoints": 1
      }
    ],
    "groupId": "example",
    "errors": [
      {
        "message": "example",
        "comment": "example"
      }
    ],
    "warnings": [
      {
        "message": "example",
        "comment": "example"
      }
    ]
  }
]

paging

Type: object

nextPageToken

Type: string

ID of the next results page.

Example: example

The ID of the next page.

Example

{
  "nextPageToken": "example"
}

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

Example

{
  "offerCards": [
    {
      "offerId": "example",
      "mapping": {
        "marketSku": 1,
        "marketSkuName": "example",
        "marketModelName": "example",
        "marketCategoryId": 0,
        "marketCategoryName": "example"
      },
      "parameterValues": [
        {
          "parameterId": 1,
          "unitId": 0,
          "valueId": 0,
          "value": "example"
        }
      ],
      "cardStatus": "HAS_CARD_CAN_NOT_UPDATE",
      "contentRating": 0,
      "averageContentRating": 0,
      "contentRatingStatus": "UPDATING",
      "recommendations": [
        {
          "type": "HAS_VIDEO",
          "percent": 0,
          "remainingRatingPoints": 1
        }
      ],
      "groupId": "example",
      "errors": [
        {
          "message": "example",
          "comment": "example"
        }
      ],
      "warnings": [
        {
          "message": "example",
          "comment": "example"
        }
      ]
    }
  ],
  "paging": {
    "nextPageToken": "example"
  }
}

Example

{
  "result": {
    "offerCards": [
      {
        "offerId": "example",
        "mapping": {},
        "parameterValues": [
          {}
        ],
        "cardStatus": "HAS_CARD_CAN_NOT_UPDATE",
        "contentRating": 0,
        "averageContentRating": 0,
        "contentRatingStatus": "UPDATING",
        "recommendations": [
          {}
        ],
        "groupId": "example",
        "errors": [
          {}
        ],
        "warnings": [
          {}
        ]
      }
    ],
    "paging": {
      "nextPageToken": "example"
    }
  }
}

400 Bad Request

The request contains incorrect data. More information about the error

Body

application/json

{
  "status": "OK",
  "errors": [
    {
      "code": "example",
      "message": "example"
    }
  ]
}

Type: object

All of 1 type

Type: object

All of 2 types

Type: object
status
Type: string

The type of response. Possible values:

OK — There are no errors.

ERROR — an error occurred while processing the request.

Enum: OK, ERROR
The standard wrapper for server responses.
Example
```
{
  "status": "OK"
}
```

Type: object

errors

Type: object[]

code

Type: string

The error code.

Example: example

message

Type: string

Description of the error.

Example: example

A list of errors.

Min items: 1

Example

[
  {
    "code": "example",
    "message": "example"
  }
]

Example

{
  "errors": [
    {
      "code": "example",
      "message": "example"
    }
  ]
}

A standard wrapper for server errors.

Example

{
  "status": "OK",
  "errors": [
    {
      "code": "example",
      "message": "example"
    }
  ]
}

401 Unauthorized

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

Body

application/json

{
  "status": "OK",
  "errors": [
    {
      "code": "example",
      "message": "example"
    }
  ]
}

Type: object

All of 1 type

Type: object

All of 2 types

Type: object
status
Type: string

The type of response. Possible values:

OK — There are no errors.

ERROR — an error occurred while processing the request.

Enum: OK, ERROR
The standard wrapper for server responses.
Example
```
{
  "status": "OK"
}
```

Type: object

errors

Type: object[]

code

Type: string

The error code.

Example: example

message

Type: string

Description of the error.

Example: example

A list of errors.

Min items: 1

Example

[
  {
    "code": "example",
    "message": "example"
  }
]

Example

{
  "errors": [
    {
      "code": "example",
      "message": "example"
    }
  ]
}

A standard wrapper for server errors.

Example

{
  "status": "OK",
  "errors": [
    {
      "code": "example",
      "message": "example"
    }
  ]
}

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": "example",
      "message": "example"
    }
  ]
}

Type: object

All of 1 type

Type: object

All of 2 types

Type: object
status
Type: string

The type of response. Possible values:

OK — There are no errors.

ERROR — an error occurred while processing the request.

Enum: OK, ERROR
The standard wrapper for server responses.
Example
```
{
  "status": "OK"
}
```

Type: object

errors

Type: object[]

code

Type: string

The error code.

Example: example

message

Type: string

Description of the error.

Example: example

A list of errors.

Min items: 1

Example

[
  {
    "code": "example",
    "message": "example"
  }
]

Example

{
  "errors": [
    {
      "code": "example",
      "message": "example"
    }
  ]
}

A standard wrapper for server errors.

Example

{
  "status": "OK",
  "errors": [
    {
      "code": "example",
      "message": "example"
    }
  ]
}

404 Not Found

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

Body

application/json

{
  "status": "OK",
  "errors": [
    {
      "code": "example",
      "message": "example"
    }
  ]
}

Type: object

All of 1 type

Type: object

All of 2 types

Type: object
status
Type: string

The type of response. Possible values:

OK — There are no errors.

ERROR — an error occurred while processing the request.

Enum: OK, ERROR
The standard wrapper for server responses.
Example
```
{
  "status": "OK"
}
```

Type: object

errors

Type: object[]

code

Type: string

The error code.

Example: example

message

Type: string

Description of the error.

Example: example

A list of errors.

Min items: 1

Example

[
  {
    "code": "example",
    "message": "example"
  }
]

Example

{
  "errors": [
    {
      "code": "example",
      "message": "example"
    }
  ]
}

A standard wrapper for server errors.

Example

{
  "status": "OK",
  "errors": [
    {
      "code": "example",
      "message": "example"
    }
  ]
}

420 Method Failure

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

Body

application/json

{
  "status": "OK",
  "errors": [
    {
      "code": "example",
      "message": "example"
    }
  ]
}

Type: object

All of 1 type

Type: object

All of 2 types

Type: object
status
Type: string

The type of response. Possible values:

OK — There are no errors.

ERROR — an error occurred while processing the request.

Enum: OK, ERROR
The standard wrapper for server responses.
Example
```
{
  "status": "OK"
}
```

Type: object

errors

Type: object[]

code

Type: string

The error code.

Example: example

message

Type: string

Description of the error.

Example: example

A list of errors.

Min items: 1

Example

[
  {
    "code": "example",
    "message": "example"
  }
]

Example

{
  "errors": [
    {
      "code": "example",
      "message": "example"
    }
  ]
}

A standard wrapper for server errors.

Example

{
  "status": "OK",
  "errors": [
    {
      "code": "example",
      "message": "example"
    }
  ]
}

500 Internal Server Error

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

Body

application/json

{
  "status": "OK",
  "errors": [
    {
      "code": "example",
      "message": "example"
    }
  ]
}

Type: object

All of 1 type

Type: object

All of 2 types

Type: object
status
Type: string

The type of response. Possible values:

OK — There are no errors.

ERROR — an error occurred while processing the request.

Enum: OK, ERROR
The standard wrapper for server responses.
Example
```
{
  "status": "OK"
}
```

Type: object

errors

Type: object[]

code

Type: string

The error code.

Example: example

message

Type: string

Description of the error.

Example: example

A list of errors.

Min items: 1

Example

[
  {
    "code": "example",
    "message": "example"
  }
]

Example

{
  "errors": [
    {
      "code": "example",
      "message": "example"
    }
  ]
}

A standard wrapper for server errors.

Example

{
  "status": "OK",
  "errors": [
    {
      "code": "example",
      "message": "example"
    }
  ]
}

Was the article helpful?

Getting a barcode file (FBY)

Editing product category characteristics