The accounts.list
method lets you retrieve a list of Account
resources that
the authenticated user can access. You can use the filter
query parameter to
narrow down the results based on various criteria, such as the following:
- Account properties
- Relationships with other accounts (such as, providers in an advanced account structure)
- Services associated with the accounts
This can be helpful for managing multiple accounts or finding specific business accounts that meet certain conditions.
You can use the following fields to filter at the account
level:
-
access
: Filters by the type of access the user has to theaccount
. This filter accepts the following values:-
DIRECT
: Returns only accounts that the user has direct access to. -
INDIRECT
: Returns only accounts that the user has indirect access to. -
ALL
: Returns all accounts the user has access to (both direct and indirect). This is the default behavior if the filter is not specified.
-
-
capabilities
: Filters by thecapabilities
of theaccount
resource (note that this field is not available on the resource itself). Only theCAN_UPLOAD_PRODUCTS
capability is supported. This field supports negation and uses the collection syntax. -
relationship(...)
: Filters by the type of relationship the account has with another account. You can include multiplerelationship(...)
filters in one request. -
accountName
: Filters by theaccountName
of theaccount
resource.
For more detailed information on the filter syntax, see the Filter syntax guide.
Examples
The following examples explain how to form the most typical queries. All the
following examples use the accounts.list
method. For more information, see the accounts.list
reference documentation.
Find sub-accounts of a specific provider
The accounts.listSubaccounts
method provides a direct way to list sub-accounts. You can also use the
filtering capabilities as described in the following sections. If you manage an
advanced account, you can list all its sub-accounts by filtering on the providerId
. Replace PROVIDER_ID
with the ID of
your advanced account.
For example, use relationship(providerId=123)
if the ID of the provider is 123
.
This is useful for managing the structure of your accounts.
GET https://merchantapi.googleapis.com/accounts/v1/accounts?filter=relationship(providerId%20%3D%20 PROVIDER_ID
)
A successful request returns a 200 status code and a response body with the list of matching sub-accounts:
{
"accounts"
:
[
{
"name"
:
"accounts/77777"
,
"accountId"
:
"77777"
,
"accountName"
:
"SubAccount A of Provider"
,
"adultContent"
:
false
,
"languageCode"
:
"fr"
,
"timeZone"
:
{
"id"
:
"Europe/Paris"
}
},
{
"name"
:
"accounts/88888"
,
"accountId"
:
"88888"
,
"accountName"
:
"SubAccount B of Provider"
,
"adultContent"
:
false
,
"languageCode"
:
"de"
,
"timeZone"
:
{
"id"
:
"Europe/Berlin"
}
}
],
"nextPageToken"
:
"XYZ123abcDEF..."
}
Find accounts that cannot upload products
You can combine multiple filter conditions to create more specific searches.
The filter accountName=*store* AND -capabilities:CAN_UPLOAD_PRODUCTS
finds all
accounts with "store" in their name that are not configured to upload products
directly. The -
before capabilities
acts as a negation operator. This can be
useful to retrieve only advanced accounts.
GET https://merchantapi.googleapis.com/accounts/v1/accounts?filter=accountName%20%3D%20%22*store*%22%20AND%20-capabilities%3ACAN_UPLOAD_PRODUCTS
A successful request returns a 200 status code and a response body with the list of matching accounts:
{
"accounts"
:
[
{
"name"
:
"accounts/54321"
,
"accountId"
:
"54321"
,
"accountName"
:
"Partner Store - US"
,
"adultContent"
:
false
,
"languageCode"
:
"en"
,
"timeZone"
:
{
"id"
:
"America/New_York"
}
},
{
"name"
:
"accounts/98765"
,
"accountId"
:
"98765"
,
"accountName"
:
"Auxiliary Brand Store"
,
"adultContent"
:
false
,
"languageCode"
:
"fr"
,
"timeZone"
:
{
"id"
:
"Europe/Paris"
}
}
],
"nextPageToken"
:
"CDEfghIJKlmnOPQ..."
}
Find accounts by name
You can search for accounts whose display name matches a specific pattern.
For example, accountName=*store*
would find all accounts with "store" in their
name.
This helps in quickly locating specific business accounts.
GET https://merchantapi.googleapis.com/accounts/v1/accounts?filter=accountName%20%3D%20%22*store*%22
A successful request returns a 200 status code and a response body with the list of matching accounts:
{
"accounts"
:
[
{
"name"
:
"accounts/12345"
,
"accountId"
:
"12345"
,
"accountName"
:
"My Awesome Store"
,
"adultContent"
:
false
,
"languageCode"
:
"en"
,
"timeZone"
:
{
"id"
:
"America/Los_Angeles"
}
},
{
"name"
:
"accounts/67890"
,
"accountId"
:
"67890"
,
"accountName"
:
"Another Store Online"
,
"adultContent"
:
false
,
"languageCode"
:
"en"
,
"timeZone"
:
{
"id"
:
"Europe/London"
}
}
],
"nextPageToken"
:
"ABSdefGHIjklMNO..."
}
Find accounts linked to a provider for a specific service
You can find accounts that have a specific service relationship with a provider.
For example, to find all accounts aggregated under the provider PROVIDER_ID
for account aggregation, use the filter relationship(providerId= PROVIDER_ID
) AND
service(type="ACCOUNT_AGGREGATION")
.
GET https://merchantapi.googleapis.com/accounts/v1/accounts?filter=relationship(providerId%20%3D%20 PROVIDER_ID
%20AND%20service(type%20%3D%20%22ACCOUNT_AGGREGATION%22))
A successful request returns a 200 status code and a response body with the list of matching accounts:
{
"accounts"
:
[
{
"name"
:
"accounts/54321"
,
"accountId"
:
"54321"
,
"accountName"
:
"Aggregated Account X"
,
"adultContent"
:
false
,
"languageCode"
:
"en"
,
"timeZone"
:
{
"id"
:
"America/New_York"
}
}
]
}
Find accounts based on service relationship approval state
You can filter accounts based on the status of their service relationship with a
provider. For example, to find all accounts that haven't accepted an account
link request (handshakeState = "PENDING")
from a specific provider PROVIDER_ID
.
For example, to find accounts where the provider ID is 123
, the service type
is ACCOUNT_MANAGEMENT
and the status is PENDING
, use relationship(service(handshakeState = "PENDING" AND type =
"ACCOUNT_MANAGEMENT") AND providerId = 123)
.
GET https://merchantapi.googleapis.com/accounts/v1/accounts?filter=relationship(service(handshakeState%20%3D%20%22PENDING%22%20AND%20type%20%3D%20%22ACCOUNT_MANAGEMENT%22)%20AND%20providerId%20%3D%20 PROVIDER_ID
)
A successful request returns a 200 status code and a response body with the list of matching accounts:
{
"accounts"
:
[
{
"name"
:
"accounts/98765"
,
"accountId"
:
"98765"
,
"accountName"
:
"Managed Account Y"
,
"adultContent"
:
false
,
"languageCode"
:
"es"
,
"timeZone"
:
{
"id"
:
"Europe/Madrid"
}
}
]
}
Filter accounts using client libraries
The following examples demonstrate how to use client libraries to filter
accounts based on combined criteria, such as account name and relationship with
a provider. These examples use the accounts.list
method. For more information,
see the accounts.list
reference documentation.
Java
import
com.google.api.gax.core.FixedCredentialsProvider
;
import
com.google.auth.oauth2.GoogleCredentials
;
import
com.google.shopping.merchant.accounts.v1.Account
;
import
com.google.shopping.merchant.accounts.v1.AccountsServiceClient
;
import
com.google.shopping.merchant.accounts.v1.AccountsServiceClient.ListAccountsPagedResponse
;
import
com.google.shopping.merchant.accounts.v1.AccountsServiceSettings
;
import
com.google.shopping.merchant.accounts.v1.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
);
}
}
PHP
use Google\ApiCore\ApiException;
use Google\Shopping\Merchant\Accounts\V1\Client\AccountsServiceClient;
use Google\Shopping\Merchant\Accounts\V1\ListAccountsRequest;
/**
* This class demonstrates how to filter the accounts the user making the request has access to.
*/
class FilterAccounts
{
public static function filterAccounts(array $config): void
{
// Gets the OAuth credentials to make the request.
$credentials = Authentication::useServiceAccountOrTokenFile();
// Creates options config containing credentials for the client to use.
$options = ['credentials' => $credentials];
// Creates a client.
$accountsServiceClient = new AccountsServiceClient($options);
// Calls the API and catches and prints any network failures/errors.
try {
// Filter for accounts with display names containing "store" and a provider with the ID "123":
$filter = "accountName = \"*store*\" AND relationship(providerId = 123)";
// Filter for all subaccounts of account "123":
// $filter = "relationship(providerId = 123 AND service(type = \"ACCOUNT_AGGREGATION\"))";
// $filter = "relationship(service(handshakeState = \"APPROVED\" AND type =
// \"ACCOUNT_MANAGEMENT\") AND providerId = 123)";
$request = new ListAccountsRequest(['filter' => $filter]);
print "Sending list accounts request with filter:\n";
$response = $accountsServiceClient->listAccounts($request);
$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.
foreach ($response->iterateAllElements() as $account) {
print_r($account);
$count++;
}
print "The following count of elements were returned: ";
print $count . PHP_EOL;
} catch (ApiException $e) {
print $e->getMessage();
}
}
public function callSample(): void
{
$config = Config::generateConfig();
self::filterAccounts($config);
}
}
$sample = new FilterAccounts();
$sample->callSample();