Notifications sub-API Overview

You can use the Notifications sub-API to receive push notifications when data changes in your Merchant Center accounts. Instead of periodically polling the API to detect changes, you can subscribe to real-time event feeds delivered directly to an HTTPS endpoint that you configure.

The Notifications sub-API supports notifications for:

  • Product status changes: Receive real-time alerts when a product approval status changes (for example, when a product becomes disapproved or approved) across any of your linked accounts or sub-accounts.
  • Account service changes: Receive real-time alerts when an AccountService resource is created, updated, or deleted (such as when an account service relationship is established, modified, or removed).

Prerequisites & callback URI setup

To receive push notifications, you must provide a callBackUri. Your callback URI must meet the following requirements:

  • Must be a publicly accessible HTTPS address with a valid SSL certificate signed by a recognized certificate authority.
  • Must accept HTTP POST requests with the Content-Type header set to application/json.

  • Must return one of the following HTTP status codes to acknowledge that the notification was received:

    • 102
    • 200
    • 201
    • 202
    • 204

You can use the same callback URI for multiple subscriptions. To minimize the load on a single endpoint, use a unique callback URI per advanced account and event type.

Manage subscriptions

The Notifications sub-API provides methods to create, list, retrieve, update, and delete notification configurations.

Create a subscription

Subscription creation is specific to the event type you want to receive. Each event type requires different configuration fields and delivers distinct payload structures.

To learn how to create subscriptions and view sample requests for each event type, see the respective guides:

List subscriptions

To list all notification subscriptions for an account, send a GET request to the notificationsubscriptions collection:

GET https://merchantapi.googleapis.com/notifications/v1/accounts/{ACCOUNT_ID}/notificationsubscriptions

Retrieve a subscription

To get details for a specific subscription, use the subscription's resource name:

GET https://merchantapi.googleapis.com/notifications/v1/accounts/{ACCOUNT_ID}/notificationsubscriptions/{SUBSCRIPTION_ID}

Update a subscription

To update the callback URI for an existing subscription, send a PATCH request with an update_mask specifying the fields to update:

PATCH https://merchantapi.googleapis.com/notifications/v1/accounts/{ACCOUNT_ID}/notificationsubscriptions/{SUBSCRIPTION_ID}?update_mask=callBackUri

{
  "callBackUri": "https://example.com/updated-callback"
}

Delete a subscription

To stop receiving notifications, delete the subscription:

DELETE https://merchantapi.googleapis.com/notifications/v1/accounts/{ACCOUNT_ID}/notificationsubscriptions/{SUBSCRIPTION_ID}

Decode notifications

When an event occurs, Google delivers a notification to your registered callBackUri. The push notification arrives in a JSON envelope with a base64-encoded data payload:

{"message":{"data":"{base64_encoded_string}"}}

Decode the data string to access the JSON event payload. The following sample Spring Boot controller shows how to receive and decode push notifications:

@RestController
public class ExampleController {
@RequestMapping(value = "/push",
  method = RequestMethod.POST,
  consumes = {"application/json"},
  produces = {"text/plain"})
  @ResponseStatus(HttpStatus.OK)
  public void handleNotification(@RequestBody String message) {
        JSONObject jsonObject = new JSONObject(message);
        JSONObject jsonMessage = jsonObject.getJSONObject("message");
        String encodedData = jsonMessage.getString("data");
        byte[] decodedBytes = Base64.getDecoder().decode(encodedData);
        String decodedPayload = new String(decodedBytes);
        // Process decodedPayload according to the registered event type
  }
}

Next steps

To configure subscriptions and handle decoded payloads for specific events, see:

Next
Product status changes