Tag Archives: content_api

Country targeting update for products in Content API for Shopping and Google Ads API

On August 10, 2022, we announced a change to country targeting for shopping products with the introduction of the feedLabel field. We’d like to update you on the progress of this change. Here are our previous announcements: What’s already changed

Google Ads:
Any Google Ads account can set the feed_label field in ShoppingSetting for Shopping and Performance Max campaigns. You can set feed_label in the Google Ads UI and the Google Ads API.

Merchant Center & Content API:
As of September 14th, 2022 we‘ve started the gradual rollout of feed labels in the Merchant Center UI. When this feature is enabled in the UI, merchants will be able to create a new feed with feed label set to any valid string. See Use feed labels to advertise products from specific feeds for more information.

In the Content API, you might see the following:
  • Products that have only feedLabel, and not targetCountry, if they were added in the Merchant Center UI.
  • Products with feed labels that aren’t two-letter country codes.
You can now use Products.update to update products by feedLabel. For example, if you had a product with offerId of “111111111” and a feedLabel set to “WINTERPRODUCTS”, you can now update attributes such as salePrice for that product by making the following call:
HTTP request:

PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/online:en:WINTERPRODUCTS:1111111111
Example request body:

{
  "salePrice": {
    "value": "17.99",
    "currency": "USD"
  }
}
Behavior summary:
Here’s a clarification of the current API behavior for feedLabel:
  • Insertion: You can only call Products.insert on products with a matching feedLabel and targetCountry. Currently, Products.insert might return an error if you don’t provide a matching targetCountry. This behavior hasn’t changed if you continue to use only targetCountry.
  • Targeting: If you set feedLabel to a valid 2-letter CLDR territory code, you must still set the shipping attribute of the products resource to the same country in order to target that country. For example, if you set a new feedLabel to “US”, you must also set the country field in the shipping attribute to “US”. If you don’t set both fields, the product might not be eligible to serve in that country. You can configure targeting for an entire feed in the Merchant Center UI.
  • Get/List: When you use Products.list or Products.get, you might see products that only have feedLabel (and not targetCountry) set if they were added in the Merchant Center UI.
  • Product IDs: Once a feedLabel is set for a product it becomes part of the product Id. This means you can’t modify the feedLabel for that product (this is similar to how language works). If you wish to change the feedLabel you will need to create a new product with a different product Id.
What’s coming next

Products:
Once the gradual rollout of feed labels in the Merchant Center UI is complete, we will accept Products.insert calls with feedLabel set to any string. At this point, including targetCountry will become optional.

Datafeeds:
In late September, we will also update the datafeeds resource to include feedLabel in the Content API for Shopping.

Opt out of receiving products and datafeeds without a country
If you’re concerned your codebase cannot handle products and datafeeds without a country, and you want to opt out of receiving them via the Content API for Shopping, fill out the following form: Feed label replaces target country in the Content API for Shopping - temporary exemption. When you’re ready to support feedLabel, you can opt back in to receiving these offers.
If you have any questions about this change, please visit the Content API for Shopping forum.
Ian Ballantyne, Content API for Shopping Team

Feed label replaces target country in Content API for Shopping

On August 23, 2022 we will gradually start updating the way country targeting works for shopping products. As a result, the targetCountry field for newly inserted products and the country field for new datafeeds may be empty in the Content API for Shopping. While targetCountry and country are now deprecated, there are no plans to remove these fields from v2.1 to preserve backward compatibility. We recommend using feedLabel to name new products and feeds, and using the shipping field to specify the countries to target.

If you're accessing accounts whose product data you don’t have total control over and you are unsure whether the products or datafeeds will have ONLY a feedLabel field beginning in late August, we recommend you update your code to support the feedLabel field.

This upcoming change might impact or break your API integration if your application cannot handle products without a targetCountry or datafeeds without a country.

See Country targeting in Shopping Ads campaigns is changing in August 2022 for how this change will impact Google Ads.

