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.
2. Event name given (for example SUBSCRIPTION_ON_HOLD): search the Type column in the Subscription or One Time Product table.
3. 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.
4. 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.