Pub/Sub Notifications

Partners can receive notifications of the state changes on subscriptions and purchase orders during their life cycles and should be treated as the source of truth. Partners need to subscribe to the corresponding Cloud Pubsub topic provisioned by Payments Reseller Subscription backend.

Subscription and Purchase Order notifications can be useful to detect and process events such as:

Google cancels a subscription:
user deleting their Google Account, or
a subscription failing to be extended by the partner during the grace period.
Google refunds a purchase order, prorated or in full.

Subscription Lifecycle

state transitions

Subscribing to Cloud Pubsub

During the onboarding process, each partner entity will be assigned with unique Cloud Pubsub Topic IDs for subscriptions and/or purchase orders. The partner will provide the accounts they wish to be allow-listed to subscribe to the topics.

For comprehensive information regarding subscription types and message handling, please refer to the Subscription Types section.

Please refer to subscriber best practices guide for more details.

Notification Specification

The notification is encoded in the pubsub message using the following specification:

data: subscription resource, or purchase order resource in json format. It is base64-encoded in Pubsub RESTful API. Pubsub SDK may return decoded value directly, see java example.
attributes: A map containing additional information related to the subscription in the message. Can be accessed via attributes field in the PubsubMessage, see java example. Currently has the following keys that are returned in the Map

Subscription Pubsub message attributes:

Key	Description
sequenceNumber	The sequence number is a unique number within a subscription (not globally unique) that can be used to handle idempotency and out-of-order notifications. Please store this sequence number for each subscription and ignore any notifications if the received sequence number equal or smaller than the stored sequence number of the same subscription.
state	Value corresponds to the String value of the enum `State`
cancellationReason	This entry will be populated only when CancellationReason is present in the message. Value corresponds to String value of enum `CancellationReason`
endUserEntitled	If an end user has linked their Google Account to the subscription. Possible values are `true` and `false`.

Purchase order Pubsub message attributes:

Key	Description
sequenceNumber	The sequence number is a unique number within a purchase order (not globally unique) that can be used to handle idempotency and out-of-order notifications. Recipients of notifications may want to persist this number and process a request only if the current sequence number is greater than the previous sequence number for a purchase order.

Partners can use attributes to create topic subscription with a filter in order to receive only messages that matches the filter. For instance, use filter such as attributes.state = "STATE_CANCELLED" AND attributes.cancellationReason = "CANCELLATION_REASON_ACCOUNT_CLOSED" to receive messages for cancelled subscriptions due to account closure. See docs for more information.

Following fields are not used:

orderingKey

Subscription notification examples:

User activating the service:

{
  "data": "ewogICJuYW1lIjogInBhcnRuZXJzL2RlbW8vc3Vic2NyaXB0aW9ucy82NWEzMGRmOS04NjY1LTQyYTgtOGM3Yi0wM2RjZTkxMzVlOWEiLAogICJwcm9kdWN0IjogInBhcnRuZXJzL2RlbW8vcHJvZHVjdHMvUFRQRC0xMjM0NTY3OCIsCiAgInBhcnRuZXJVc2VyVG9rZW4iOiAiMjE1NDkzNDI1MTY2IiwKICAicmVkaXJlY3RVcmkiOiAiaHR0cHM6Ly93d3cuZXhhbXBsZS5jb20iLAogICJzZXJ2aWNlTG9jYXRpb24iOiB7CiAgICAicmVnaW9uQ29kZSI6ICJVUyIKICB9LAogICJjeWNsZUVuZFRpbWUiOiAiMjAyMS0wMi0wMlQxNTowMToyM1oiLAogICJmcmVlVHJpYWxFbmRUaW1lIjogIjIwMjEtMDEtMDJUMTU6MDE6MjNaIiwKICAiZW5kVXNlckVudGl0bGVkIjogdHJ1ZSwKICAic3RhdGUiOiAiU1RBVEVfQUNUSVZFIiwKICAicHJvdmlzaW9uVGltZSI6ICIyMDIwLTEwLTAyVDE1OjAxOjIwWiIsCiAgImNyZWF0ZVRpbWUiOiAiMjAyMC0xMC0wMlQxNTowMToyM1oiLAogICJ1cGRhdGVUaW1lIjogIjIwMjAtMTAtMDhUMTU6MDE6MjNaIiwKfQ==",
  "attributes": {
    "state": "STATE_ACTIVE"
  },
  "messageId": "967147fc-6b2e-11eb-b3ac-a1d6ba962d73",
  "publishTime": "2021-02-02T15:01:23Z"
}

