Filter accounts you can access

You can use Merchant Accounts API to view a filtered list of the accounts you can access, including sub-accounts. You can filter them by display name and by their relationships to other accounts.

For example, to see all your stores that haven't accepted an account link request, you could filter for accounts with display names that contain the string "store" and have a link status of PENDING.

Basic filtering

To view all your subaccounts, call accounts.v1beta.accounts.listSubAccounts.

To view a filtered list of all the accounts you have access to, including sub-accounts and any accounts that have you as a User, call accounts.v1beta.accounts.list and specify your filter criteria in the filter field.

For details on the syntax for the filter field, see the filter syntax reference.

Account filters

You can use the following fields to filter at the account level:

• accountName: Filters by the accountName of the account resource.
• capabilities: Filters by the capabilities of the account resource (note that this field is not available on the resource itself). Only the CAN_UPLOAD_PRODUCTS capability is supported. This field supports negation and uses the collection syntax. For example:
  • capabilities:CAN_UPLOAD_PRODUCTS returns accounts that can upload products
  • -capabilities:CAN_UPLOAD_PRODUCTS returns accounts that can not upload products
  • NOT capabilities:CAN_UPLOAD_PRODUCTS returns accounts that can not upload products
• relationship(...): Filters by the type of relationship the account has with another account. You can include multiple relationship(...) filters in one request.

Relationship filters

AccountRelationship is a child of the Account resource. Its only mutable field is accountIdAlias. This field allows a provider to specify an alias for an account, an alternate way to reference it. Establishing a service between a Merchant Center account and a third party creates an instance of this resource.

You can use the relationship(...) function to filter based on the following criteria:

• providerId: The merchant ID of the service provider. For example, if the filter should return only accounts that have a service provided by account/123, use providerId = 123.
• accountIdAlias: The account ID alias that is configured for the relationship. This filter requires also setting a providerId.
• service(...): The service that is provided as part of the relationship. You can include multiple service(...) functions in one relationship(...) function.

Service filters

You can use the service(...) function to further filter accounts based on the status of their relationships, and the types of services those relationships provide:

• externalAccountId: The service provider's external account ID for the account it provides a service to.
• handshakeState: The state of a service agreement between two accounts. Accepts the following values:
  • PENDING
  • APPROVED
• type: The type of service given by the provider. Accepts the following values:
  • ACCOUNT_MANAGEMENT The provider manages the account.
  • ACCOUNT_AGGREGATION The provider is an aggregator of the account.

Examples

Here are some examples of filters you can try.

Filter for accounts with display names containing "store" and providers with the ID "123":

accountName = "*store*" AND relationship(providerId = 123)

Filter for accounts with display names containing "store" that cannot upload products:

accountName = "*store*" AND -capabilities:CAN_UPLOAD_PRODUCTS

Filter for all sub-accounts of account "123":

relationship(providerId = 123 AND service(type = "ACCOUNT_AGGREGATION"))

Filter for accounts with approved account management services:

relationship(service(handshakeState = "APPROVED" AND type = "ACCOUNT_MANAGEMENT"))

Filter for accounts with a relationship that has a specific alias and the relationship has a service with a specific external account ID.

relationship(accountIdAlias = "alias" AND service(externalAccountId = "extAcctId"))

The following sample demonstrates how you can use the ListAccountsRequest package to retrieve a filtered list of the accounts.

Java

import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.accounts.v1beta.Account;
import com.google.shopping.merchant.accounts.v1beta.AccountsServiceClient;
import com.google.shopping.merchant.accounts.v1beta.AccountsServiceClient.ListAccountsPagedResponse;
import com.google.shopping.merchant.accounts.v1beta.AccountsServiceSettings;
import com.google.shopping.merchant.accounts.v1beta.ListAccountsRequest;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to filter the accounts the user making the request has access to. */
public class FilterAccountsSample {

  public static void filterAccounts(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.
    AccountsServiceSettings accountsServiceSettings =
        AccountsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    // Calls the API and catches and prints any network failures/errors.
    try (AccountsServiceClient accountsServiceClient =
        AccountsServiceClient.create(accountsServiceSettings)) {

      // Filter for accounts with display names containing "store" and a provider with the ID "123":
      String filter = "accountName = \"*store*\" AND relationship(providerId = 123)";

      // Filter for all subaccounts of account "123":
      // String filter2 = "relationship(providerId = 123 AND service(type =
      // \"ACCOUNT_AGGREGATION\"))";

      // String filter3 = "relationship(service(handshakeState = \"APPROVED\" AND type =
      // \"ACCOUNT_MANAGEMENT\") AND providerId = 123)";

      ListAccountsRequest request = ListAccountsRequest.newBuilder().setFilter(filter).build();

      System.out.println("Sending list accounts request with filter:");
      ListAccountsPagedResponse response = accountsServiceClient.listAccounts(request);

      int count = 0;

      // Iterates over all rows in all pages and prints the sub-account
      // in each row.
      // `response.iterateAll()` automatically uses the `nextPageToken` and recalls the
      // request to fetch all pages of data.
      for (Account account : response.iterateAll()) {
        System.out.println(account);
        count++;
      }
      System.out.print("The following count of elements were returned: ");
      System.out.println(count);
    } catch (Exception e) {
      System.out.println(e);
    }
  }

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

    filterAccounts(config);
  }
}
FilterAccountsSample.java

What's next

• For more information about filtering accounts, see Filter syntax.