This document provides guidelines for best practices. See Performance tips for more information.
When to use the API
To send requests programmatically
Whether you prefer to automate every part of your workflow, or create a hook into your ERP (Enterprise Resource Planning) system, the Content API allows you to send updates as soon as your inventory changes.
To receive immediate feedback
In the Content API, you get a response to every request instantly, rather than via an email summary after the data feeds are processed. A five to ten second latency is expected for large batch requests.
To frequently change your product data
With the Content API you can make incremental updates to your fast moving product inventory many times in a day, whereas sending your entire data feed every time is not feasible. If updates become available individually, send them individually, don't wait until there are several updates so you can batch them up. Likewise, if updates are available in batches, send them in batches, do not break them up into individual requests.
To manage several sub-accounts
Newly created Merchant Center accounts are single accounts, holding on to its own set of product data. This works well in most cases, but as your account grows, you may find that you need a more complex management system for your products. If this is the case for you, consider using a multi-client account, or MCA. API-level management of an MCA account can be conducted through the Accounts service, and allows for programmatic adding and managing of sub-accounts. More information about how to obtain an MCA account can be found here.
How to use the API
Don't use the API as you would use data feeds
Avoid daily updates of your entire product feed when using the products resource.
Instead, specifically update only those products whose data has actually
changed. Sending your entire data feed via the products resource consumes more
time and resources for both Google and you.
Don't use the API to regularly retrieve product information you have uploaded
If you are responsible for maintaining the product information in a
particular Merchant Center account, avoid requesting product
information from the Content API via the
products.get
or
products.list
methods on a regular basis. For clients that upload information, these
methods can help you debug issues when designing solutions that
use the Content API. However, they are not meant for regular retrieval of
product information by such clients. You should have another source for
your product information, like a local product database, and the products
in Merchant Center should reflect the contents of that source.
Don't use both data feeds and Content API to submit product items
If you're considering a switch to the API for item submission, make sure that you're not using data feeds anymore to submit product items. If you keep on submitting items on both mediums, unexpected results may occur.
Is there a way I can safely use API and data feeds together?
You can manipulate your data feeds using the API's Datafeed Service. While this will make data feed management at scale much easier, keep in mind that you should not insert or update products using the API concurrently with feeds, as unexpected results could occur.
Some other examples of acceptable ways to use feeds and API jointly include:
Executing read-only requests (get or list) from the API: some merchants want to use the API to fetch information and status updates on their products. This is acceptable because product information only gets updated by feeds.
Using the API to manage your sub-accounts (Accounts Service) and/or account-level tax and shipping settings (Accounttax Service and Shippingsettings Service). These are not functions that Datafeeds can provide, so there is no conflict with using the API to manage these functions.
How do I migrate from using data feeds to using only the API or vice versa?
If you currently use data feeds and you want to switch to only using the API for updating products, then you need to re-upload your product data with the API. When you use the products service to update a given product, the API takes control of the product information, and deleting the product from the data feed or deleting the data feed itself will no longer remove the product information from your Merchant Center account. Make sure that there are no data feed updates if you want to remove the product from the data feed or the data feed itself, else the data feed will take ownership again and removing the product from the data feed will cause the product to be removed.
If you currently use only the API for product information and you want to use data feeds as your primary source of product information, then you can simply add the new data feed to your Merchant Center account and they will take ownership of their listed products. If there are products you want removed before they expire that were uploaded solely from API, you must delete them either via Merchant Center or via the API.
How do I target multiple countries with products using the Content API for Shopping?
To target multiple countries with ads and free listings for products submitted
via the Content API, configure additional countries on the Content API primary
feed in Merchant Center or add those additional countries via the shipping
field on the products resource.
An example of how to modify the Content API primary feed settings is below.
For more information, see: Targeting Shopping ads and free listings in multiple countries.
Make sure that your client libraries are up to date
If you are using a Google client library to interact with the Content API, make sure to use the package manager for your chosen programming language and ensure that library version is up to date. For more information, see the developer's guide for your chosen language in Samples and Libraries.
Make sure to use the destinations attributes to control which products appear in the different shopping programs
The Content API automatically adopts the default settings for your Content
API feed as it was configured in the Merchant Center. You can use the
includedDestinations or excludedDestinations product attributes to
control program participation on a product level within a feed or via the
Content API.
If your API feed has been opted into a program, for example, Buy on Google
(formerly known as Shopping Actions), but you want to exclude certain products,
use the excludedDestinations attribute and specify Shopping Actions as the
value. Provided that there are no errors, this will overwrite the default
feed settings in the Merchant Center and that particular item will not
surface in Buy on Google (formerly known as Shopping Actions). Conversely, if
your feed has not been opted into a program, for example, Shopping, you can
include individual items, by using the includedDestinations attribute and
Shopping_ads as the value and the item will surface in Shopping ads.
For more information on the includedDestinations and
excludedDestinations product attributes, see the
Help Center.
Make sure to update items before they expire
If an item does not change before it expires, 30 days after the last update or at the specified expiration date if earlier, update the item to avoid its deactivation. If you need to update many items, because none of them have changed or you are not able to track when they were last updated, do not update all items at the same time, but rather spread the load evenly over multiple days.
Don't delete the Content API feed or your products may disappear
The first time that you upload a product with channel:online via the Content
API, a new feed will appear in Merchant Center titled Content API. The first
time that you upload a product with channel:local via the Content API, a new
feed will appear in Merchant Center titled Content API with a subheading of
Local Products. Make sure that you do not accidentally delete the online or
the local Content API feed. Depending on the feed you delete, the online
or local products that you have added to Merchant Center via the Content API
will be removed.
Batch multiple requests to the same service using the custombatch method
Instead of making many sequential or parallel requests to the same service, make a single custombatch request that contains all the desired requests. This way, the latency for making requests to the API endpoint only happens once for the custombatch call instead of on each individual request, which is especially important if you are making sequential requests.
Don't send multiple updates to a single item in a single batch
This will give unexpected results due to uncertainty as to the sequence of updates and may cause a conflict error.
Don't send updates for unchanged items
Make sure you only send requests for new, changed, or deleted product items unless the items will expire otherwise.
Use Supplemental Feeds if prices and/or availability change rapidly
If you are having trouble keeping a product's price, availability, or sale
information up-to-date, consider using the
Supplemental Feeds in the products resource
to send updates for just those attributes. Since supplemental feed updates
are small, you can make many more supplemental feed updates in a given
period than full product updates, which will help keep your products' prices
and availability in line with your landing pages.
Another route for updating product price and availability is to use automatic item updates. This can be used in addition to API updates to help avoid mismatches between the information in the Merchant Center and the information on the product landing pages. However, keep in mind that this is designed to fix small problems with product price and availability accuracy, so automatic item updates are not a replacement for also providing the correct information via the API.
When to use a refresh token
The refresh token is returned in the HTTP header of authorization requests. It contains lots of other authentication-related information, but the refresh token is often the piece that developers want to get their hands on, as it removes the need to repeatedly prompt the user for authentication, since access tokens last only 60 minutes before expiring.