// The `data` field encodes the following subscription resource:
{
  "name": "partners/demo/subscriptions/65a30df9-8665-42a8-8c7b-03dce9135e9a",
  "products": ["partners/demo/products/PTPD-12345678"],
  "partnerUserToken": "215493425166",
  "redirectUri": "https://www.example.com",
  "serviceLocation": {
    "regionCode": "US"
  },
  "cycleEndTime": "2021-02-02T15:01:23Z",
  "freeTrialEndTime": "2021-01-02T15:01:23Z",
  "endUserEntitled": true,
  "state": "STATE_ACTIVE",
  "provisionTime": "2020-10-02T15:01:20Z",
  "createTime": "2020-10-02T15:01:23Z",
  "updateTime": "2020-10-08T15:01:23Z",
  "renewalTime": "2021-02-02T15:01:23Z",
  "lineItems": [{
    "product": "partners/demo/products/PTPD-12345678",
    "state": "LINE_ITEM_STATE_ACTIVE",
    "description": "Base Plan",
    "recurrenceType": "LINE_ITEM_RECURRENCE_TYPE_PERIODIC",
    "amount": {
      "currencyCode": "USD",
      "amountMicros": "12990000"
    },
    "lineItemIndex": 0
  }]
}

Subscription cancellation. It can be initiated by the partner or Google.

{
  "data": "ewogICJuYW1lIjogInBhcnRuZXJzL2RlbW8vc3Vic2NyaXB0aW9ucy82NWEzMGRmOS04NjY1LTQyYTgtOGM3Yi0wM2RjZTkxMzVlOWEiLAogICJwcm9kdWN0IjogInBhcnRuZXJzL2RlbW8vcHJvZHVjdHMvUFRQRC0xMjM0NTY3OCIsCiAgInBhcnRuZXJVc2VyVG9rZW4iOiAiMjE1NDkzNDI1MTY2IiwKICAicmVkaXJlY3RVcmkiOiAiaHR0cHM6Ly93d3cuZXhhbXBsZS5jb20iLAogICJzZXJ2aWNlTG9jYXRpb24iOiB7CiAgICAicmVnaW9uQ29kZSI6ICJVUyIKICB9LAogICJjeWNsZUVuZFRpbWUiOiAiMjAyMS0wMi0wMlQxNTowMToyM1oiLAogICJmcmVlVHJpYWxFbmRUaW1lIjogIjIwMjEtMDEtMDJUMTU6MDE6MjNaIiwKICAiZW5kVXNlckVudGl0bGVkIjogdHJ1ZSwKICAic3RhdGUiOiAiU1RBVEVfQ0FOQ0VMTEVEIiwKICAiY2FuY2VsbGF0aW9uRGV0YWlscyI6IHsKICAgICJyZWFzb24iOiAiQUNDT1VOVF9DTE9TRUQiCiAgfSwKICAicHJvdmlzaW9uVGltZSI6ICIyMDIwLTEwLTAyVDE1OjAxOjIwWiIsCiAgImNyZWF0ZVRpbWUiOiAiMjAyMC0xMC0wMlQxNTowMToyM1oiLAogICJ1cGRhdGVUaW1lIjogIjIwMjAtMTAtMDhUMTU6MDE6MjNaIiwKfQ==",
  "attributes": {
    "state": "STATE_CANCELLED",
    "cancellationReason": "CANCELLATION_REASON_ACCOUNT_CLOSED"
  },
  "messageId": "967147fc-6b2e-11eb-b3ac-a1d6ba962d73",
  "publishTime": "2021-02-02T15:01:23Z"
}

