Rtdn Reference

RTDN Reference

Phase 0: Intent

Tell the user: "I will look up the RTDN notification type you asked about and recommend handling."

Phase 1: Locate

Map the user's question to one of the tables in Phase 2:

1. Integer code given (for example notificationType: 5): determine which notification family the user is in.

• If the payload wraps the code in subscriptionNotification, use the Subscription Notification Types table.
• If the payload wraps the code in oneTimeProductNotification, use the One Time Product Notification Types table.
• If the payload has voidedPurchaseNotification, use the Voided Purchase Notification section.
• If the payload has testNotification, use the Test Notification section.

1. Event name given (for example SUBSCRIPTION_ON_HOLD): search the Type column in the Subscription or One Time Product table.
2. Symptom given (for example "user lost access after failed payment"): match the trigger phrase in the Trigger column. Account hold and grace period map to codes 5 and 6 respectively in the subscription table.
3. Unassigned code (14, 15, 16, 21): report that the code is reserved and not emitted.

After locating the row, jump to Phase 3 for the handling guidance for that family.

Phase 2: Reference tables

RTDN Message Structure

Every RTDN message arrives as a Cloud Pub/Sub message with a base64 encoded JSON payload in the data field. The decoded JSON has this structure:

{
  "version": "1.0",
  "packageName": "com.example.app",
  "eventTimeMillis": "1234567890123",
  "subscriptionNotification": { },
  "oneTimeProductNotification": { },
  "voidedPurchaseNotification": { },
  "testNotification": { }
}

Only one notification field is present per message.

Subscription Notification Types

| Code | Type | Trigger | Subscription State After | Required Action | |------|------|---------|--------------------------|-----------------| | 1 | SUBSCRIPTION_RECOVERED | Payment recovered from grace period, account hold, or pause resumes | ACTIVE | Grant access. Call subscriptionsv2.get to confirm state. | | 2 | SUBSCRIPTION_RENEWED | Active subscription successfully renewed | ACTIVE | Extend entitlement. Update expiryTime in your database. | | 3 | SUBSCRIPTION_CANCELED | Subscription canceled (user, developer, or system) | CANCELED | Check canceledStateContext for reason. User retains access until expiryTime. | | 4 | SUBSCRIPTION_PURCHASED | New subscription purchased | ACTIVE | Verify purchase. Grant access. Acknowledge within 3 days. | | 5 | SUBSCRIPTION_ON_HOLD | Grace period expired, entered account hold | ON_HOLD | Revoke access. Notify user to fix payment method. | | 6 | SUBSCRIPTION_IN_GRACE_PERIOD | Renewal payment failed, entered grace period | IN_GRACE_PERIOD | Retain access. Notify user about payment issue. Show in app message. | | 7 | SUBSCRIPTION_RESTARTED | User restored canceled subscription from Play Store before expiration | ACTIVE | Grant access. Same purchase token. | | 8 | SUBSCRIPTION_PRICE_CHANGE_CONFIRMED | (Deprecated) User confirmed a price change | No state change | Deprecated. Use type 19 instead. | | 9 | SUBSCRIPTION_DEFERRED | Subscription billing date extended via subscriptionsv2.defer | ACTIVE | Update expiryTime in your database. Extend access. | | 10 | SUBSCRIPTION_PAUSED | Subscription paused (effective at end of current period) | PAUSED | Revoke access when pause begins. | | 11 | SUBSCRIPTION_PAUSE_SCHEDULE_CHANGED | Pause schedule modified (pause set, changed, or removed) | Varies | Call API to check current pause schedule. | | 12 | SUBSCRIPTION_REVOKED | Subscription revoked (refund, developer revocation) | EXPIRED | Immediately revoke access. | | 13 | SUBSCRIPTION_EXPIRED | Subscription expired after cancellation or account hold failure | EXPIRED | Revoke access. Clean up entitlement records. | | 17 | SUBSCRIPTION_ITEMS_CHANGED | Items in subscription bundle changed (add ons) | Varies | Call API to get updated line items. | | 18 | SUBSCRIPTION_CANCELLATION_SCHEDULED | Installment subscription cancellation scheduled at end of commitment | ACTIVE (until commitment ends) | Note the scheduled cancellation. User retains access through commitment period. | | 19 | SUBSCRIPTION_PRICE_CHANGE_UPDATED | Price change details updated for existing subscribers | Varies | Call API to get updated price change information. | | 20 | SUBSCRIPTION_PENDING_PURCHASE_CANCELED | Pending subscription purchase was canceled | EXPIRED | Do not grant access. Clean up any pending records. | | 22 | SUBSCRIPTION_PRICE_STEP_UP_CONSENT_UPDATED | Price step up consent period begun or user provided consent (South Korea) | Varies | Call API to check consent status. |

