Release Notes (v2.1)

October 30, 2024

As part of the Settlement-related APIs shutdown, the following services are deprecated: - settlementreports - settlementtranscations

The Settlement-related APIs shutdown is related to the previously shut down BuyOnGoogle program and Orders-related APIs.

Calls to the aforementioned services are expected to fail with a Service was not found on the server response.

October 16, 2024

update_mask in UpdateConversionSourceRequest is now OPTIONAL. If no update mask is specified, all fields that have a non-empty value are updated.

August 26, 2024 (sooner than originally communicated)

As part of the Orders-related APIs shutdown, the following services have been deprecated: - orderinvoices - orderreports - orderreturns - orderreturns.labels - orders

Calls to the aforementioned services are expected to fail with a Service was not found on the server response.

The OrderTrackingSignals service is not deprecated and continues to be available.

August 10, 2024

Buy on Google services

As part of Buy on Google APIs shutdown all the methods within BuyOnGoogleProgramService will fail with service was not found on the server.

July 19, 2024

Products Service

Added the member_price_effective_date field. This update lets you specify, if applicable, the date range during which the loyalty member price is effective. If the field value isn't provided, the member price is always effective.

May 20, 2024

Products Service

Added LoyaltyPrograms. This update lets you provide multiple tiers with different loyalty points, prices, etc. for a single product. You should use this field in place of the singular LoyaltyProgram field.

Reports Service

Deprecated Buy on Google metrics in the MerchantPerformanceView table. After this update, retrieving any Buy on Google metric returns 0. This also applies to historical values for past dates.

For more information, see Buy on Google deprecation.

May 13, 2024

Products Service

Product Resource

Changes to certifications field: Added certificationValue to the ProductCertification field to provide certification value (also known as class, level, or grade), which lets users upload certification information even if the certification authority doesn't issue certification code or number.

For more information, see our Products guides.

May 6, 2024

Reports Service

Added effectiveness bucket to the PriceInsightsProductView table. Effectiveness indicates which products would benefit most from price changes. This rating takes into consideration the performance boost predicted by adjusting the sale price and the difference between your current price and the suggested price.

April 24, 2024

Products Service

Product Resource

Added optional downpayment and creditType fields for Installment payments:

  • downpayment provides the amount the buyer has to pay upfront as a one-time payment.
  • creditType provides the type of installment payment (finance or lease). This field is only applicable to Vehicle Ads.

April 11, 2024

Products Service

Product Resource

  • Added free shipping threshold attribute (FreeShippingThreshold) for offer-level shipping. This attribute lets merchants input a minimum product price for the shipping cost to become free.
  • Changed the visibility of LoyaltyPoints

April 10, 2024

Products Service

Product Resource

Added LoyaltyProgram

April 9, 2024

Products Service

Product Resource

Added structuredTitle and structuredDescription to provide AI-generated product titles and descriptions.

April 3, 2024

Merchant Support Service

Added user_input_action_option field that lets partners request a new type of action: BuiltInUserInputAction. This action lets partners build complex self-serve functionality for merchants, directly in their application instead of redirecting them to the Merchant Center.

Added a new TriggerAction method for BuiltInUserInputAction. To access this method, submit a request to this form.

March 27, 2024

Products Service

Product Resource

Added AutoPricingMinPrice as a safeguard in the "Automated Discounts" and "Dynamic Promotions" projects, ensuring that discounts on merchants' offers don't reduce the product price to lower than this value. Thereby, preserving the offer's value and profitability.

March 15, 2024

Sunset Buy on Google for Search and Shopping. You can continue to view existing orders until October 31, 2024 using orders.list and orders.get.

March 08, 2024

Reports Service

Added TopicTrendsView report to the Reports service.

For more information, see our Reporting guides.

March 6, 2024

Reports service

Added click potential bucket and rank for products.

For more information, see our Reporting guides.

February 19, 2024

ConversionSources Service

Removed the following values as valid conversion sources:

  • CROSS_CHANNEL_FIRST_CLICK
  • CROSS_CHANNEL_LINEAR
  • CROSS_CHANNEL_POSITION_BASED
  • CROSS_CHANNEL_TIME_DECAY

