Enable automatic improvements

Automatic improvements are a set of features that allow Google to automatically update your products, images, and shipping estimates based on your website's landing page. Enabling these automatic improvements can lead to an improved user experience, more traffic to your products, and higher conversion rates.

You can use the AutomaticImprovements resource within the Accounts sub-API to:

Special considerations

  • Inheritance of settings:
  • Merchant Center UI:
    • shippingImprovements are manageable only through the API, not through the Merchant Center UI.
  • Update behavior:
    • When updating settings for itemUpdates, imageImprovements, or shippingImprovements, the API performs a full replacement of the specified top-level component (e.g., the entire itemUpdates object). Verify that your update request includes all intended sub-fields for the components you intend to modify, as specified by the update_mask.
  • Prerequisites:

Retrieve automatic improvements settings

Retrieve the current automatic improvement settings for your Merchant Center account. This includes settings for item updates (price, availability, condition), image improvements, and shipping improvements. The response shows both the settings configured directly on the account (if any) and the effective settings, which consider inheritance from an advanced account for item and image updates.

GET https://merchantapi.googleapis.com/accounts/v1beta/accounts/<var>ACCOUNT_ID</var>/automaticImprovements

A successful request returns an AutomaticImprovements resource in the response body. The response shows both the settings configured directly on the account and the effective settings. The effective settings are what is applied to the account and may be inherited from a higher-level account (such as a multi-client account) if not explicitly set.

{
  "name": "accounts/12345/automaticImprovements",
  // Example 1: Settings are directly configured on the account.
  "itemUpdates": {
    // When `accountItemUpdatesSettings` is present, `effective` values match the configured ones.
    "accountItemUpdatesSettings": {
      "allowPriceUpdates": true,
      "allowAvailabilityUpdates": true,
      "allowStrictAvailabilityUpdates": false,
      "allowConditionUpdates": true
    },
    "effectiveAllowPriceUpdates": true,
    "effectiveAllowAvailabilityUpdates": true,
    "effectiveAllowStrictAvailabilityUpdates": false,
    "effectiveAllowConditionUpdates": true
  },
  // Example 2: Settings are inherited from a parent account.
  "imageImprovements": {
    // `accountImageImprovementsSettings` is omitted, thus the `effective` value of `true` is inherited.
    "effectiveAllowAutomaticImageImprovements": true
  },
  "shippingImprovements": {
    "accountShippingImprovementsSettings": {
      "allowShippingImprovements": true
    },
    "effectiveAllowShippingImprovements": true
  }
}

This example shows how to retrieve the automatic improvement settings for a Merchant Center account.

Java

import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.accounts.v1beta.AutomaticImprovements;
import com.google.shopping.merchant.accounts.v1beta.AutomaticImprovementsName;
import com.google.shopping.merchant.accounts.v1beta.AutomaticImprovementsServiceClient;
import com.google.shopping.merchant.accounts.v1beta.AutomaticImprovementsServiceSettings;
import com.google.shopping.merchant.accounts.v1beta.GetAutomaticImprovementsRequest;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to get the automatic improvements of a Merchant Center account. */
public class GetAutomaticImprovementsSample {

  public static void getAutomaticImprovements(Config config) throws Exception {

    // Obtains OAuth token based on the user's configuration.
    GoogleCredentials credential = new Authenticator().authenticate();

    // Creates service settings using the credentials retrieved above.
    AutomaticImprovementsServiceSettings automaticImprovementsServiceSettings =
        AutomaticImprovementsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Creates AutomaticImprovements name to identify the AutomaticImprovements.
    String name =
        AutomaticImprovementsName.newBuilder()
            .setAccount(config.getAccountId().toString())
            .build()
            .toString();

    // Calls the API and catches and prints any network failures/errors.
    try (AutomaticImprovementsServiceClient automaticImprovementsServiceClient =
        AutomaticImprovementsServiceClient.create(automaticImprovementsServiceSettings)) {

      // The name has the format: accounts/{account}/automaticImprovements
      GetAutomaticImprovementsRequest request =
          GetAutomaticImprovementsRequest.newBuilder().setName(name).build();

      System.out.println("Sending get AutomaticImprovements request:");
      AutomaticImprovements response =
          automaticImprovementsServiceClient.getAutomaticImprovements(request);

      System.out.println("Retrieved AutomaticImprovements below");
      System.out.println(response);
    } catch (Exception e) {
      System.out.println(e);
    }
  }

