Get Product Diagnoses

GET

/product/202405/products/diagnoses

Diagnose multiple existing live (status: ACTIVATE) products to obtain information that helps you to improve the product content, enhancing product visibility and customer trust. The returned information includes:

• Listing quality information (available only for the US market).
• Issues with the current product details and the overall recommendations
• Auto-generated optimization suggestions targeted for specific product fields, including the title, description, and image. Note: This API focuses solely on optimizing product visibility and does not evaluate whether your product meets listing requirements. Quality issues identified by this API do not block your product from being listed. To verify listing requirements, use the Check Product Listing API.

Authorizations

• accessToken

Parameters

Query Parameters

shop_cipher

required

string

Identifies the shop. Obtain it from the Get Authorized Shops API.

product_ids

required

Array<string>

The list of product IDs that you want to diagnose.

Note:

• Max number of IDs: 200
• The product must be live (status: ACTIVATE)

Responses

200

Success

Media typeapplication/json

object

code

Status code; 0 means success.

integer format: int64

message

Success or failure message.

string

request_id

Request log ID.

string

data

object

products

The list of requested products and the corresponding diagnosis results.

Array<object>

object

id

The product ID.

string

listing_quality

Product listing quality information.

object

current_tier

The current quality tier of this product listing. The quality tier of a product listing depends on the quality of the content in its product fields such as the title, image, attributes etc.

Possible values:

• POOR
• FAIR
• GOOD

NOTE: Available only for the US market.

string

Allowed values: POOR FAIR GOOD

remaining_recommendations

The remaining number of recommendations (see diagnosis_results) that must be implemented for the product to advance to the highest tier.

Note:

• To advance to the highest tier, you must implement all recommendations listed in diagnosis_results.
• Available only for the US market.

integer format: int64

diagnoses

Product diagnosis and optimization information.

Array<object>

object

field

The product field being diagnosed. Possible values:

• TITLE: Product title
• DESCRIPTION: Product description
• IMAGE: Product image displayed in the image gallery
• ATTRIBUTE: Product attribute
• SIZE_CHART: Product size chart

string

Allowed values: TITLE DESCRIPTION IMAGE ATTRIBUTE SIZE_CHART

diagnosis_results

The results of diagnosing the specified field.

Array<object>

object

code

A machine-readable code that represents an identified issue. Refer to Listing quality diagnosis for the full list of identified issues and the corresponding recommendations.

string

how_to_solve

The recommendation for resolving the identified issue, returned in the default locale language of the shop. Refer to Listing quality diagnosis for the full list of recommendations.

string

quality_tier

The listing quality tier you can reach by implementing the recommendation. Possible values:

• FAIR
• GOOD

Note:

• To reach a higher tier, you must implement all recommendations from the destination tier and all preceding tiers. For example, a product will reach the “GOOD” tier once all “FAIR” and “GOOD” recommendations are addressed or implemented.
• Available only for the US market.

string

Allowed values: FAIR GOOD

suggestion

Optimization suggestions that are auto-generated by the system to improve the effectiveness of the specified field.

Note: This will not be returned if the value for optimization_fields is blank or NONE.

object

seo_words

The SEO keyword suggestions if diagnoses.field is “TITLE”.

Array<object>

object

text

The suggested SEO keyword text.

string

smart_texts

The intelligent text suggestions for titles and descriptions.

Array<object>

object

text

The suggested intelligent text.

string

images

The optimized main image. Only the first image in the main image set will be optimized.

Array<object>

object

height

The image height after optimization.

integer format: int64

width

The image width after optimization.

integer format: int64

uri

The original URI of the image.

string

url

The original URL of the image.

string

optimized_uri

The URI of the image after optimization.

string

optimized_url

The URL of the image after optimization.

string

Example

{
  "code": 0,
  "data": {
    "products": [
      {
        "id": "123456",
        "listing_quality": {
          "current_tier": "POOR",
          "remaining_recommendations": 3
        },
        "diagnoses": [
          {
            "field": "TITLE",
            "diagnosis_results": [
              {
                "code": "TITLE_LESS_THAN_40_CHARACTERS",
                "how_to_solve": "Names must be at least 40 characters long and contain product-identifying information, such as \"hiking boots\" or \"lipstick\".",
                "quality_tier": "GOOD"
              }
            ],
            "suggestion": {
              "seo_words": [
                {
                  "text": "dress"
                }
              ],
              "smart_texts": [
                {
                  "text": "this is a good title"
                }
              ],
              "images": [
                {
                  "height": 600,
                  "width": 600,
                  "uri": "tos-maliva-i-o3syd03w52-us/53b55d6e8cdf1f315affa7e70b45707d",
                  "url": "https://p16-graph-va.ibyteimg.com/tos-maliva-i-1por3rr4fy-us/v2/53b55d6e8cdf1f315affa7e70b45707d~tplv-1por3rr4fy-image.webp",
                  "optimized_uri": "tos-maliva-i-o3syd03w52-us/0266127022264e54ad2f639f5e0fb5e6",
                  "optimized_url": "https://p16-graph-va.ibyteimg.com/tos-maliva-i-1por3rr4fy-us/v2/0266127022264e54ad2f639f5e0fb5e6~tplv-1por3rr4fy-image.webp"
                }
              ]
            }
          }
        ]
      }
    ]
  },
  "message": "Success",
  "request_id": "202203070749000101890810281E8C70B7"
}