// The `data` field encodes the following subscription resource with cancellation details:
{
  "name": "partners/demo/subscriptions/65a30df9-8665-42a8-8c7b-03dce9135e9a",
  "products": ["partners/demo/products/PTPD-12345678"],
  "partnerUserToken": "215493425166",
  "redirectUri": "https://www.example.com",
  "serviceLocation": {
    "regionCode": "US"
  },
  "cycleEndTime": "2021-02-02T15:01:23Z",
  "freeTrialEndTime": "2021-01-02T15:01:23Z",
  "renewalTime": "2021-02-02T15:01:23Z",
  "endUserEntitled": true,
  "state": "STATE_CANCELLED",
  "cancellationDetails": {
    "reason": "CANCELLATION_REASON_ACCOUNT_CLOSED"
  },
  "provisionTime": "2020-10-02T15:01:20Z",
  "createTime": "2020-10-02T15:01:23Z",
  "updateTime": "2020-10-08T15:01:23Z",
  "lineItems": [{
    "product": "partners/demo/products/PTPD-12345678",
    "state": "LINE_ITEM_STATE_ACTIVE",
    "description": "Base Plan",
    "recurrenceType": "LINE_ITEM_RECURRENCE_TYPE_PERIODIC",
    "amount": {
      "currencyCode": "USD",
      "amountMicros": "12990000"
    },
    "lineItemIndex": 0
  }]
}

Purchase Order notification examples:

Upon subscription renewal charge :

{
  "data": "ewogICJuYW1lIjogInBhcnRuZXJzL2RlbW8vc3Vic2NyaXB0aW9ucy82NWEzMGRmOS04NjY1LTQyYTgtOGM3Yi0wM2RjZTkxMzVlOWEiLAogICJwcm9kdWN0IjogInBhcnRuZXJzL2RlbW8vcHJvZHVjdHMvUFRQRC0xMjM0NTY3OCIsCiAgInBhcnRuZXJVc2VyVG9rZW4iOiAiMjE1NDkzNDI1MTY2IiwKICAicmVkaXJlY3RVcmkiOiAiaHR0cHM6Ly93d3cuZXhhbXBsZS5jb20iLAogICJzZXJ2aWNlTG9jYXRpb24iOiB7CiAgICAicmVnaW9uQ29kZSI6ICJVUyIKICB9LAogICJjeWNsZUVuZFRpbWUiOiAiMjAyMS0wMi0wMlQxNTowMToyM1oiLAogICJmcmVlVHJpYWxFbmRUaW1lIjogIjIwMjEtMDEtMDJUMTU6MDE6MjNaIiwKICAiZW5kVXNlckVudGl0bGVkIjogdHJ1ZSwKICAic3RhdGUiOiAiU1RBVEVfQUNUSVZFIiwKICAicHJvdmlzaW9uVGltZSI6ICIyMDIwLTEwLTAyVDE1OjAxOjIwWiIsCiAgImNyZWF0ZVRpbWUiOiAiMjAyMC0xMC0wMlQxNTowMToyM1oiLAogICJ1cGRhdGVUaW1lIjogIjIwMjAtMTAtMDhUMTU6MDE6MjNaIiwKfQ==",
  "attributes": {
    "sequenceNumber": "1680291396"
  },
  "messageId": "967147fc-6b2e-11eb-b3ac-a1d6ba962d73",
  "publishTime": "2021-02-02T15:01:23Z"
}


// The `data` field encodes the following purchase order resource with charged details:
{
  "name": "partners/demo_partner/purchaseorders/be587593-9b44-4e6d-90b2-08db29689362",
  "partnerUserToken": "09DDE00156E31A9A909E0004AC1EA1AD",
  "lineItems": [{
    "product": "partners/demo_partner/products/844b3390-fc0b-4cce-9881-2531aa9ac56d",
    "description": "Base Plan",
    "amount": {
      "currencyCode": "USD",
      "amountMicros": "62990000"
    },
    "servicePeriod": {
      "startTime": "2023-03-25T17:33:47.503Z",
      "endTime": "2023-04-25T17:33:47.503Z"
    },
    "chargedDetails": {
      "priceDetails": {
        "pretaxAmount": {
          "currencyCode": "USD",
          "amountMicros": "62990000"
        },
        "taxAmount": {
          "currencyCode": "USD",
          "amountMicros": "0"
        },
        "totalAmount": {
          "currencyCode": "USD",
          "amountMicros": "62990000"
        }
      }
    }
  }],
  "subscriptionDetails": {
    "subscription": "partners/demo_partner/subscriptions/be587593-9b44-4e6d-90b2-08db29689362",
    "purchaseOrderType": "PURCHASE_ORDER_TYPE_RENEWAL"
  }
}

Pub/Sub Notifications Stay organized with collections Save and categorize content based on your preferences.