Filter accounts you can access

You can use the Merchant Accounts API to view a filtered list of the accounts you have access to, including sub-accounts. You can filter by display names, and relationships to other accounts. For example, you might filter for accounts with display names that contain the string "store", that also have a PENDING link status, to see all your stores who haven't accepted an account link request yet.

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.

Here are the kinds of filters you can use:

Account filters

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

• accountName: Filters by the accountName of the account resource.
• relationship(...): Filters by the type of relationship the account has with another account. You can include multiple relationship(...) filters in one request.

Relationship filters

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.
• callerHasAccessToProviderFilter(): Filters for accounts that have a relationship with a service provider that you have access to.
• externalAccountId: The service provider's external account ID for the account it provides a service to.
• accountIdAlias: The account ID alias that is configured for the relationship.
• 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:

• 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 all subaccounts 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 specific alias and ID, who have access to a provider. You must also have access to the provider for this request:

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

What's next

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