What’s already changed
On August 8, 2022, the Content API for Shopping added the feedLabel field to the products resource. As of August 8, 2022, feedLabel can only accept and return two-letter CLDR territory codes. Products now require either targetCountry or feedLabel. As long as the feedLabel set is a valid two-letter CLDR code, targetCountry will be backfilled for compatibility.

We have changed the definition of the product identifier (the id, i.e. the REST ID). feedLabel now replaces targetCountry as the third component of the identifier, so it is no longer just a valid two-letter CLDR code. You can find an example shown here.

This change to product identifier is backwards compatible, so existing REST IDs for existing products will continue to work without change.

Important: feedLabel doesn’t impact targeting. This means if you use feedLabel instead of targetCountry, you need to specify all countries you want to target in the shipping attribute.

What’s coming next
We’re starting a gradual rollout to all users on August 23, 2022. When the upcoming change reaches you, you’ll be able to create a product or datafeed with any string (not just a two-letter CLDR code) as the feedLabel via the API or the Merchant Center. You’ll still be able to use a two-letter country code in targetCountry for backwards compatibility.

After the upcoming change, if you submit a feedLabel that isn’t a CLDR territory code, the API will return those products without a targetCountry or those datafeeds without a country. Instead, only their feedLabel will be populated. This may break your codebase if your implementation expects a value in targetCountry for products or a value in country for datafeeds.

How you’re impacted
Products
If you continue inserting your products with a targetCountry, you are not required to make any changes at this time, as the feedLabel value in the products REST ID will be identical to the targetCountry you inserted.

However, if you use a feedLabel in Merchant Center or the API that is not a CLDR territory code, we highly recommend you update your codebase to use feedLabels on all product insertions instead of targetCountry to avoid issues with your API integration.

All products inserted with a feedLabel instead of targetCountry, even if the feedLabel is a CLDR territory code, will not automatically target that country. You must explicitly set the countries you want to target via the shipping field.

Datafeeds
Note that starting August 23, 2022, feed label will replace the current country of sale value in the Merchant Center UI. The Content API will be expected to support this change via the datafeeds service starting mid-September. These new datafeeds will only have the feedLabel field set, not the country field, unless you explicitly set the feedLabel to a CLDR territory code.

To support new users, we highly recommend you update your codebase to use feedLabels on all datafeeds instead of country to avoid issues with your API integration.

Recommendation for third party integrations
If you’re a third party or agency that manages your customers' accounts for them, we highly recommend you check your codebase is able handle products without a targetCountry and datafeeds without a country before August 23, 2022.

After the gradual rollout starting in late August, your merchants will be able to modify products directly in Merchant Center to create a product with a feedLabel that is not a valid two-letter CLDR territory code. When this product is returned via products.list, you could encounter issues if your implementation expects a value in targetCountry.

As well, after the gradual rollout in late August, new users will create datafeeds that by default have a feedLabel and no country field. When this datafeed is returned via datafeeds.list, you could encounter issues if your implementation expects a value in country.

How to detect if you have offers without a country in your Merchant Center account
  1. Make a request to products.list.
  2. Filter your products to search for products where the targetCountry field does not exist on the product.
  3. If any products appear, you have offers without a country in your Merchant Center.
Detailed Changes
To view a detailed breakdown of the changes to the Content API by this feature launch, see the guide here.

Datafeeds Service
Starting mid-September the datafeeds service will begin to return feedLabel on all datafeeds, which will be the country value if that is how the datafeed was created. The datafeeds service will also return the country field if the feedLabel is a valid country code for backwards compatibility.

Opt out of receiving products and datafeeds without a country
If you’re concerned your codebase cannot handle products and datafeeds without a country, and you want to opt out of receiving them via the Content API after August 23, then please fill out the following form: Feed label replaces target country in the Content API for Shopping - temporary exemption. Once you have fully supported feedLabel, you will be able to opt back in to receiving these offers.

If you have any questions or concerns, please don't hesitate to contact us via the forum.
Benji Rothman, Content API for Shopping Team