  public static void main(String[] args) throws Exception {
    Config config = Config.load();

    getAutomaticImprovements(config);
  }
}
GetAutomaticImprovementsSample.java

PHP

use Google\ApiCore\ApiException;
use Google\Shopping\Merchant\Accounts\V1beta\Client\AutomaticImprovementsServiceClient;
use Google\Shopping\Merchant\Accounts\V1beta\GetAutomaticImprovementsRequest;

/**
 * This class demonstrates how to get the automatic improvements of a Merchant Center account.
 */
class GetAutomaticImprovementsSample
{
    /**
     * Helper function to construct the resource name for AutomaticImprovements.
     *
     * @param string $accountId The Merchant Center account ID.
     * @return string The resource name in the format: accounts/{account}/automaticImprovements
     */
    private static function getAutomaticImprovementsName(string $accountId): string
    {
        return sprintf("accounts/%s/automaticImprovements", $accountId);
    }

    /**
     * Retrieves the automatic improvements settings for a given Merchant Center account.
     *
     * @param array $config The configuration array containing the account ID.
     * @return void
     */
    public static function getAutomaticImprovementsSample(array $config): void
    {
        // Obtains OAuth credentials for authentication.
        $credentials = Authentication::useServiceAccountOrTokenFile();

        // Contructs an options array for the client.
        $options = ['credentials' => $credentials];

        // Creates a new AutomaticImprovementsServiceClient.
        $automaticImprovementsServiceClient = new AutomaticImprovementsServiceClient($options);

        // Constructs the full resource name for the automatic improvements settings.
        $name = self::getAutomaticImprovementsName($config['accountId']);

        // Creates the GetAutomaticImprovementsRequest.
        $request = new GetAutomaticImprovementsRequest(['name' => $name]);

        printf("Sending get AutomaticImprovements request:%s", PHP_EOL);

        try {
            // Makes the API call to retrieve automatic improvements settings.
            $response = $automaticImprovementsServiceClient->getAutomaticImprovements($request);

            printf("Retrieved AutomaticImprovements below%s", PHP_EOL);
            // Prints the response in JSON format for readability.
            print_r($response);
        } catch (ApiException $e) {
            printf("ApiException was thrown: %s%s", $e->getMessage(), PHP_EOL);
        }
    }

    /**
     * Helper to execute the sample.
     *
     * @return void
     */
    public function callSample(): void
    {
        $config = Config::generateConfig();
        self::getAutomaticImprovementsSample($config);
    }
}

// Runs the script.
$sample = new GetAutomaticImprovementsSample();
$sample->callSample();
GetAutomaticImprovementsSample.php

Python

"""Gets the automatic improvements settings for a Merchant Center account."""
from examples.authentication import configuration
from examples.authentication import generate_user_credentials
from google.shopping.merchant_accounts_v1beta import AutomaticImprovementsServiceClient
from google.shopping.merchant_accounts_v1beta import GetAutomaticImprovementsRequest


# Fetches the account ID from the config file.
# This is a placeholder for your actual account ID.
_ACCOUNT_ID = configuration.Configuration().read_merchant_info()
# Construct the resource name for AutomaticImprovements.
# The format is accounts/{account}/automaticImprovements
_NAME = f"accounts/{_ACCOUNT_ID}/automaticImprovements"


def get_automatic_improvements_sample():
  """Gets the automatic improvements settings for a Merchant Center account."""

  # Generates OAuth 2.0 credentials for authentication.
  credentials = generate_user_credentials.main()

  # Creates a client for the AutomaticImprovementsService.
  client = AutomaticImprovementsServiceClient(credentials=credentials)

  # Creates the request to get automatic improvements.
  # The name parameter is the resource name of the automatic improvements
  # settings.
  request = GetAutomaticImprovementsRequest(name=_NAME)

  print("Sending get AutomaticImprovements request:")
  # Makes the API request to get automatic improvements.
  try:
    response = client.get_automatic_improvements(request=request)

    print("Retrieved AutomaticImprovements below")
    print(response)
  except RuntimeError as e:
    print(f"An API error occurred: {e}")


