Overview of Merchant Data sources API

This page shows how to programmatically create and update your data sources that let you insert products. Automated data sources make it easier to send your product data to Google. Automated data sources make sure that the most up-to-date information about relevant products from your website reach Google.

Content API for Shopping only lets you create primary data sources. With Merchant Data sources API, you can create the following types of data sources:

• Primary product data sources
• Supplemental product data sources
• Local inventory data sources
• Regional inventory data sources
• Promotion data sources
• Product review data sources
• Merchant review data sources

Content API for Shopping only lets you manage data sources with file input. Merchant API lets you manage data sources with both file and API inputs.

Using Merchant Data sources API, you can do the following:

• Create a new primary data source with a specific feedLabel and contentLanguage.
• Create a data source that doesn't have feedLabel and contentLanguage fields set. Using this type of data source you can target multiple countries for your products, as you can insert products with different combinations of feedLabel and contentLanguage into a single data source.
• Create a supplemental data source to link to an existing primary data source.
• Set up a schedule for a file data source.
• Enroll your account for automatic management of data sources.
• Manage API data sources.
• Manage the default rule of data sources using primary product data sources.
• Use other types of data sources like promotions.

You cannot use Merchant API to insert products in a data source that contains both local and online products. For more information about data sources channels, see Channels.

Prerequisites

• Your account must have been migrated to single locale feeds.

• To verify that the account is already migrated to data target split, use the data source list or get methods. In case you aren't eligible, you will receive the following exception message and you should contact support.

  This account is in the data sources migration process and can't be used with
  this API yet. Contact support for more info on when this account will be able
  to use the data sources endpoint.
  

Create a new data source

Primary data sources are the main data sources for your Merchant Center inventory. You can only add or remove products using a primary data source. If every product you add to your primary data source meets Merchant Center's data and eligibility requirements, you won't need to create any more data sources.

To create a new primary data source with a specific feedLabel and contentLanguage, set the feedLabel and contentLanguage fields in the type-specific configuration. For more information about these fields, see PrimaryProductDataSource.

The following sample request demonstrates how you can create a primary product data source:

POST https://merchantapi.googleapis.com/datasources/v1beta/accounts/{ACCOUNT_ID}/dataSources

{
  "displayName": "{DISPLAY_NAME}",
  "primaryProductDataSource": {
    "contentLanguage": "{CONTENT_LANGUAGE}",
    "feedLabel": "{FEED_LABEL}",
    "countries": [
      "{COUNTRY}"
    ],
    "channel": "ONLINE_PRODUCTS"
  }
}

Replace the following:

• {ACCOUNT_ID}: The unique identifier of your Merchant Center account.
• {DISPLAY_NAME}: The display name of the data source.
• {CONTENT_LANGUAGE}: The two-letter ISO 639-1 language code of the products in the data source.
• {FEED_LABEL}: The feed label of the data source.
• {COUNTRY}: The CLDR territory code of the target country of the products that will be uploaded using the data source.

After the request is successfully run, you see the following response:

{
  "name": "accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}",
  "dataSourceId": "{DATASOURCE_ID}",
  "displayName": "{DISPLAY_NAME}",
  "primaryProductDataSource": {
    "channel": "ONLINE_PRODUCTS",
    "feedLabel": "{FEED_LABEL}",
    "contentLanguage": "{CONTENT_LANGUAGE}",
    "countries": [
      "{COUNTRY}"
    ],
    "defaultRule": {
      "takeFromDataSources": [
        {
          "self": true
        }
      ]
    }
  },
  "input": "API"
}

For more information about creating a data source, see the accounts.dataSources.create method.

To view your newly created data source, use the accounts.dataSources.get or accounts.dataSources.list method.

The following sample demonstrates how you can create a primary product data source for the GB and en feedLabel and contentLanguage combination.

