Migrating from Content API v2 to v2.1

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:

GET https://shoppingcontent.googleapis.com/content/v2/merchantId/products/productId

For v2.1, update the URL to:

GET https://shoppingcontent.googleapis.com/content/v2.1/merchantId/products/productId

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

The v2 inventory service has been removed and replaced by two new features in v2.1:

2. Update calls to the accounts service

  • Calls to the accounts.update method in v2.1 completely overwrite the accounts resource, instead of only updating the fields included in the request. To avoid deleting fields on the accounts resource, update your call requests to include all fields.

  • The reviewsUrl has been removed.

  • The link status inactive has been removed for adsLinks, googleMyBusinessLink, and youtubeChannelLinks.

3. Update calls to the products service

  • 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 productTypes has replaced both productType and additionalProductTypes.

  • The repeated fields includedDestinations and excludedDestinations have replaced the repeated field destinations.

  • The following AdWords-related fields have been renamed:

    • adwordsGrouping -> adsGrouping
    • adwordsLabels -> adsLabels
    • adwordsRedirect -> adsRedirect

  • The following fields have been removed:

    • aspects
    • destinations
    • onlineOnly
    • validatedDestinations
    • warnings

  • The includeInvalidInsertedItems parameter has been removed.

  • There is now a delay of a few minutes before an inserted product can be retrieved via products.get or products.list.

  • The returned offerId is no longer guaranteed to be the same as the input offerId. v2.1 trims leading and trailing whitespace in the offerId and merges multiple whitespace characters into one. This change does not impact offerId values that conform to the recommended offerId syntax.

  • Prices are now validated before product insertion. Only the following characters are allowed in the value string: +, -, ., and digits (i.e., 0-9). Commas are no longer accepted.

  • Responses from a products.insert call now only contain the following attributes:

    • channel
    • contentLanguage
    • id
    • offerId
    • targetCountry

4. Update calls to the productstatuses service

  • The product attribute has been removed, along with the includeAttributes parameter. To retrieve attributes of the product corresponding to a status, use the products service and pass the value of the new productId field.

  • The includeInvalidInsertedItems parameter has been removed. The productId of every product is now returned regardless of whether the product is valid.

  • The intention, approvalStatus, and approvalPending fields in destinationStatuses have been replaced by status, which is a string that can be one of approved, disapproved, or pending.

  • dataQualityIssues has been replaced by itemLevelIssues.

5. Update calls to the datafeeds service

  • The following target fields have been replaced:

    • contentLanguage -> language
    • targetCountry -> country
    • intendedDestinations -> includedDestinations, and excludedDestinations

  • Data feeds with contentType = "product inventory update" have been removed.

6. Update calls to the orders and TestOrders services

  • 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.

  • The InStoreRefundLineItem and ReturnRefundLineItem fields amountPretax and amountTax have been replaced by priceAmount and taxAmount, respectively. priceAmount can be pre-tax or post-tax, depending on the location of the order.

  • The ShipLineItem fields carrier, shipmentId, and trackingId in the request have been moved to shipmentInfos.

  • billingAddress and predefinedBillingAddress are now top-level fields in orders and TestOrder, respectively.

  • customer.explicitMarketingPreference has been replaced by customer.marketingRightsInfo.

  • The netAmount field has been split into netPriceAmount and netTaxAmount.

  • shippingOption has been replaced by lineItems[].shippingDetails.

  • The CancelLineItem fields amount, amountPretax, and amountTax in the request have been removed. The refunded amount is now calculated automatically.

  • CustomBatch has been removed.

  • Refund has been removed. Use refundOrder or refundItem instead.

  • The paymentMethod field has been removed.

  • ReturnLineItem has been removed. Use returnRefundLineItem without providing a refund amount instead.

  • The customer.email, channelType, and lineItem.product.channel fields have been removed.

  • The promotions field has been removed from the TestOrder service and its format changed in Order.

7. Update calls to the orderinvoice service

  • The amountPretax and amountTax fields have been replaced by priceAmount and taxAmount, respectively. The priceAmount field can be pre-tax or post-tax, depending on the location of the order.

  • Removed balances (merchant, customer, Google) in invoiceSummary and 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.

  • The dryRun parameter has been removed. This change applies to all API calls.

  • All HTTP BATCH methods have been removed. Use customBatch instead.

  • The patch method has been removed from the following services:

    • accounts
    • accounttax
    • datafeeds
    • liasettings
    • shippingsettings

  • The orderpayments service 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:

  • New services:

    • The new localinventory service allows you to make local product updates (in place of the inventory service in v2).

    • The new orderreturns service makes it easier to manage Buy on Google (formerly known as Shopping Actions) by allowing to to process returns without having to use the orders service.

  • Supplemental Feeds allow you to make partial product updates.

  • Additional changes to the products service:

    • products.insert requests 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 itemLevelIssues by the productstatus service:

      • ageGroup
      • availability
      • condition
      • energyEfficiencyClass
      • gender
      • maxEnergyEfficiencyClass
      • minEnergyEfficiencyClass
      • sizeSystem
      • sizeType

    • Custom attributes are now recursive, which removes the need for custom groups.

    • Custom attributes now have a groupValues field in addition to the original value field. Exactly one of the fields must be set.