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](https://developers.google.com/merchant/api/guides/notifications/overview#prerequisites--callback-uri-setup).

## 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:

- <var translate="no">ACCOUNT_ID</var>: The identifier of the account that owns the subscription and receives notifications.
- <var translate="no">TARGETACCOUNT_ID</var>: 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`](https://developers.google.com/merchant/api/guides/compatibility/overview#aip-principles-identifiers)
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`](https://developers.google.com/merchant/api/reference/rpc/google.shopping.merchant.notifications.v1/Types/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.

> [!NOTE]
> **Note:** `ResourceChangeMessage` provides lightweight notifications without an embedded resource payload. When you receive a notification, use the `resource` name to call `accounts.services.get` in the Accounts API to fetch the latest service configuration details.

## 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"
    }