if __name__ == "__main__":
  get_automatic_improvements_sample()

get_automatic_improvements_sample.py

cURL

curl --location 'https://merchantapi.googleapis.com/accounts/v1beta/accounts/YOUR_ACCOUNT_ID/automaticImprovements' \
--header 'Authorization: Bearer <var>API_TOKEN</var>'

Update automatic improvements settings

Modify the automatic improvement settings for your Merchant Center account. Provide the AutomaticImprovements object with the intended state for itemUpdates, imageImprovements, and shippingImprovements. Use the update_mask query parameter to specify which fields you are updating (for example, to update all provided settings, use update_mask=*).

When you update settings, you can either overwrite the existing configuration or clear it to inherit settings from a parent account.

  • To overwrite a setting: Include the top-level field name (for example, itemUpdates or imageImprovements) in the update_mask and provide its new configuration in the request body. This action replaces any existing settings for that field on the sub-account.

  • To clear a setting and inherit from a parent: Include the field name in the update_mask, but omit the field entirely from the request body. This removes the specific configuration from the sub-account, causing it to inherit the setting from its parent. If the parent account also has no setting configured, the system default applies.

The following example demonstrates how to clear the imageImprovements settings for a sub-account, causing it to inherit them from its parent account, while simultaneously updating the itemUpdates settings.

PATCH https://merchantapi.googleapis.com/accounts/v1beta/accounts/{account}/automaticImprovements?update_mask=itemUpdates,imageImprovements

Request body (omitting imageImprovements):

{
  "name": "accounts/12345/automaticImprovements",
  "itemUpdates": {
    "accountItemUpdatesSettings": {
      "allowPriceUpdates": true,
      "allowAvailabilityUpdates": true,
      "allowStrictAvailabilityUpdates": true,
      "allowConditionUpdates": true
    }
  }
}

PATCH https://merchantapi.googleapis.com/accounts/v1beta/accounts/<var>ACCOUNT_ID</var>/automaticImprovements?update_mask=itemUpdates,imageImprovements,shippingImprovements

Request body example (enabling all improvements):

{
  "name": "accounts/<var>ACCOUNT_ID</var>/automaticImprovements",
  "itemUpdates": {
    "accountItemUpdatesSettings": {
      "allowPriceUpdates": true,
      "allowAvailabilityUpdates": true,
      "allowStrictAvailabilityUpdates": true,
      "allowConditionUpdates": true
    }
  },
  "imageImprovements": {
    "accountImageImprovementsSettings": {
      "allowAutomaticImageImprovements": true
    }
  },
  "shippingImprovements": {
      "allowShippingImprovements": true
  }
}

A successful request returns the updated AutomaticImprovements resource in the response body.

{
  "name": "accounts/12345/automaticImprovements",
  "itemUpdates": {
    "accountItemUpdatesSettings": {
      "allowPriceUpdates": true,
      "allowAvailabilityUpdates": true,
      "allowStrictAvailabilityUpdates": true,
      "allowConditionUpdates": true
    },
    "effectiveAllowPriceUpdates": true,
    "effectiveAllowAvailabilityUpdates": true,
    "effectiveAllowStrictAvailabilityUpdates": true,
    "effectiveAllowConditionUpdates": true
  },
  "imageImprovements": {
    "accountImageImprovementsSettings": {
      "allowAutomaticImageImprovements": true
    },
    "effectiveAllowAutomaticImageImprovements": true
  },
  "shippingImprovements": {
      "allowShippingImprovements": true
    "effectiveAllowShippingImprovements": true
  }
}

This example demonstrates how to update the automatic improvements settings, enabling all available automatic improvements for a Merchant Center account. The update_mask is set to *, meaning all fields provided in the automatic_improvements object in the request body are applied. The response shows the updated settings, with both the configured and effective values.

