In March 2019, we released version 2.1 of the Content API for Shopping, and in July 2020, we announced that v2 will be sunset on March 29, 2021. On this date, all requests made against v2 of the Content API will fail. This guide explains how to update your application for compatibility with v2.1. We recommend migrating as soon as possible to ensure that your application is unaffected.
Migrating your application
Migrating from v2 to v2.1 involves updating your endpoint URLs to call the new v2.1 versions and modifying your applications to account for breaking changes introduced in v2.1.
Updating your API calls to use v2.1 endpoints
To make calls to v2.1, update your requests to use the new v2.1 endpoints.
For example, to call the
products.get method with v2, you would use:
For v2.1, update the URL to:
For complete information on v2.1 services and endpoints, see the API Reference.
Making required changes
In addition to updating the URLs for your API calls, you also need to update your application to account for several breaking changes introduced in v2.1. Review the following sections and update your application, as needed.
1. Update integrations with the
inventory service has been removed
and replaced by two new features in v2.1:
- Use new Supplemental Feeds for partial product updates.
- Use the new
localinventoryservice for local product updates.
2. Update calls to the
Calls to the
accounts.updatemethod in v2.1 completely overwrite the
accountsresource, instead of only updating the fields included in the request. To avoid deleting fields on the
accountsresource, update your call requests to include all fields.
reviewsUrlhas been removed.
The link status
inactivehas been removed for
3. Update calls to the
Custom attributes no longer contain a type and unit. Instead, units are to be appended to the value and types should be automatically detected.
The repeated field
productTypeshas replaced both
The repeated fields
excludedDestinationshave replaced the repeated field
The following AdWords-related fields have been renamed:
The following fields have been removed:
includeInvalidInsertedItemsparameter has been removed.
There is now a delay of a few minutes before an inserted product can be retrieved via
offerIdis no longer guaranteed to be the same as the input
offerId. v2.1 trims leading and trailing whitespace in the
offerIdand merges multiple whitespace characters into one. This change does not impact
offerIdvalues that conform to the recommended
Prices are now validated before product insertion. Only the following characters are allowed in the value string:
., and digits (i.e.,
9). Commas are no longer accepted.
Responses from a
products.insertcall now only contain the following attributes:
4. Update calls to the
productattribute has been removed, along with the
includeAttributesparameter. To retrieve attributes of the product corresponding to a status, use the
productsservice and pass the value of the new
includeInvalidInsertedItemsparameter has been removed. The
productIdof every product is now returned regardless of whether the product is valid.
destinationStatuseshave been replaced by
status, which is a string that can be one of
dataQualityIssueshas been replaced by
5. Update calls to the
The following target fields have been replaced:
Data feeds with
contentType = "product inventory update"have been removed.
6. Update calls to the
In v2.1, calls should not not include tax data because tax data is calculated automatically. If the order is fulfilled in a state with a Marketplace Fairness Act (MFA) or similar, calls that include tax data fail. If the order is fulfilled in a non-MFA state, tax is calculated based on settings configured in Merchant Center. If not configured, the calculated tax is 0.
amountTaxhave been replaced by
priceAmountcan be pre-tax or post-tax, depending on the location of the order.
trackingIdin the request have been moved to
predefinedBillingAddressare now top-level fields in
customer.explicitMarketingPreferencehas been replaced by
netAmountfield has been split into
shippingOptionhas been replaced by
amountTaxin the request have been removed. The refunded amount is now calculated automatically.
CustomBatchhas been removed.
Refundhas been removed. Use
paymentMethodfield has been removed.
ReturnLineItemhas been removed. Use
returnRefundLineItemwithout providing a refund amount instead.
lineItem.product.channelfields have been removed.
promotionsfield has been removed from the
TestOrderservice and its format changed in
7. Update calls to the
amountTaxfields have been replaced by
taxAmount, respectively. The
priceAmountfield can be pre-tax or post-tax, depending on the location of the order.
Removed balances (merchant, customer, Google) in
invoiceSummaryand promotion charge related fields.
8. Remove functionality not included in v2.1
Several other features have been removed from the Content API in v2.1. Review the following list and update your application, as needed:
XML is no longer supported. For more information on switching to JSON, see Sunset of XML support in the Content API for Shopping.
dryRunparameter has been removed. This change applies to all API calls.
HTTP BATCHmethods have been removed. Use
patchmethod has been removed from the following services:
orderpaymentsservice has been removed.
Testing your migration
For more information on testing the changes to your applications after migrating to v2.1, see Testing Uses of the Content API for Shopping. If you encounter issues while testing your updates, you can post your issue on the Content API forum.
Additional changes in v2.1
In addition changes that require updates, v2.1 also introduces several new features and non-breaking changes:
Supplemental Feeds allow you to make partial product updates.
Additional changes to the
products.insertrequests no longer report non-fatal warnings or errors. This allows you to insert products and make subsequent updates to resolve issues via feed rules in Merchant Center, just as you would with feeds managed outside the Content API.
Invalid values for the following attributes no longer trigger insertion errors, and returned as part of
Custom attributes are now recursive, which removes the need for custom groups.
Custom attributes now have a
groupValuesfield in addition to the original
valuefield. Exactly one of the fields must be set.