Java

     public static String createDataSource(Config config, String displayName) throws Exception {
    GoogleCredentials credential = new Authenticator().authenticate();

    DataSourcesServiceSettings dataSourcesServiceSettings =
        DataSourcesServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    String parent = getParent(config.getAccountId().toString());

    // The type of data that this datasource will receive.
    PrimaryProductDataSource primaryProductDataSource =
        PrimaryProductDataSource.newBuilder()
            // Channel can be "ONLINE_PRODUCTS" or "LOCAL_PRODUCTS" or "PRODUCTS" .
            // While accepted, datasources with channel "products" representing unified products
            // currently cannot be used with the Products bundle.
            .setChannel(PrimaryProductDataSource.Channel.ONLINE_PRODUCTS)
            .addCountries("GB")
            .build();

    try (DataSourcesServiceClient dataSourcesServiceClient =
        DataSourcesServiceClient.create(dataSourcesServiceSettings)) {

      CreateDataSourceRequest request =
          CreateDataSourceRequest.newBuilder()
              .setParent(parent)
              .setDataSource(
                  DataSource.newBuilder()
                      .setDisplayName(displayName)
                      .setPrimaryProductDataSource(primaryProductDataSource)
                      .build())
              .build();

      System.out.println("Sending Create PrimaryProduct DataSource request");
      DataSource response = dataSourcesServiceClient.createDataSource(request);
      System.out.println("Created DataSource Name below");
      System.out.println(response.getName());
      return response.getName();
    } catch (Exception e) {
      System.out.println(e);
      System.exit(1);
      // Null is necessary to satisfy the compiler as we're not returning a String on failure.
      return null;
    }
  }
CreatePrimaryProductDataSourceWildCardSample.java

Create a new primary data source that helps target multiple countries

To create a new primary feed that helps you target multiple countries, configure your data source using PrimaryProductDataSource and don't set the feedLabel and contentLanguage fields.

Using Content API for Shopping, there is only one API data source created for you. Using Merchant Data sources API, you can have multiple API data sources, some of which can be without the feedLabel and contentLanguage fields set.

Only data sources with API input can be without the feedLabel and contentLanguage fields set. This type of data sources isn't supported for file inputs.

Create a supplemental data source and link it to the primary data source

Supplemental data sources are used only to update product data that already exists in one or more primary data sources. You can have multiple supplementary data sources, and each one can supplement data in any number of primary data sources.

You can use supplemental data sources to make partial updates to product data by adding the unique identifier of the data source as a query parameter when making calls to the accounts.productInputs.insert and accounts.productInputs.delete methods. You can only use supplemental data sources to update existing products.

To create a supplemental data source, configure your data source using SupplementalProductDataSource and then link it by updating the defaultRule field on your primary data source.

Supplemental file data sources must have the feedLabel and contentLanguage fields set. Supplemental API data sources must always have the feedLabel and contentLanguage fields unset.

The following sample demonstrates how you can create a file supplemental product data source for the en and GB contentLanguage and feedLabel combination.

Java

     private static FileInput setFileInput() {
    // If FetchSettings are not set, then this will be an `UPLOAD` file type
    // that you must manually upload via the Merchant Center UI.
    return FileInput.newBuilder()
        // FileName is required for `UPLOAD` fileInput type.
        .setFileName("British T-shirts Supplemental Data")
        .build();
  }

  public static String createDataSource(Config config, String displayName, FileInput fileInput)
      throws Exception {
    GoogleCredentials credential = new Authenticator().authenticate();

    DataSourcesServiceSettings dataSourcesServiceSettings =
        DataSourcesServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    String parent = getParent(config.getAccountId().toString());

    try (DataSourcesServiceClient dataSourcesServiceClient =
        DataSourcesServiceClient.create(dataSourcesServiceSettings)) {

      CreateDataSourceRequest request =
          CreateDataSourceRequest.newBuilder()
              .setParent(parent)
              .setDataSource(
                  DataSource.newBuilder()
                      .setDisplayName(displayName)
                      .setSupplementalProductDataSource(
                          SupplementalProductDataSource.newBuilder()
                              .setContentLanguage("en")
                              .setFeedLabel("GB")
                              .build())
                      .setFileInput(fileInput)
                      .build())
              .build();

      System.out.println("Sending create SupplementalProduct DataSource request");
      DataSource response = dataSourcesServiceClient.createDataSource(request);
      System.out.println("Created DataSource Name below");
      System.out.println(response.getName());
      return response.getName();
    } catch (Exception e) {
      System.out.println(e);
      System.exit(1);
      // Null is necessary to satisfy the compiler as we're not returning a String on failure.
      return null;
    }
  }