Merchant IDs as 64-bit in Content API for Shopping

In the Content API for Shopping, Merchant IDs are now 64-bit signed integers. Applications that integrate with the Content API must be able to handle ID values in that range.

Historically, Merchant IDs in the Content API for Shopping were within the maximum value of a 32-bit signed integer, but have recently exceeded this range. In order to avoid any issues, please make sure your applications are fully compliant with IDs within a range of 64-bit signed integer values.

If you have any questions or concerns, please don't hesitate to contact us via the forum.
Benji Rothman, Content API for Shopping Team

Upcoming enforcement of custom batch limits in Content API for Shopping

Beginning May 31, 2022 we will enforce the following limits for custom batch methods in the Content API for Shopping:
  • Maximum entries per request: 10,000
  • Maximum transfer size per request: 32Mb (The payload received from the client)
We’re introducing these limits to enable the fair and stable use of Content API for Shopping. The limits will apply to the following endpoints: After May 31, 2022, calls to any of these endpoints that exceed these limits will begin to fail with the following error:
  • request_too_large
Visit our batching guide to learn more about methods for reducing your batch size. If you are looking for a reasonable batch size to implement, we recommend 1,000 entries per request for each endpoint. Following this means you are unlikely to encounter the limits even if your batch size temporarily increases.

If you have any questions about implementing this change, please visit the Content API for Shopping forum.
Ian Ballantyne, Content API for Shopping Team

Introducing the new Merchant Center Status Dashboard

At Google, we strive to provide the highest level of service possible to our users. Still, from time to time, unexpected service disruptions do occur. When your team experiences an outage or other technical challenge, one of the first evaluations they need to make is whether the issue is with a third-party service provider or in-house. As part of our commitment to transparency and speed when communicating the status of our products, and incidents when they happen to occur, we’re pleased to roll out the Merchant Center Status Dashboard.

Check the status of a service
A look at the Merchant Center Status Dashboard

If a major incident is identified, we will generally post an outage notice on the Dashboard and provide updates when the issue is resolved. If the dot is green, it means there are no issues. The Merchant Center Status Dashboard provides status information on the Content API for Shopping, Merchant Center, and Feeds.

You can check the dashboard to view the current status of any of those services. All incidents are first verified by our support engineers, so there may be a slight delay from the time they actually occurred. More information can be found on the Merchant Center Help Center.

Subscribe to the Status Dashboard RSS or JSON feeds
To get the fastest outage alerts, we recommend subscribing to the Status Dashboard RSS feed:
  1. Go to the Status Dashboard.
  2. At the bottom, click RSS Feed and copy the feed URL.
  3. In your RSS reader, paste the URL to add the Status Dashboard feed.
  4. If you want programmatic access to the Status Dashboard, for example to integrate it into your monitoring system, at the bottom, click JSON History.
Learn more
More information about the Status dashboard can be found on the Merchant Center Help Center.

To investigate the most common errors regarding the Content API for Shopping, check this page on our Developers site. For other errors or for general Content API support, visit the forum.
Ian Ballantyne, Content API for Shopping Team

Ads API apps must complete OAuth verification

Last year, the OAuth scopes used by the following Ads APIs were classified as sensitive, requiring developers to complete the OAuth verification process for their Google Cloud projects:
  • Google Ads API & AdWords API
    • https://www.googleapis.com/auth/adwords
  • Content API for Shopping
    • https://www.googleapis.com/auth/content
  • DoubleClick Bid Manager API
    • https://www.googleapis.com/auth/doubleclickbidmanager
Any remaining OAuth clients using the above scopes that remain unverified may have their existing credentials revoked and lose access to the above APIs if they do not complete the OAuth verification process as soon as possible.

Certain apps may qualify for one of the exceptions for app verification. If your application meets any one of those exceptions, follow the steps listed for the appropriate use case. If not, you must complete OAuth verification to continue using these Ads APIs.

If you have any questions or need additional help, contact us using any of the following support options: Adam Ohren, Google Ads API Team