Notification type codes 14, 15, 16, and 21 are not assigned. Do not expect to receive these values.

Subscription notification payload:

{
  "version": "1.0",
  "notificationType": 4,
  "purchaseToken": "purchase-token-string",
  "subscriptionId": "premium_monthly"
}

One Time Product Notification Types

| Code | Type | Trigger | Required Action | |------|------|---------|-----------------| | 1 | ONE_TIME_PRODUCT_PURCHASED | One time product purchase completed | Verify purchase. Grant access. Acknowledge or consume. | | 2 | ONE_TIME_PRODUCT_CANCELED | Pending one time product purchase was canceled | Do not grant access. Clean up pending records. |

One time product notification payload:

{
  "version": "1.0",
  "notificationType": 1,
  "purchaseToken": "purchase-token-string",
  "sku": "remove_ads"
}

One time product notifications include the sku field (the product ID); subscription notifications include subscriptionId.

Voided Purchase Notification

Sent when a purchase is voided due to a refund, chargeback, or revocation.

{
  "purchaseToken": "purchase-token-string",
  "orderId": "GPA.1234-5678-9012-34567",
  "productType": 1,
  "refundType": 1
}

| Field | Values | |-------|--------| | productType | 1 = Subscription, 2 = One time product | | refundType | 1 = Full refund, 2 = Quantity based refund |

Test Notification

{
  "version": "1.0"
}

Test notifications have only a version field inside the testNotification object.

Phase 3: Recommended handling

Subscription notifications

For every subscription notification:

1. Decode the base64 data field from the Pub/Sub message.
2. Parse the DeveloperNotification and read subscriptionNotification.notificationType.
3. Extract purchaseToken and subscriptionId.
4. Call purchases.subscriptionsv2.get on the Google Play Developer API with the purchase token.
5. Apply the action from the Required Action column in the table, using the API response as the source of truth.
6. Acknowledge the Pub/Sub message.

Code-specific notes:

• Codes 4 (purchase) and 1 (recovered) require acknowledging the purchase within 3 days or Google refunds it.
• Code 3 (canceled) is not an immediate revocation. Grant access until lineItems[].expiryTime.
• Code 5 (on hold) is the revoke-now signal after a failed renewal. Code 6 (grace period) is the keep-access signal.
• Code 12 (revoked) requires immediate access revocation regardless of expiryTime.
• Codes 11, 17, 19, 22 have a Varies state; the notification flags that something changed and the API holds the new value.
• Code 8 is deprecated. New integrations should handle code 19 instead.

One time product notifications

1. Read oneTimeProductNotification.notificationType and purchaseToken.
2. Call purchases.products.get on the Google Play Developer API.
3. For code 1, verify the purchase state, grant the entitlement, then acknowledge (non-consumable) or consume (consumable) within 3 days.
4. For code 2, discard any pending record you created when the user began checkout.

Voided purchase notifications

1. Revoke access immediately for the purchaseToken.
2. Call the Voided Purchases API (purchases.voidedpurchases.list) for full details, including voidedReason and voidedSource.
3. Use productType to route to your subscription or one time product tables.
4. Use refundType to decide whether to revoke the full entitlement or only an adjusted quantity.

Test notifications

Acknowledge the Pub/Sub message without processing it as a real event. Log receipt so you can confirm your integration is wired up when you trigger a test from Play Console.

Handler pattern (applies to every RTDN)

1. Receive the Pub/Sub message.
2. Decode the base64 data field.
3. Parse the JSON DeveloperNotification.
4. Identify which notification field is present.
5. Extract the purchaseToken.
6. Call the Google Play Developer API for current state.
7. Update your database from the API response, not from the notification alone.
8. Acknowledge the Pub/Sub message.

Never rely solely on the RTDN payload for business logic. RTDNs signal that something changed. The API tells you the current state.

References

• Full chapter

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: RevenueCat
• Source: RevenueCat/play-billing-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.