CreateFileSupplementalProductDataSourceSample.java

To create a supplemental data source that works for all feedLabel and contentLanguage combinations, run the following sample.

Java

     public static String createDataSource(Config config, String displayName) throws Exception {
    GoogleCredentials credential = new Authenticator().authenticate();

    DataSourcesServiceSettings dataSourcesServiceSettings =
        DataSourcesServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    String parent = getParent(config.getAccountId().toString());

    try (DataSourcesServiceClient dataSourcesServiceClient =
        DataSourcesServiceClient.create(dataSourcesServiceSettings)) {

      CreateDataSourceRequest request =
          CreateDataSourceRequest.newBuilder()
              .setParent(parent)
              .setDataSource(
                  DataSource.newBuilder()
                      .setDisplayName(displayName)
                      .setSupplementalProductDataSource(
                          SupplementalProductDataSource.newBuilder().build())
                      .build())
              .build();

      System.out.println("Sending create SupplementalProduct DataSource request");
      DataSource response = dataSourcesServiceClient.createDataSource(request);
      System.out.println("Created DataSource Name below");
      System.out.println(response.getName());
      return response.getName();
    } catch (Exception e) {
      System.out.println(e);
      System.exit(1);
      return null; // Necessary to satisfy the compiler as we're not returning a
      // String on failure.
    }
  }
CreateSupplementalProductDataSourceWildCardSample.java

Set up a schedule for your file data source

To set up a schedule for your file feed, configure your data source to be a file data source by using the FileInput field and then set up fetchsettings using the FileInput.FetchSettings field.

Delete a data source

To delete an existing data source from your account, use the accounts.dataSources.delete method.

The following sample demonstrates how you can use the DeleteDataSourceRequest package to delete a data source.

Java

     public static void deleteDataSource(Config config, String dataSourceId) throws Exception {
    GoogleCredentials credential = new Authenticator().authenticate();

    DataSourcesServiceSettings dataSourcesServiceSettings =
        DataSourcesServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    String name =
        DataSourceName.newBuilder()
            .setAccount(config.getAccountId().toString())
            .setDatasource(dataSourceId)
            .build()
            .toString();

    try (DataSourcesServiceClient dataSourcesServiceClient =
        DataSourcesServiceClient.create(dataSourcesServiceSettings)) {
      DeleteDataSourceRequest request = DeleteDataSourceRequest.newBuilder().setName(name).build();

      System.out.println("Sending deleteDataSource request");
      // Delete works for any datasource type.
      // If Type "Supplemental", delete will only work if it's not linked to any primary feed.
      // If a link exists and the Type is "Supplemental", you will need to remove the supplemental
      // feed from the default and/or custom rule(s) of any primary feed(s) that references it. Then
      // retry the delete.

      dataSourcesServiceClient.deleteDataSource(request); // No response returned on success.
      System.out.println(
          "Delete successful, note that it may take a few minutes for the delete to update in"
              + " the system.");
    } catch (Exception e) {
      System.out.println(e);
    }
  }
DeleteDataSourceSample.java

Fetch data source

To fetch a file configured in the data source, use the accounts.dataSources.fetch method. This method perform the data fetch immediately on a data source from your account. This method only works on data sources with a file input set.

Get data source

To retrieve the data source configuration for your account, use the accounts.dataSources.get method.

The following sample demonstrates how you can use the GetDataSourceRequest package to retrieve a specific data source for a given Merchant Center account.

Java

     public static DataSource getDataSource(Config config, String dataSourceId) throws Exception {

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

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

    // Creates datasource name to identify datasource.
    String name =
        DataSourceName.newBuilder()
            .setAccount(config.getAccountId().toString())
            .setDatasource(dataSourceId)
            .build()
            .toString();

    // Calls the API and catches and prints any network failures/errors.
    try (DataSourcesServiceClient dataSourcesServiceClient =
        DataSourcesServiceClient.create(dataSourcesServiceSettings)) {

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

      System.out.println("Sending GET DataSource request:");
      DataSource response = dataSourcesServiceClient.getDataSource(request);

      System.out.println("Retrieved DataSource below");
      System.out.println(response);
      return response;
    } catch (Exception e) {
      System.out.println(e);
      System.exit(1);
      return null; // Necessary to satisfy the compiler as we're not returning a
      // DataSource on failure.
    }
  }
