Migrating from v2 to v2.1

Behavior changes

Accounts service

  • You can now delete businessInformation and googleMyBusinessLink in an update request without having to provide an empty body ({}).

  • The following AdWords-related fields have been renamed:

    • adwordsLinks -> adsLinks
    • adwordsLinks.adwordsId -> adsLinks.adsId

Order and TestOrder resources

  • Merchants should not provide tax data in their API calls since they're automatically calculated. Doing so will result in a failed call if the order is fulfilled to a state with Marketplace Fairness Act (or similar) legislation. For merchants operating in non-MFA states, calculated tax is dependent on settings in the Merchant Center; if not set up, calculated tax will be 0.

Products service

  • Response from an insert will contain only the following attributes:

    • channel
    • contentLanguage
    • id
    • offerId
    • targetCountry
  • Non-fatal warnings and errors are no longer returned in the response.

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

  • The returned offer ID is no longer guaranteed to be the same as the input offer ID.

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

Product resource

  • Invalid values for the following attributes no longer trigger insertion error, but rather are returned as part of itemLevelIssues in productstatus.

    • ageGroup
    • availability
    • condition
    • energyEfficiencyClass
    • gender
    • maxEnergyEfficiencyClass
    • minEnergyEfficiencyClass
    • sizeSystem
    • sizeType
  • Custom attributes are now recursive, removing the need for custom groups.

  • Custom attributes now have a groupValues field in addition to the original value field; exactly one must be set.

  • 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


  • XML is no longer supported. Check out the related blog post for more details and suggestions on how to switch to JSON.

  • The parameter dryRun has been removed from v2.1. This applies to all API calls.

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

  • The patch() method has been removed from

    • Accounts
    • Accounttax
    • Datafeeds
    • Liasettings
    • Shippingsettings


  • The deprecated field reviewsUrl has been removed.

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


  • The fields contentLanguage, targetCountry, and intendedDestinations have been removed and replaced by language, country, includedDestinations, and excludedDestinations in targets.

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


  • Local inventory services are not yet available in v2.1. New services supporting local inventory cases will be added soon. If you're currently using the Inventory API for local products and decide to migrate to v2.1 before the new services are available, you can continue using the v2 Inventory API at the same time as other v2.1 services.

  • Online inventory data can be updated by using the Supplemental Feeds API functionality.

Order and TestOrder

  • CancelLineItem

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

  • InStoreRefundLineItem and ReturnRefundLineItem

    • The fields amountPretax and amountTax have been replaced by priceAmount and taxAmount, respectively. The field priceAmount may be pre-tax or post-tax depending on the location of the order.
  • Refund has been removed. Use returnRefundLineItem instead.

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

  • ShipLineItem

    • The fields carrier, shipmentId, and trackingId in the request have been moved to shipmentInfos.
  • The field paymentMethod has been removed, and billingAddress and predefinedBillingAddress are now top-level fields in Order and TestOrder, respectively.

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

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

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

  • The netAmount field was split into netPriceAmount and netTaxAmount.

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


  • Removed balances (merchant, customer, Google) in invoiceSummary and promotion charge related fields.

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


  • This service has been removed.


  • The parameter includeInvalidInsertedItems has been removed.

  • The following deprecated fields have been removed:

    • aspects
    • destinations
    • onlineOnly
    • validatedDestinations
    • warnings


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

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

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

  • dataQualityIssues have been replaced by itemLevelIssues.