Removed the options of 60 and 90 as lookback window days and added 40 as a valid option.

January 17, 2024

POS service

Added new values for the matching_status_hint field in PosStore, which lets users to have more details about why their store matching has failed.

January 11, 2024

Accounts service

Added localProductManager and localProductManagement as link type and service respectively for the link method. These allow for accounts to link with the purpose of managing local product data.

November 29, 2023

Merchant Support Service

Added VERIFY_IDENTITY_IN_MERCHANT_CENTER external action type for identity verification that needs to be performed in the Merchant Center.

POS service

Added matching_status and matching_status_hint fields to PosStore which lets users to know matching status of Pos Store with Google Business Profile Store and hint to fix in case of an issue.

Nov 15, 2023

repricingrules and repricingrules.repricingreports endpoints are no longer supported.

Nov 1, 2023

Shipping Settings service

The shipment_type=pickup is no longer supported.

October 18, 2023

Accounts service

Added Business Identity field that allows merchants to self-identify to certain consumer values.

October 10, 2023

Added Collection Point as a new shipment type of shipping settings service. A collection point delivery is a service provided by a third party (e.g. not merchant owned) to deliver the item to a third party affiliated location (like UPS Access Points), instead of delivering directly to the home.

September 18, 2023

LIA settings service

Added setOmnichannelExperience method to allow users to set their omnichannel experience (that is, local storefront and pick-up settings). By this time, this is only available for users whose POS provider is trusted to enable such settings.

September 7, 2023

Buy on Google deprecation

Adding a new DEPRECATED status into the GetBuyOnGoogleProgramStastus method. Reactivating or pausing the program from such a state is not possible.

September 4, 2023

Merchant Support Service

Added FIX_ACCOUNT_ISSUE built-in action for product issues that needs to be resolved on the account level. Added SHOW_ADDITIONAL_CONTENT built-in action that will be used to deliver a justification from a national authority.

August 28, 2023

Promotions service

Open list method in Promotions service from limited access to all.

August 22, 2023

Merchant Support Service

Launched Merchant Support Service. This service provides a support content for account issues and product issues.

August 4, 2023

Reports Service

Added Close Competitors Competitive Visibility report to Reports service.

For more information, see our Reporting guides.

July 25, 2023

POS Service

Inventory Resource

Add pickup_method and pickup_sla fields to provide an ability for merchants to submit pickup information along with their inventory.

July 14, 2023

Reports Service

Added Competitive Visibility reports to Reports service.

For more information, see our Reporting guides.

July 7, 2023

Products Service

Product Resource

Added virtualModelLink to provide URLs to 3D model image.

July 4, 2023

Products Service

Product Resource

Add certifications field to provide product certifications, for example for energy efficiency labeling of products based on the EU EPREL database.

June 26, 2023

Shipping Settings service

Local Fulfillment

Added no_delivery_post_cutoff field to allow merchants to opt-out of showing n+1 day local delivery when they have a shipping service configured to n day local delivery.

May 29, 2023

Promotions service

Added list method for the Promotions service.

Recommendation service

Enable interaction dismiss in the ReportInteraction method of the Recommendations service.

May 9, 2023

Cloud Retail Destination

Cloud Retail Additional Properties

Add the cloud retail additional properties field. This is a repeated field intended to be used by customers using the Cloud Retail destination. When this field is used it will be available when using the cloud retail program. This will be mapped to the attributes field in the Google Cloud Retail product model.

May 22, 2023

Promotions service

Added list method for the Promotions service.

April 11, 2023

Shipping Settings service

Local Fulfillment

Added the local delivery fulfillment option for merchants creating a new shipping setting. They can configure their settings for local stores in the new storeConfig field. This includes the service radius, cutoff time, and store codes for the stores offering local delivery.

April 3

Recommendations Service

Launched Recommendations Service. This service provides suggested ways to improve the performance of your merchant account and lets you report merchant clicks on helpful recommendations.

Feb 20, 2023

Accounts Service

Account Resource

Added a new section Account.ConversionSettings in the Accounts resource.

ConversionSources Service

