This document provides guidelines for best practices. See also Performance Tips.
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
- Do not use the API as you would use Feeds
- Avoid daily updates of your entire product feed. Instead, specifically update only those items that actually change. Sending your entire data feed consumes more time and resources both for Google and for you.
- Do not 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.
- Do not 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 Datafeeds together?
You can manipulate your datafeeds using the API’s Datafeeds Service. While this will make datafeed 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 Inventory Service (v2 only) to update pricing and inventory throughout the day. This is acceptable because Inventory Service does not alter the product, which keeps it tied to the datafeed that it came from. Keep in mind that this means that your expiration date will not be updated either. This is usually not an issue since merchants tend to update their feeds often enough to prevent product expiration.
- 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 Datafeeds to using only the API or vice versa?
If you currently use Datafeeds 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 datafeed or deleting the data feed itself will no longer remove the product information from your Merchant Center account. Make sure that there are no datafeed updates if you want to remove the product from the datafeed or the datafeed itself, else the datafeed will take ownership again and removing the product from the datafeed will cause the product to be removed.
If you currently use only the API for product information and you want to use Datafeeds as your primary source of product information, then you can simply add the new Datafeeds 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?
With file-based feeds, you can submit feeds to multiple countries by adding targets to the feeds in the Merchant Center. This will not work with the Content API feed that is listed in your feed list. The targets listed for the Content API feed reflect those that you have submitted using the Content API for Shopping, and manually adding targets does not cause either previously submitted or newly submitted products to be duplicated across targets.
Instead, submit the appropriate product data multiple times, changing the
contentLanguagefor each submission to match the desired target.
- Make sure that your client libraries are up to date
If you are using a Google client libraries 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
excludedDestinationsproduct 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, Shopping Actions, but you want to exclude certain products, use the
excludedDestinationsattribute and specify
Shopping Actionsas 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 Shopping Actions. Conversely, if your feed has not been opted into a program, for example, Shopping, you can include individual items, by using the
Shoppingas the value and the item will surface in Shopping ads.
For more information on the
excludedDestinationsproduct 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 via the Content API, a new feed will appear in Merchant Center titled Content API. Make sure that you do not accidentally delete this feed or the 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 service 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.
- Make sure to inform customers of delays or changes in shipping information
You can use
updatelineitemshippingdetailsto update your shipping information and inform customers if there have been partial delays (relating to individual line items) in their orders. This can happen when one or more line items is delayed and the rest of the order is on schedule. To do this, call
updatelineitemshippingdetailsand pass the updated values for the
deliveryByDatefields. Placing this call automatically triggers an email to the customer to let them know about the changes to scheduled delivery times.
- 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.