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.

Partner could use appropriate processing in their application for such changes.

Currently, we don't provide notifications on other resources such as products and promotions.

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 service accounts they wish to be allow-listed to subscribe to the topics. We recommend using the default service accounts provided by Compute Engine, or App Engine.

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
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
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. 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 subscription.

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",
  "product": "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",
}
  • 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",
  "product": "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_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",
}

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