Added the Conversion Sources service, which supports managing conversion sources (part of the Conversion Settings section in Merchant Center).

Feb 16, 2023

Shipping Settings service

Store code validation

Store codes are now validated to ensure that they belong to the merchant before shipping settings are updated.

LIA merchant validation

Programs a Merchant ID is enrolled in are now validated before shipping settings are updated. Merchants must be in one of the following programs:

  • LOCAL_INVENTORY_ON_SURFACES_ACROSS_GOOGLE
  • LOCAL_INVENTORY_ADS

Feb 9, 2023

Promotions Service

Expand Promotions service to 6 additional targetCountry options with local contentLanguage support.:

  • BR
  • ES
  • NL
  • JP
  • IT
  • KR

Jan 12, 2023

Products Service

Product Resource

Added lifestyleImageLinks to provide URLs to lifestyle images.

Nov 24, 2022

Promotion Service

Added a new field `promotionStatus' in the Promotions.PromotionStatus section. This is a read only field.

Nov 15, 2022

Reports Service

Added Market Insights reports to Reports service.

You can now query Reports service for the following:

For more information, see our Reporting guides.

Nov 7, 2022

Datafeeds Service

Added feedLabel support for Datafeeds service.

Sept 14, 2022

Updated feedLabel to accept any string.

Aug 9, 2022

Added feedLabel for products.

You can now use feedLabel instead of targetCountry to specify the country for offer IDs. Offer IDs are now constructed as online:language:feedLabel:offerId.

feedLabel has been automatically populated with your targetCountry value for existing feeds for backwards compatibility.

Deprecated targetCountry.

To support global offers, the Content API for Shopping has deprecated the targetCountry field. Instead, we recommend using the shipping field to specify your target countries.

targetCountry is now automatically populated with the value you provide in feedLabel.

See the blog post Feed label replaces target country in Content API for Shopping for more details.

Dec 8, 2021

Accounts Service

Account Resource

Added a new section Account.AutomaticImprovements in the Accounts resource.

This new section will allow merchants to automatically update items, improve images and shipping settings.

Oct 25, 2021

Promotion Service

Adding Get Promotion to the Promotion API.

Oct 11, 2021

Shipping Settings API

Added new warehouse field in ShippingSettings resource to allow merchants to manage the warehouses which can be used in WarehouseBasedDeliveryTime.

Add new warehouseName field in WarehouseBasedDeliveryTime to refer to warehouse by warehouse name.

Oct 4, 2021

Accounts Service

Account Resource

Added a new field 'phone_verification_status' in the Accounts.BusinessInformation section. This is a read-only field, set by Accounts.VerifyPhoneNumber.

Sept 13, 2021

BuyOnGooglePrograms service

BuyOnGoogleProgramStatus resource

Added new fields in the BuyOnGooglePrograms.BuyOnProgramStatus resource respresnting: online sales channels, business models and customer service phone.

New UpdateBuyOnGoogleProgramStatus method

Added a new UpdateBuyOnGoogleProgramStatus method which will allow to update extended BuyOnGooglePrograms.BuyOnProgramStatus resource.

Sept 6, 2021

Accounts Service

Account Resource

Added a new field 'korean_business_registration_number' in the Accounts.BusinessInformation section. This field will only be cleared if explicitly set to an empty string.

Aug 30, 2021

Promotion Service

Added a new Promotion Service with Insert Promotion available.

Orders Service

Added a new method orders/captureOrder to capture funds before shipment.

New order cancellation reason FAILED_TO_CAPTURE_FUNDS

Products Service

Product Resource

Added productLength, productHeight, productWidth and productWeight to provide product dimensions and weight.

Aug 9, 2021

RepricingRule Service

RepricingRule Type

New enum value for RepricingRuleType field.

Added TYPE_SALES_VOLUME_BASED and TYPE_COMPETITIVE_PRICE.

May 17, 2021

Order Returns Label Service

Added a new 'product_id' field in the CreateReturnRequest. Merchants can specify either the product_id or line_item_id to identify the item to return.

Products Service

Added a new method to update existing products. You can update a product by only providing the fields that need to be updated instead of the whole product.

May 3, 2021

Order Returns Label Service

Added new methods to upload labels for Merchant Managed Returns (MMR). With the new orderreturns.labels.create, you can upload the return labels, to share them with the customer.

April 26, 2021

Shipping Settings API

New warehouseBasedDeliveryTimes field in DeliveryTime to support shipping services calculating the estimated delivery date based on the warehouse location and the chosen carrier service.

New eddServices field in CarriersCarrier object to return names of the services applicable for calculating the estimated delivery date.

April 12, 2021

Products Service

Product Resource

New additionalSizeType field to support up to 2 size types per product.

Changes to shipping field: Added minHandlingTime, maxHandlingTime, minTransitTime and maxTransitTime to ProductShipping to provide offer level shipping speed.

January 28, 2021

Accounts Service

Added automatic labels support to AccountLabel and Account resources. For more information, see CSS Label types section in the CSS Label management guide.

October 5, 2020

CSSES Service

CSS Resource

Added a new csses service for retrieving information about CSS domains and assigning labels to them. The AccountLabel resource can now also be used for creating and listing CSS group level labels. For more information, see CSS Label Management.

August 24, 2020

Products Service

Products Resource

New shoppingAdsExcludedCountries field to exclude offers from advertising in certain countries.

Productstatuses Resource

New approvedCountries, pendingCountries and disapprovedCountries fields in destinationStatuses object which provide for offer status information beyond targetCountry.

New itemLevelIssues.applicableCountries field.

August 10, 2020

Accounts Service

Added a new AccountLabel resource for managing Merchant Center account labels for CSS Center. CSS Center users can now also list their Merchant Center accounts and assign labels to them with accounts.list, accounts.get and accounts.updatelabels methods. For more information, see CSS Label Management.

June 19, 2020

Products Service

Product Resource

New fields

New productDetails, productHighlights, subscriptionCost, and canonicalLink fields.

June 2, 2020

Orders Service

Added new methods to initiate refunds without returns. With the new orders.refunditem and orders.refundorder, you can initiate refunds on orders even if they are not returned by the customer.

April 27, 2020

Orderreturns Service

Added new methods acknowledge and process, and new filters and fields for read methods (list, get).

GMB linking

Added the ability to link Merchant Center accounts to a GMB account using the GMB account ID.

April 14, 2020

Settlement Report APIs

Added a new service for getting settlement reports.

March 9, 2020

Local inventory API

Added a new service for submitting local inventory data.

March 2, 2020

Pubsub notification settings API

Added a new service for managing settings for pubsub notifications.

December 3, 2019

Products Service

Added support for multi-client account supplemental Content API feeds.

September 11, 2019

Orders Service

Added support for pickup shipments in orders and corresponding sandbox features.

August 14, 2019

New services

Added new Returnpolicy and Returnaddress services for Buy on Google.

Orders Service

Order Resource

New field

New quantityUndeliverable field.

August 7, 2019

Orders Service

Order Resource

New fields

Added new loyaltyInfo and invoiceReceivingEmail fields to Order resource.

July 1, 2019

Products Service

Support for supplemental Content API feeds added in the Products service.

June 11, 2019

Orders Service

Order and TestOrder Resources

Addition of price adjustment

Added new lineItem[].adjustments field that contains adjustment to original line item price and tax caused by applying promotions.

February 14, 2019

Changes introduced in this version

Dry runs no longer supported

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

Patch methods no longer supported

The following services no longer support the patch method:

  • Accounts
  • Accounttax
  • Datafeeds
  • Liasettings
  • Shippingsettings

Removal of HTTP BATCH methods

All HTTP BATCH methods have been removed from v2.1. Use customBatch instead. The affected services are the following:

  • Accounts
  • Accountstatuses
  • Datafeeds
  • Datafeedstatuses
  • Liasettings
  • Orderreports
  • Pos
  • Products
  • Productstatuses
  • Shippingsettings

Accounts Service

Update

The fields businessInformation and googleMyBusinessLink in the request were introduced after the initial launch of Content API v2. Due to this, there is a safeguard that prevents merchants from unintentionally deleting information in these two fields with update if they are not provided.

In v2, merchants must explicitly provide these fields with an empty body ( {}) to delete them. In v2.1, fields are deleted if you provide an empty body, or if you don't provide them.

Account Resource

AdWords -> Google Ads rebranding

With AdWords becoming Google Ads, the following AdWords-related fields have been renamed:

  1. adwordsLinks -> adsLinks
  2. adwordsLinks.adwordsId -> adsLinks.adsId
Removal of deprecated fields and values

The deprecated field reviewsUrl has been removed. In addition, the link status inactive has been removed for adsLinks, googleMyBusinessLink, and youtubeChannelLinks.

Accountstatuses Service

AccountStatus Resource

Removal of dataQualityIssues

These have been superseded by itemLevelIssues.

Datafeed Service

Datafeed Resource

Removal of deprecated fields

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

Removal of product inventory update

Feeds of type product inventory update have been removed.

Inventory Service

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

Orders Service

CancelLineItem

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

CustomBatch

CustomBatch has been removed from v2.1.

InStoreRefundLineItem

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

This method has been removed. Use returnRefundLineItem instead.

ReturnLineItem

This method has been removed. Use returnRefundLineItem without providing a refund amount instead.

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.

ShipLineItem

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

Order and TestOrder Resources

New promotion format

There is a new promotion format in v2.1. You can't create test orders with promotions.

Removal of deprecated fields

The field paymentMethod has been removed, and billingAddress andpredefinedBillingAddress are now top-level fields in Order and TestOrder, respectively.

Furthermore, customer.explicitMarketingPreference has been removed and replaced by customer.marketingRightsInfo in both Order and TestOrder.

The deprecated field customer.email has been removed.

The format of the promotions field has changed in the Order resource.

Orderpayments Service

This service has been removed from v2.1.

Products Service

Response from an insert will contain only the following attributes:

  • channel
  • contentLanguage
  • id
  • offerId
  • targetCountry

Nonfatal warnings and errors are no longer returned in the response. This allows for better integration with feed rules and other advanced feed management features.

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 (0-9). Commas are no longer accepted.

Product Resource

CustomGroups replaced by recursive customAttributes

Previously, custom attributes could be grouped together by adding custom attributes under the same custom group in v2. Custom attributes are now recursive in v2.1, so this removes the need for custom groups.

Custom attributes now have an additional groupValues field in addition to the original value field; exactly one of them must be set, meaning they cannot be simultaneously set or left out.

As merchants may switch between v2 and v2.1, it is possible for products to have recursive custom attributes which cannot be represented in v2 as custom groups have a maximum of two levels. In this case, the custom attribute group will be truncated.

Removal of type and unit in customAttributes

In v2.1, custom attributes will no longer contain a type and unit. Instead, units are to be appended to the value (if present), and types should be automatically detected. For exammple, use "1.23 EUR" or "5.6 cm" as the value in v2.1.

ProductTypes supersedes productType and additionalProductTypes

Previously, product types were stored in two fields with the first type in the singular field productType and the remaining in the repeated field additionalProductTypes. In v2.1, the two fields have been replaced by a single repeated field productTypes.

Destinations attribute replaced by includedDestinations and excludedDestinations

Destinations were input as a list of destination name and intention pairs in v2 in the repeated field destinations. This field has been replaced by the following two repeated fields: includedDestinations and excludedDestinations. Destinations enabled by default need not be included in includedDestinations. This will match the configuration of destination overrides in feeds.

With AdWords becoming Google Ads, the following AdWords-related fields have been renamed:

  • adwordsGrouping -> adsGrouping
  • adwordsLabels -> adsLabels
  • adwordsRedirect -> adsRedirect
Removal of deprecated fields

The following deprecated fields have been removed:

  • aspects
  • destinations
  • onlineOnly
  • validatedDestinations
  • warnings

Productstatuses Service

Get and List

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.

List

The parameter includeInvalidInsertedItems has been removed. All products are now returned regardless of whether they are valid, meaning list now behaves as if includeInvalidInsertedItems is always set to true.

ProductStatus Resource

DestinationsStatuses

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.

Removal of dataQualityIssues

These have been superseded by itemLevelIssues.