Java

import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.protobuf.FieldMask;
import com.google.shopping.merchant.accounts.v1beta.AutomaticImageImprovements;
import com.google.shopping.merchant.accounts.v1beta.AutomaticImageImprovements.ImageImprovementsAccountLevelSettings;
import com.google.shopping.merchant.accounts.v1beta.AutomaticImprovements;
import com.google.shopping.merchant.accounts.v1beta.AutomaticImprovementsName;
import com.google.shopping.merchant.accounts.v1beta.AutomaticImprovementsServiceClient;
import com.google.shopping.merchant.accounts.v1beta.AutomaticImprovementsServiceSettings;
import com.google.shopping.merchant.accounts.v1beta.AutomaticItemUpdates;
import com.google.shopping.merchant.accounts.v1beta.AutomaticItemUpdates.ItemUpdatesAccountLevelSettings;
import com.google.shopping.merchant.accounts.v1beta.AutomaticShippingImprovements;
import com.google.shopping.merchant.accounts.v1beta.UpdateAutomaticImprovementsRequest;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to update AutomaticImprovements to be enabled. */
public class UpdateAutomaticImprovementsSample {

  public static void updateAutomaticImprovements(Config config) throws Exception {

    GoogleCredentials credential = new Authenticator().authenticate();

    AutomaticImprovementsServiceSettings automaticImprovementsServiceSettings =
        AutomaticImprovementsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Creates AutomaticImprovements name to identify AutomaticImprovements.
    String name =
        AutomaticImprovementsName.newBuilder()
            .setAccount(config.getAccountId().toString())
            .build()
            .toString();

    // Create AutomaticImprovements with the updated fields.
    AutomaticImprovements automaticImprovements =
        AutomaticImprovements.newBuilder()
            .setName(name)
            .setItemUpdates(
                AutomaticItemUpdates.newBuilder()
                    .setAccountItemUpdatesSettings(
                        ItemUpdatesAccountLevelSettings.newBuilder()
                            .setAllowPriceUpdates(true)
                            .setAllowAvailabilityUpdates(true)
                            .setAllowStrictAvailabilityUpdates(true)
                            .setAllowConditionUpdates(true)
                            .build())
                    .build())
            .setImageImprovements(
                AutomaticImageImprovements.newBuilder()
                    .setAccountImageImprovementsSettings(
                        ImageImprovementsAccountLevelSettings.newBuilder()
                            .setAllowAutomaticImageImprovements(true)
                            .build())
                    .build())
            .setShippingImprovements(
                AutomaticShippingImprovements.newBuilder()
                    .setAllowShippingImprovements(true)
                    .build())
            .build();

    FieldMask fieldMask = FieldMask.newBuilder().addPaths("*").build();

    try (AutomaticImprovementsServiceClient automaticImprovementsServiceClient =
        AutomaticImprovementsServiceClient.create(automaticImprovementsServiceSettings)) {

      UpdateAutomaticImprovementsRequest request =
          UpdateAutomaticImprovementsRequest.newBuilder()
              .setAutomaticImprovements(automaticImprovements)
              .setUpdateMask(fieldMask)
              .build();

      System.out.println("Sending Update AutomaticImprovements request");
      AutomaticImprovements response =
          automaticImprovementsServiceClient.updateAutomaticImprovements(request);
      System.out.println("Updated AutomaticImprovements Name below");
      System.out.println(response.getName());
    } catch (Exception e) {
      System.out.println(e);
    }
  }

  public static void main(String[] args) throws Exception {
    Config config = Config.load();

    updateAutomaticImprovements(config);
  }
}
UpdateAutomaticImprovementsSample.java

PHP