GetDataSourceSample.java

List data source

To list the configurations for data sources for your account, use the accounts.dataSources.list method.

The following sample demonstrates how you can use the ListDataSourceRequest package to list all the data sources for a given Merchant Center account.

Java

     public static ArrayList<DataSource> listDataSources(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.
    DataSourcesServiceSettings dataSourcesServiceSettings =
        DataSourcesServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Creates parent to identify the account from which to list all the datasources.
    String parent = getParent(config.getAccountId().toString());

    // Calls the API and catches and prints any network failures/errors.
    try (DataSourcesServiceClient dataSourcesServiceClient =
        DataSourcesServiceClient.create(dataSourcesServiceSettings)) {

      // The parent has the format: accounts/{account}
      ListDataSourcesRequest request =
          ListDataSourcesRequest.newBuilder().setParent(parent).build();

      System.out.println("Sending list datasources request:");
      ListDataSourcesPagedResponse response = dataSourcesServiceClient.listDataSources(request);

      int count = 0;
      ArrayList<DataSource> dataSources = new ArrayList<DataSource>();
      ArrayList<DataSource> justPrimaryDataSources = new ArrayList<DataSource>();

      // Iterates over all rows in all pages and prints the datasource in each row.
      // Automatically uses the `nextPageToken` if returned to fetch all pages of data.
      for (DataSource element : response.iterateAll()) {
        System.out.println(element);
        count++;
        dataSources.add(element);
        // The below lines show how to filter datasources based on type.
        // `element.hasSupplementalProductDataSource()` would give you supplemental
        // datasources, etc.
        if (element.hasPrimaryProductDataSource()) {
          justPrimaryDataSources.add(element);
        }
      }
      System.out.print("The following count of elements were returned: ");
      System.out.println(count);
      return dataSources;
    } catch (Exception e) {
      System.out.println(e);
      System.exit(1);
      return null; // Necessary to satisfy the compiler as we're not returning an
      // ArrayList<DataSource> on failure.
    }
  }
ListDataSourcesSample.java

Patch data source

To update the configuration of an existing data source, use the accounts.dataSources.patch method.

The following sample demonstrates how you can use the UpdateDataSourceRequest package to update a data source. It also demonstrates how to update a primary data source to add supplemental data sources to its default rule.