Reminder of upcoming Content API for Shopping v2.0 sunset date

In March of this year, we announced that beginning September 30, 2021, we will end support for the legacy v2.0 of the Content API for Shopping. We also recommended you migrate to using v2.1, which has been available since March 2019.

As of this announcement, there is now less than 1 month until support for v2.0 will end on September 30, 2021. Following this date, the legacy v2.0 of the Content API is no longer guaranteed to function. We will continue to provide support for your efforts to migrate to v2.1. To avoid disruption we strongly encourage you to migrate to v2.1 imminently.

What do I need to know?
To check your usage of Content API for Shopping, you can look it up: If your application uses a multi-client account (MCA) to make changes to sub-accounts, you should also check your API usage for that account. Please note that all API usage from Content API for Shopping v2.0, is no longer guaranteed to function after September 30, 2021.

Where do I get support?
We have a comprehensive migration guide to help you migrate your implementation including all the changes and new features available in v2.1.

For support migrating the Inventory.set method, see the release of partial product updates.

For support for Google Apps Script & Google Ads scripts, see the update of the default runtime to v2.1.

If you have any questions or issues during migration, contact your Google representative for Merchant Center programs, or ask questions in the Content API for Shopping forum.
Ian Ballantyne, Content API for Shopping Team

Google Apps Script & Google Ads scripts now support Content API v2.1 by default

Going forward, if you use Content API for Shopping through Google Apps Script or Google Ads scripts, new scripts will use Content API v2.1 by default. This change is part of the deprecation of Content API for Shopping v2, scheduled for sunset on September 30th, 2021, after which scripts that depend on v2 features won’t work.

If you currently have a Google Apps script or Google Ads script that uses Content API for Shopping v2, then we strongly recommend you migrate to v2.1. Please note that some methods and fields in v2 are no longer supported in v2.1 (for example Inventory.set), so check the availability of methods and fields you use when you migrate. See the migration guide for more detail.

If you need help implementing this change, please visit the Content API for Shopping forum.
Ian Ballantyne, Content API for Shopping Team

Phone Verification in Content API for Shopping

We are pleased to announce a new Content API interface developers can use to verify phone numbers for Merchant Center accounts. Phone verification is an important step in providing contact information for an account and can also help address account status issues such as PENDING_PHONE_VERIFICATION, which in some cases can enable the option for an account re-review. Prior to this release, this was only possible in the Merchant Center user interface.

Two new methods are provided in the 2-step verification process: Once verified, the phone number will appear in the Accounts.AccountBusinessInformation. The new methods replace the prior approach of setting a phone number directly. We strongly recommend you use these new methods to verify the phone numbers for all Merchant Center accounts to avoid future issues. See the Phone Verification guide for examples and more detail.

If you require further support implementing this change, please visit the Content API for Shopping forum.
Ian Ballantyne, Content API for Shopping Team

Performance reporting now available in the Content API for Shopping

We're excited to announce that performance reporting is now available in v2.1 of the Content API for Shopping. With the search method of the Reports service, you can programmatically retrieve all of the performance data that's available in the Merchant Center.

Requests to the Reports service use the new Merchant Center Query Language, which gives you control over which metrics to download, how to segment/group your data, and which criteria to apply for selecting the result set. If you also use the reporting features of the Google Ads API, you’ll find that many of these concepts are familiar.

For example, the following query will result in a report of impressions, clicks, and clickthrough rate (CTR) over the last 30 days, summarized by date, brand, and offer ID. 

SELECT
  segments.date,
  segments.brand,
  segments.offer_id,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr
FROM MerchantPerformanceView
WHERE segments.date DURING LAST_30_DAYS
  AND segments.category_l2 IN ('Clothing', 'Shoes')

For more details, check out the Reporting guides, which include an overview, a quick example to get you started, and an explanation of key concepts, including how to compose queries in the Merchant Center Query Language.

If you have any questions or need help with the new reporting service, please contact us through the Content API for Shopping forum.

Josh Radcliff, Content API for Shopping Team