use Google\ApiCore\ApiException;
use Google\Protobuf\FieldMask;
use Google\Shopping\Merchant\Accounts\V1beta\AutomaticImageImprovements;
use Google\Shopping\Merchant\Accounts\V1beta\AutomaticImageImprovements\ImageImprovementsAccountLevelSettings;
use Google\Shopping\Merchant\Accounts\V1beta\AutomaticImprovements;
use Google\Shopping\Merchant\Accounts\V1beta\Client\AutomaticImprovementsServiceClient;
use Google\Shopping\Merchant\Accounts\V1beta\AutomaticItemUpdates;
use Google\Shopping\Merchant\Accounts\V1beta\AutomaticItemUpdates\ItemUpdatesAccountLevelSettings;
use Google\Shopping\Merchant\Accounts\V1beta\AutomaticShippingImprovements;
use Google\Shopping\Merchant\Accounts\V1beta\UpdateAutomaticImprovementsRequest;

/**
 * This class demonstrates how to update AutomaticImprovements to be enabled.
 */
class UpdateAutomaticImprovementsSample
{
    /**
     * Helper function to construct the resource name for AutomaticImprovements.
     *
     * @param string $accountId The Merchant Center account ID.
     * @return string The resource name in the format: accounts/{account}/automaticImprovements
     */
    private static function getAutomaticImprovementsName(string $accountId): string
    {
        return sprintf("accounts/%s/automaticImprovements", $accountId);
    }

    /**
     * Updates the automatic improvements settings for a Merchant Center account.
     * This sample enables all automatic improvements.
     *
     * @param array $config The configuration array containing the account ID.
     * @return void
     */
    public static function updateAutomaticImprovementsSample(array $config): void
    {
        // Obtains OAuth credentials for authentication.
        $credentials = Authentication::useServiceAccountOrTokenFile();

        // Contructs an options array for the client.
        $options = ['credentials' => $credentials];

        // Creates a new AutomaticImprovementsServiceClient.
        $automaticImprovementsServiceClient = new AutomaticImprovementsServiceClient($options);

        // Constructs the full resource name for the automatic improvements settings.
        $name = self::getAutomaticImprovementsName($config['accountId']);

        // Prepares the AutomaticImprovements object with all settings enabled.
        $automaticImprovements = new AutomaticImprovements([
            'name' => $name,
            'item_updates' => new AutomaticItemUpdates([
                'account_item_updates_settings' => new ItemUpdatesAccountLevelSettings([
                    'allow_price_updates' => true,
                    'allow_availability_updates' => true,
                    'allow_strict_availability_updates' => true,
                    'allow_condition_updates' => true
                ])
            ]),
            'image_improvements' => new AutomaticImageImprovements([
                'account_image_improvements_settings' => new ImageImprovementsAccountLevelSettings([
                    'allow_automatic_image_improvements' => true
                ])
            ]),
            'shipping_improvements' => new AutomaticShippingImprovements([
                'allow_shipping_improvements' => true
            ])
        ]);

        // Creates a FieldMask to indicate that all paths provided in $automaticImprovements
        // should be updated. The "*" path means to replace all updatable fields.
        $fieldMask = new FieldMask(['paths' => ['*']]);

        // Creates the UpdateAutomaticImprovementsRequest.
        $request = new UpdateAutomaticImprovementsRequest([
            'automatic_improvements' => $automaticImprovements,
            'update_mask' => $fieldMask
        ]);

        printf("Sending Update AutomaticImprovements request%s", PHP_EOL);

        try {
            // Makes the API call to update automatic improvements settings.
            $response = $automaticImprovementsServiceClient->updateAutomaticImprovements($request);

            printf("Updated AutomaticImprovements Name below%s", PHP_EOL);
            printf("%s%s", $response->getName(), PHP_EOL);
        } catch (ApiException $e) {
            printf("ApiException was thrown: %s%s", $e->getMessage(), PHP_EOL);
        }
    }

    /**
     * Helper to execute the sample.
     *
     * @return void
     */
    public function callSample(): void
    {
        $config = Config::generateConfig();
        self::updateAutomaticImprovementsSample($config);
    }
}

// Runs the script.
$sample = new UpdateAutomaticImprovementsSample();
$sample->callSample();
UpdateAutomaticImprovementsSample.php

Python

