This document provides guidelines for best practices. See [Performance tips](https://developers.google.com/shopping-content/guides/how-tos/performance) 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](https://support.google.com/merchants/answer/188487). ## 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`](https://developers.google.com/shopping-content/reference/rest/v2.1/products/get) or [`products.list`](https://developers.google.com/shopping-content/reference/rest/v2.1/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](https://developers.google.com/shopping-content/reference/rest/v2.1/accounts)) and/or account-level tax and shipping settings ([Accounttax Service](https://developers.google.com/shopping-content/reference/rest/v2.1/accounttax) and [Shippingsettings Service](https://developers.google.com/shopping-content/reference/rest/v2.1/shippingsettings)). 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](https://developers.google.com/shopping-content/reference/rest/v2.1/products) 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. > [!NOTE] > **Note:** These rules mean that if the data feed is the last to update the product, deleting the product from the feed will delete it from your Merchant Center account. If the [products > service](https://developers.google.com/shopping-content/reference/rest/v2.1/products) is the last to update the product, then deleting the product from your data feed will not remove the product from the Merchant Center. This is why we strongly suggest you pick only one method for inserting and updating products. ### 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`](https://developers.google.com/shopping-content/reference/rest/v2.1/products#Product.FIELDS.shipping) field on the `products` resource. An example of how to modify the Content API primary feed settings is below. ![](https://developers.google.com/static/shopping-content/images/Add_Additional_Countries.png) For more information, see: [Targeting Shopping ads and free listings in multiple countries](https://developers.google.com/shopping-content/guides/targeting-ads-in-multiple-countries). > [!NOTE] > **Note:** If you want to advertise the product in a different country with a **different language** , you need to resubmit the product with a new `feedLabel` and new `contentLanguage`. You also need to update other fields such as `description` and `title` to match the new language. ### 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](https://developers.google.com/shopping-content/guides/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](https://support.google.com/merchants/topic/6324338). ### 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](https://developers.google.com/shopping-content/guides/how-tos/common-errors#conflict). ### 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](https://developers.google.com/shopping-content/guides/products/supplemental-feeds) 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](https://support.google.com/merchants/answer/3246284). 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.