We will sunset v2 of the Content API on March 29th, 2021. To avoid disruptions with your integration, please migrate to v2.1 as soon as possible. For more information, see Migrating to v2.1.

API Issue Severity and Diagnostics Issue Prioritization

Suppose you want to get information on the products currently available in your account. In particular, you're interested in knowing whether any of your products have issues that need addressing. You know how to get this information from the Merchant Center, but you'd rather set up an automatic alerting system using the Content API. In this guide, we'll go through how the issue severity information in the Content API maps to the issue prioritization seen in the Diagnostics reports in the Merchant Center.

An example interaction with the Content API

To get the issues affecting your products, you can run Accountstatuses.get for your account. Here's a cut down example of the resource you get back:

{
 "kind": "content#accountStatus",
 "accountId": "...",
 "accountLevelIssues": [
    {
     "id": "editorial_and_professional_standards_destination_url_down_policy",
     "title": "Account suspended due to policy violation: landing page not working",
     "country": "US",
     "severity": "critical",
     "documentation": "https://support.google.com/merchants/answer/6150244#wycd-usefulness"
    },
    {
     "id": "missing_ad_words_link",
     "title": "No Google Ads account linked",
     "severity": "error",
     "documentation": "https://support.google.com/merchants/answer/6159060"
    }
   ],
   "products": [
      {
       "channel": "online",
       "destination": "Shopping",
       "country": "US",
       "statistics": {
        "active": "0",
        "pending": "0",
        "disapproved": "5",
        "expiring": "0"
       },
       "itemLevelIssues": [
        {
         "code": "image_link_broken",
         "servability": "disapproved",
         "resolution": "merchant_action",
         "attributeName": "image link",
         "description": "Invalid image [image link]",
         "detail": "Ensure the image is accessible and uses an accepted image format (JPEG, PNG, GIF)",
         "documentation": "https://support.google.com/merchants/answer/6098289",
         "numItems": "2"
        },
        {
         "code": "landing_page_error",
         "servability": "disapproved",
         "resolution": "merchant_action",
         "attributeName": "link",
         "description": "Unavailable desktop landing page",
         "detail": "Update your website or landing page URL to enable access from desktop devices",
         "documentation": "https://support.google.com/merchants/answer/6098155",
         "numItems": "5"
        }
      ]
     },
  ...
}

Under accountLevelIssues[].severity, you see the severity of Merchant Center account errors. Critical errors will cause an account suspension, which will stop you from serving your products.

Under itemLevelIssues, you can see the product errors that can lead to product disapprovals. Note that itemLevelIssues[].numItems lets you know that 2 items in your account are affected by a broken image link, and 5 items have a landing page error.

Under itemLevelIssues[].servability, you can see whether the error causes the affected products to be disapproved. Note that both the broken image link and the landing page error cause products to be disapproved.

To find all the affected products, you call Productstatuses.list to get a complete list of issues on a per-product basis. It returns entries like the following:

 {
  "kind": "content#productstatusesListResponse",
  ...
  "resources": [
   {
     "kind": "content#productStatus",
     "productId": "online:en:US:online-en-US-GGL614",
     ...
     "itemLevelIssues": [
       {
         "code": "mobile_landing_page_crawling_not_allowed",
         "servability": "disapproved",
         "resolution": "merchant_action",
         "attributeName": "link",
         "destination": "Shopping",
         "description": "Mobile page not crawlable due to robots.txt",
         "detail": "Update your robots.txt file to allow user-agents \"Googlebot\" and \"Googlebot-Image\" to crawl your site",
         "documentation": "https://support.google.com/merchants/answer/6098296"
       },
       {
         "code": "pending_initial_policy_review",
         "servability": "disapproved",
         "resolution": "pending_processing",
         "destination": "Shopping",
         "description": "Pending initial review",
         "documentation": "https://support.google.com/merchants/answer/2948694"
       },
       {
         "code": "ambiguous_gtin",
         "servability": "unaffected",
         "resolution": "merchant_action",
         "attributeName": "gtin",
         "destination": "Shopping",
         "description": "Ambiguous value [gtin]",
         "detail": "Use the full GTIN. Include leading zeroes, and use the full UPC, EAN, JAN, ISBN-13, or ITF-14.",
         "documentation": "https://support.google.com/merchants/answer/7000891"
       }
     ],
     ...
   },
   ...
   ]
 }

Now you have information about the issues for all the products in your account, but it’s unclear how important it is to fix these issues.

In our Productstatuses example, you can use itemLevelIssues[].servability to discover whether an error disables your ability to serve the product in Shopping Actions, Shopping Ads, or Surfaces across Google.

If itemLevelIssues[].servability is unaffected like the ambiguous_gtin error, the error will not prevent your product from serving.

However, if itemLevelIssues[].servability is disapproved like the mobile_landing_page_crawling_not_allowed error, this is a much more serious error since you cannot serve your product until the error is fixed.

In our Accountstatuses example, under accountLevelIssues[].severity, the Diagnostics section in Merchant Center defines issue prioritization and precisely what the different priorities mean.

First, take a look at the report:

Diagnostics report from Merchant Center

How does all the information you're getting from the Content API for Shopping correlate with what you see in the Diagnostics section? Which entries are issues you need to fix ASAP, and which ones would be nice to tackle, but are not essential to fix? Which issues will stop your products from serving in your ads if unaddressed?

As shown in these examples, the Diagnostics section provides severity information about issues for the account and products on that account, while the Content API (via the Accountstatuses service) provides severity information solely for accountLevel issues.

Each source divides issues into three categories based on the severity of the issue. Understanding how to judge the severity of issues returned from the status-related services can help quickly pinpoint which issues are the most important to address, and which issues can be safely ignored.

Issue prioritization and issue severity

In the Diagnostics section, the issue prioritization describes the issue severity as one of three levels: errors, warnings, and notifications. In report tables like the one above, these levels are represented by images that appear in the first column: Error for errors, Warning for warnings, and Notification for notifications.

  • Errors have caused either an account suspension or an item disapproval. They should be resolved as soon as possible to ensure items are eligible to appear in results again.

  • Warnings could negatively impact the performance of your ads and will likely lead to item or account suspensions in the future unless the issue is resolved.

  • Notifications are suggested optimizations to increase data quality. Resolving these issues is recommended, but not required.

We need not visit Merchant Center to find out which errors are which, though. In the Content API, the accountLevelIssues[].severity field in the Accountstatuses resource objects provides the same issue severity information. These fields can contain one of three values: critical, error, and suggestion.

These values have a one-to-one correspondence with the issue prioritization on the Diagnostics tab:

Data Quality Issue Severity (API) Issue Prioritization
critical Error (Error)
error Warning (Warning)
suggestion Notification (Notification)

So in our Accountstatuses example, the missing_ad_words_link issue lets you know that you need to link a Google Ads account to serve ads, but it won't affect the product's approval in your Merchant Center database. On the other hand, the editorial_and_professional_standards_destination_url_down_policy is a more severe error that suspends your account. If you are participating in Shopping Actions, Surfaces across Google, or if you had a linked Google Ads account, a critical error stops your products from serving in the Shopping Actions, Surfaces across Google, and Shopping Ads programs immediately.

Armed with this information, you can now write alerting software that will bring important issues to your attention immediately while collecting less serious issues for eventual fixing, without having to visit Merchant Center to discern which is which.