"""Updates the automatic improvements settings for a Merchant Center account."""
from examples.authentication import configuration
from examples.authentication import generate_user_credentials
from google.protobuf import field_mask_pb2
from google.shopping.merchant_accounts_v1beta import AutomaticImageImprovements
from google.shopping.merchant_accounts_v1beta import AutomaticImprovements
from google.shopping.merchant_accounts_v1beta import AutomaticImprovementsServiceClient
from google.shopping.merchant_accounts_v1beta import AutomaticItemUpdates
from google.shopping.merchant_accounts_v1beta import AutomaticShippingImprovements
from google.shopping.merchant_accounts_v1beta import UpdateAutomaticImprovementsRequest


# Fetches the Merchant Center account ID from the configuration.
_ACCOUNT_ID = configuration.Configuration().read_merchant_info()

# The resource name for the AutomaticImprovements settings of the account.
# Format: accounts/{account}/automaticImprovements
_AUTOMATIC_IMPROVEMENTS_RESOURCE_NAME = (
    f"accounts/{_ACCOUNT_ID}/automaticImprovements"
)


def update_automatic_improvements_settings():
  """Updates automatic improvements settings for a Merchant Center account to enable all available automatic improvements.
  """

  # Generates OAuth 2.0 credentials for authenticating with the API.
  credentials = generate_user_credentials.main()

  # Creates a client for the AutomaticImprovementsService.
  client = AutomaticImprovementsServiceClient(credentials=credentials)

  # Prepares the AutomaticImprovements object with all improvements enabled.
  # The 'name' field specifies the AutomaticImprovements resource to update.
  automatic_improvements_config = AutomaticImprovements(
      name=_AUTOMATIC_IMPROVEMENTS_RESOURCE_NAME,
      item_updates=AutomaticItemUpdates(
          account_item_updates_settings=AutomaticItemUpdates.ItemUpdatesAccountLevelSettings(
              allow_price_updates=True,
              allow_availability_updates=True,
              allow_strict_availability_updates=True,
              allow_condition_updates=True,
          )
      ),
      image_improvements=AutomaticImageImprovements(
          account_image_improvements_settings=
          AutomaticImageImprovements.ImageImprovementsAccountLevelSettings(
              allow_automatic_image_improvements=True
          )
      ),
      shipping_improvements=AutomaticShippingImprovements(
          allow_shipping_improvements=True
      ),
  )

  # Creates a field mask to specify which fields of the
  # AutomaticImprovements resource should be updated.
  # Using "*" indicates that all fields provided in the
  # automatic_improvements_config object should be updated.
  field_mask = field_mask_pb2.FieldMask(paths=["*"])

  # Creates the update request, including the configured
  # AutomaticImprovements object and the field mask.
  request = UpdateAutomaticImprovementsRequest(
      automatic_improvements=automatic_improvements_config,
      update_mask=field_mask,
  )

  # Sends the request to update automatic improvements and handles the response.
  try:
    print("Sending Update AutomaticImprovements request")
    response = client.update_automatic_improvements(request=request)
    print("Updated AutomaticImprovements Name below")
    print(response.name)
  except RuntimeError as e:
    # Catches and prints any errors that occur during the API call.
    print(e)


if __name__ == "__main__":
  update_automatic_improvements_settings()

update_automatic_improvements_sample.py

cURL

curl --location --request PATCH 'https://merchantapi.googleapis.com/accounts/v1beta/accounts/YOUR_ACCOUNT_ID/automaticImprovements?update_mask=*' \
--header 'Authorization: Bearer <var>API_TOKEN</var>' \
--header 'Content-Type: application/json' \
--data '{
  "name": "accounts/YOUR_ACCOUNT_ID/automaticImprovements",
  "itemUpdates": {
    "accountItemUpdatesSettings": {
      "allowPriceUpdates": true,
      "allowAvailabilityUpdates": true,
      "allowStrictAvailabilityUpdates": true,
      "allowConditionUpdates": true
    }
  },
  "imageImprovements": {
    "accountImageImprovementsSettings": {
      "allowAutomaticImageImprovements": true
    }
  },
  "shippingImprovements": {
    "accountShippingImprovementsSettings": {
      "allowShippingImprovements": true
    }
  }
}'

Learn more

Previous
Subscribe to push notifications
Next
Manage Merchant Center email notifications