Java

     public static String updateDataSource(Config config, String displayName, String dataSourceId)
      throws Exception {
    GoogleCredentials credential = new Authenticator().authenticate();

    DataSourcesServiceSettings dataSourcesServiceSettings =
        DataSourcesServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Creates datasource name to identify datasource.
    String name =
        DataSourceName.newBuilder()
            .setAccount(config.getAccountId().toString())
            .setDatasource(dataSourceId)
            .build()
            .toString();

    DataSource dataSource =
        DataSource.newBuilder()
            // Update the datasource to have the new display name
            .setDisplayName(displayName)
            .setName(name)
            .build();

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

    try (DataSourcesServiceClient dataSourcesServiceClient =
        DataSourcesServiceClient.create(dataSourcesServiceSettings)) {

      UpdateDataSourceRequest request =
          UpdateDataSourceRequest.newBuilder()
              .setDataSource(dataSource)
              .setUpdateMask(fieldMask)
              .build();

      System.out.println("Sending Update DataSource request");
      DataSource response = dataSourcesServiceClient.updateDataSource(request);
      System.out.println("Updated DataSource Name below");
      System.out.println(response.getName());
      return response.getName();
    } catch (Exception e) {
      System.out.println(e);
      System.exit(1);
      return null;
    }
  }

  public String updateDataSource(
      Config config,
      String primaryDataSourceName,
      String firstSupplementalDataSourceName,
      String secondSupplementalDataSourceName)
      throws Exception {
    GoogleCredentials credential = new Authenticator().authenticate();

    DataSourcesServiceSettings dataSourcesServiceSettings =
        DataSourcesServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Setting self to 'true' refers to the primary datasource itself.
    DataSourceReference dataSourceReferenceSelf =
        DataSourceReference.newBuilder().setSelf(true).build();
    DataSourceReference firstSupplementalDataSourceReference =
        DataSourceReference.newBuilder()
            .setSupplementalDataSourceName(firstSupplementalDataSourceName)
            .build();
    DataSourceReference secondSupplementalDataSourceReference =
        DataSourceReference.newBuilder()
            .setSupplementalDataSourceName(secondSupplementalDataSourceName)
            .build();

    // The attributes will first be taken from the primary DataSource.
    // Then the first supplemental DataSource if the attribute is not in the primary DataSource
    // And finally the second supplemental DataSource if not in the first two DataSources.
    // Note that CustomRules could change the behavior of how updates are applied.
    DefaultRule defaultRule =
        DefaultRule.newBuilder()
            .addTakeFromDataSources(dataSourceReferenceSelf)
            .addTakeFromDataSources(firstSupplementalDataSourceReference)
            .addTakeFromDataSources(secondSupplementalDataSourceReference)
            .build();

    // The type of data that this datasource will receive.
    PrimaryProductDataSource primaryProductDataSource =
        PrimaryProductDataSource.newBuilder().setDefaultRule(defaultRule).build();

    DataSource dataSource =
        DataSource.newBuilder()
            // Update the primary datasource to have the default rule datasources in the correct
            // order.
            .setPrimaryProductDataSource(primaryProductDataSource)
            .setName(primaryDataSourceName)
            .build();

    // The '.' signifies a nested field.
    FieldMask fieldMask =
        FieldMask.newBuilder().addPaths("primary_product_data_source.default_rule").build();

    try (DataSourcesServiceClient dataSourcesServiceClient =
        DataSourcesServiceClient.create(dataSourcesServiceSettings)) {

      UpdateDataSourceRequest request =
          UpdateDataSourceRequest.newBuilder()
              .setDataSource(dataSource)
              .setUpdateMask(fieldMask)
              .build();

      System.out.println("Sending Update DataSource request");
      DataSource response = dataSourcesServiceClient.updateDataSource(request);
      System.out.println("Updated DataSource Name below");
      System.out.println(response.getName());
      return response.getName();
    } catch (Exception e) {
      System.out.println(e);
      System.exit(1);
      return null;
    }
  }
UpdateDataSourceSample.java

Link data sources

Primary product data sources let you manage the default rule of data sources. The default rule is the rule that applies to all attributes in your data source. The default rule can be set while creating the data source or by updating an existing data source through the default rule field.

For more information about setting up rules, see Set up rules for your product data sources.

The following sample configuration ensures that all attributes are first taken from the data source with the unique identifier 1001. Then the missing attributes are added from the primary data source. Eventually, the remaining attributes will be taken from the supplemental data source with the unique identifier 1002 if not already provided in any other data source. If the same attribute is provided in multiple data sources, the value higher in the list is selected.

defaultRule {
 takeFromDataSources: [
   '1001', // Supplemental product data source
   'self', //  Self reference to the primary data source
   '1002' // Supplemental product data source
 ]
}

Note: Custom rules cannot be modified through the API.

Auto-management of feeds

To enroll your account for automatic management of data sources, you must do the following:

• Check whether your account is eligible for enrollment by calling the accounts.autofeedSettings.getAutofeedSettings method.
• Make sure that you account isn't a marketplace account.

After your account is eligible for enrollment, you can use the accounts.autofeedSettings.updateAutofeedSettings method to enable automatic management of data sources. Enabling automatic management of data sources lets Google automatically add your products from your online store and ensure they are always up to date on Google's platforms.

Retrieve file upload status

To get the status of a data source with either file, fetch or spreadsheet, you can call the GET method of the accounts.dataSources.fileUploads service. To obtain the result of the last retrieval of the data source computed asynchronously when the data source processing is finished, use the name identifier latest.

GET https://merchantapi.googleapis.com/accounts/v1beta/{ACCOUNT_ID}/datasources/{DATASOURCE_ID}/fileUploads/latest

The file upload status might contain a detailed view of your products, including any potential issues.

Note that the file upload status might not exist if the file was never uploaded. The file upload status might be in the processing state if requested soon after the file is uploaded.