You can subscribe to ACCOUNT_SERVICE_CHANGE notifications to receive
real-time alerts when AccountService resources are created, updated, or
deleted. This is particularly valuable for third-party providers and businesses
managing multi-account service relationships.
Subscribing to account service changes lets you immediately detect when an account service is proposed, approved, updated, or removed, without polling the API.
Before you begin, ensure that your callback URI is configured according to the requirements described in the Notifications sub-API Overview.
Subscribe to account service changes
To subscribe to account service changes, send a POST request to the
notificationsubscriptions resource with registeredEvent set to
ACCOUNT_SERVICE_CHANGE.
Subscribe for a specific target account
The following sample request subscribes to account service changes for a specific merchant account:
POST https://merchantapi.googleapis.com/notifications/v1/accounts/{ACCOUNT_ID}/notificationsubscriptions/
{
"registeredEvent": "ACCOUNT_SERVICE_CHANGE",
"targetAccount": "accounts/{TARGETACCOUNT_ID}",
"callBackUri": "https://example.com/callback"
}
Replace the following:
- ACCOUNT_ID: The identifier of the account that owns the subscription and receives notifications.
- TARGETACCOUNT_ID: The identifier of the account about which you want to receive notifications.
Subscribe for all managed accounts
Providers and businesses managing multiple merchant accounts can subscribe to
account service changes across all managed accounts by setting
allManagedAccounts: true:
POST https://merchantapi.googleapis.com/notifications/v1/accounts/{ACCOUNT_ID}/notificationsubscriptions/
{
"registeredEvent": "ACCOUNT_SERVICE_CHANGE",
"allManagedAccounts": true,
"callBackUri": "https://example.com/callback"
}
Successful calls return a
name
identifier for your subscription, including a unique subscription ID:
{
"name":"accounts/{ACCOUNT_ID}/notificationsubscriptions/{SUBSCRIPTION_ID}",
"registeredEvent": "ACCOUNT_SERVICE_CHANGE",
"allManagedAccounts": true,
"callBackUri": "https://example.com/callback"
}
Decode account service change payloads
When an account service change occurs, your callback URI receives a
base64-encoded message. When decoded, the payload conforms to the
ResourceChangeMessage
format:
{
"account": "accounts/{TARGETACCOUNT_ID}",
"managingAccount": "accounts/{ACCOUNT_ID}",
"resourceType": "ACCOUNT_SERVICE",
"resource": "accounts/{TARGETACCOUNT_ID}/services/{SERVICE_ID}",
"operation": "CREATE",
"eventTime": "2026-08-25T10:00:00Z"
}
Payload fields and rules
account: The target account that owns the changed service entity (accounts/{merchant_id}).managingAccount: The account that manages the merchant's account (accounts/{service_provider_id}).resourceType: The resource type that changed (ACCOUNT_SERVICE).resource: The full resource name of the account service (for example,accounts/{account}/services/{service}).operation: The operation performed on the resource:CREATE: A new account service relationship was created.UPDATE: An existing account service configuration or permission changed.DELETE: An account service relationship was removed.
eventTime: The timestamp when the event was generated. Use this timestamp to ensure proper ordering of events.
Test account service change notifications
Use the following sample request to test whether your callback endpoint receives, acknowledges, and decodes account service change messages correctly:
curl --request POST \
'https://{YOUR_CALLBACK_URI}' \
--header 'Content-Type: application/json' \
--header 'Accept: text/plain' \
--data '{"message":{"data": "ewogICJhY2NvdW50IjogImFjY291bnRzLzEyMzQiLAogICJtYW5hZ2luZ0FjY291bnQiOiAiYWNjb3VudHMvNTY3OCIsCiAgInJlc291cmNlVHlwZSI6ICJBQ0NPVU5UX1NFUlZJQ0UiLAogICJyZXNvdXJjZSI6ICJhY2NvdW50cy8xMjM0L3NlcnZpY2VzLzEyMyIsCiAgIm9wZXJhdGlvbiI6ICJDUkVBVEUiLAogICJldmVudFRpbWUiOiAiMjAyNi0wOC0yNVQxMDowMDowMFoiCn0="}}'In response to this call, your callback URI should return an acceptable HTTP
status code (such as 200 OK). The decoded message has the following content:
{
"account": "accounts/1234",
"managingAccount": "accounts/5678",
"resourceType": "ACCOUNT_SERVICE",
"resource": "accounts/1234/services/123",
"operation": "CREATE",
"eventTime": "2026-08-25T10:00:00Z"
}