Google Play

Set up Google Play product sync, purchase verification, and real-time developer notifications

Google Play

Connect Google Play to sync subscriptions and one-time products, verify Android purchases, consume eligible consumables, process refunds and voided purchases, and keep subscription state current with Real-time Developer Notifications (RTDN).

Set up Developer API credentials

Nuxie uses the Google Play Developer API to read your catalog, validate purchase tokens, acknowledge or consume purchases, hydrate order details, and reconcile refunds.

In Google Cloud, create or select a project and enable the Google Play Android Developer API.
Create a service account for Nuxie server-to-server access.
In Google Play Console, grant that service account access to your developer account or app. Include billing-related access such as viewing financial data and managing orders/subscriptions as appropriate for your workflow.
Download the service account JSON key.
In the Nuxie dashboard, open your Google Play app's Settings page.
Paste the service account JSON into Google Play Developer API.
Save, then click Test to verify that Nuxie can call the Developer API for the app's package name.

Nuxie encrypts and stores the service account JSON. The configured package name must match the Android package name in Google Play Console.

Tip: Google notes that RTDN only tells you that purchase state changed. Nuxie follows Google's guidance by calling the Developer API after each notification to fetch the complete purchase state.

Configure RTDN

Google Play sends RTDN through Google Cloud Pub/Sub. Choose the Nuxie environment that should receive the app's Google Play RTDN stream, then use that environment's Play Store webhook URL as the Pub/Sub push endpoint.

Google Play does not include an App Store-style sandbox or environment field in RTDN. Nuxie stores Google Play test-purchase metadata after hydrating the purchase through the Developer API, but the Nuxie environment is still determined by the webhook URL you configure. If you create separate Pub/Sub push subscriptions for test and live from the same Google Play topic, both subscriptions receive the same notification stream.

In Google Cloud Pub/Sub, create a topic for your app.
Grant google-play-developer-notifications@system.gserviceaccount.com the Pub/Sub Publisher role on that topic.
Create a push subscription for the topic.
Use the Nuxie Play Store webhook URL from your app settings:
text
```
https://webhooks.nuxie.ai/play-store/{appId}/{env}
```
Enable push authentication on the subscription and select a service account. Copy that service account email into Pub/Sub Service Account Email in Nuxie.
If you set a custom Pub/Sub token audience, copy it into Pub/Sub Audience. Otherwise Nuxie verifies the audience against the exact push endpoint URL. When you append a token query parameter, include that query parameter in the Pub/Sub push endpoint audience.
Optionally set a Pub/Sub Verification Token in Nuxie. If you use one, append it to the push endpoint:
text
```
https://webhooks.nuxie.ai/play-store/{appId}/{env}?token=your-shared-token
```
In Google Play Console, go to Monetize > Monetization setup > Real-time developer notifications.
Enable real-time notifications and enter the topic name in the format projects/{project_id}/topics/{topic_name}.
Choose Get all notifications for subscriptions and one-time products if you sell one-time products. Choose the subscription-only option only if the app never sells one-time products through Google Play.
Send a test message from Play Console and confirm that the Nuxie webhook accepts it.

Nuxie validates Pub/Sub push requests using Google's OpenID Connect JWT when a Pub/Sub service account email is configured. The JWT email must match your configured Pub/Sub service account email, the email must be verified, and the audience must match the configured audience or webhook URL. If you configure a verification token, Nuxie also requires the token query parameter to match.

Supported notifications

Google Play notification	What Nuxie does
`SUBSCRIPTION_PURCHASED`	Creates or updates the subscription and grants entitlements
`SUBSCRIPTION_RENEWED`	Extends the billing period and keeps access active
`SUBSCRIPTION_CANCELED`	Records cancellation while preserving access until expiry when Google reports an active period
`SUBSCRIPTION_PENDING_PURCHASE_CANCELED`	Records a canceled pending subscription purchase or upgrade without treating the existing subscription as canceled
`SUBSCRIPTION_ON_HOLD`	Marks the subscription with a billing issue
`SUBSCRIPTION_IN_GRACE_PERIOD`	Marks the subscription past due while retaining grace-period access
`SUBSCRIPTION_PAUSE_SCHEDULE_CHANGED`	Records that a future pause was scheduled while preserving access until the current period ends
`SUBSCRIPTION_PAUSED`	Marks the subscription paused, removes access, and stores auto-resume context
`SUBSCRIPTION_RESTARTED` / `SUBSCRIPTION_RECOVERED`	Reactivates the subscription
`SUBSCRIPTION_REVOKED` / voided purchase	Records refund or revocation, updates entitlements, and includes refund transaction metadata when Google Play reports a revoked subscription as a refund
`SUBSCRIPTION_EXPIRED`	Expires the subscription and removes access
`SUBSCRIPTION_DEFERRED`	Records a period extension
`SUBSCRIPTION_ITEMS_CHANGED`	Handles subscription item/base-plan changes
`ONE_TIME_PRODUCT_PURCHASED`	Records the one-time purchase and grants entitlements
`ONE_TIME_PRODUCT_CANCELED`	Records a canceled pending one-time product purchase without granting entitlements
`TEST`	Acknowledges the test notification without changing state

Product sync

Nuxie can import your Google Play catalog so product definitions stay aligned with Play Console.

Configure Developer API credentials.
Open Products in your Google Play app dashboard.
Click Import from Google Play.
Review created, updated, unchanged, and deactivated products.
Confirm the sync.

The sync imports:

Subscription products and all non-draft base plans.
Subscription offers, including free trials and introductory pricing metadata.
One-time products and all non-draft purchase options.
One-time product offers, including discounted and pre-order offers.
Regional pricing for the app's default currency when available.

Google Play subscriptions can have multiple base plans under one product ID. Nuxie represents each base plan as a product using this external ID shape:

text

{googleProductId}:{basePlanId}

Google Play one-time products can have multiple purchase options. If there is a single or legacy-compatible purchase option, Nuxie keeps the product external ID as the Google Play product ID. Additional purchase options use:

text

{googleProductId}:{purchaseOptionId}

Products removed from Google Play are soft-deactivated in Nuxie when they were created by Google Play sync.

Purchase sync

When your Android app completes or observes a Google Play purchase, send the purchase token to Nuxie through the SDK or POST /purchase.

json

{
  "apiKey": "nux_live_abc123",
  "type": "playstore",
  "purchase_token": "google-play-purchase-token",
  "product_id": "premium",
  "base_plan_id": "monthly"
}

distinct_id is optional for Google Play purchase sync. When it is omitted, Nuxie uses Google Play external/obfuscated account identifiers from the hydrated purchase payload when present, then falls back to a stable purchase-token identity.

For one-time products, send the Google Play product_id when your app is reporting a single known product. Nuxie derives the purchase option from the Developer API purchase payload. For multi-product one-time purchases, Google Play can identify the purchase by token while the individual products come from purchases.productsv2; send product_type: "one_time" and omit product_id when the app only has the token-level purchase. If the product is consumable and your app should let the customer buy it again, set consume_purchase to true; otherwise Nuxie acknowledges the completed purchase. Multi-quantity one-time purchases are token-scoped and grant finite entitlements according to the remaining refundable quantity, so repeat consumable purchases keep separate Google Play purchase-token ownership for later refunds. Multi-product one-time RTDNs may omit sku; Nuxie uses the purchase token to hydrate purchases.productsv2 and grants every returned line item.

Rented one-time product purchase options grant time-limited access. Google Play marks rental line items with productLineItem[].productOfferDetails.rentOfferDetails in purchases.productsv2, while the rental duration comes from the synced one-time product catalog rentOption.rentalPeriod. Nuxie uses that catalog rental period as the entitlement window starting at purchase completion, stores the end time on the customer product and transaction, preserves the rental marker and expiration period as provider metadata, and returns a configuration error instead of granting open-ended access if a rental purchase is missing duration metadata. Keep product sync enabled for apps that sell rentals. Analytics events and customer webhooks include the resolved access window, access period source, rental period, rental expiration period, and preorder release time when present.

Pending Google Play purchases are recorded but do not grant entitlements until Google marks them purchased. Pending subscription top-ups, upgrades, and downgrades keep the linked existing subscription active until the pending transaction completes. If Google reports the pending transaction as canceled or expired, including SUBSCRIPTION_STATE_PENDING_PURCHASE_EXPIRED from purchases.subscriptionsv2, Nuxie records pending_purchase_canceled and leaves the linked active subscription in place.

Google Play does not expose an App Store-style account-wide purchase history endpoint. For repair and catch-up sync, Nuxie replays known Google Play purchase tokens from previously ingested SDK purchases, RTDN, and refund records. Scheduled replay uses an app-level cursor so configured Play Store apps are rotated at a bounded interval. Large replay backlogs are scanned from a stable source-transaction snapshot in keyset-paginated continuation jobs, and the app-level cursor advances only after the final page succeeds. Each replay refetches the current purchases.subscriptionsv2 or purchases.productsv2 resource, hydrates the related Orders API details when an order ID is available, and updates the existing customer product, transaction, entitlement, acknowledgement, and order metadata idempotently.

When Google Play reports a subscription add-on with deferredItemRemoval, Nuxie keeps the add-on active through the returned expiry time and marks the customer product as cancel-at-period-end so access remains correct while the scheduled removal is visible. Subscription replacement metadata is preserved from lineItems[].itemReplacement and lineItems[].deferredItemReplacement; transaction, analytics, and webhook metadata include normalized replacement product, base-plan, offer, and mode fields when Google returns them.

Nuxie resolves customers using, in order:

An existing transaction or customer product for the purchase token.
Linked purchase tokens and out-of-app resubscribe context for subscription changes.
The distinct_id passed by the app.
Google Play external, obfuscated account/profile, and out-of-app resubscribe identifiers when present.
Subscribe with Google profile identity when Google returns it and no app account identifier is available.
A stable fallback based on the purchase token.

Cancellation events include Google Play cancellation context when available. Nuxie normalizes whether the cancellation was user-, system-, developer-, or replacement-initiated and forwards user cancel survey reason fields to analytics and customer webhooks.

Billing retry events include Google Play renewal-declined context when available. For account hold and grace-period notifications, Nuxie forwards the failed or pending renewal order ID as billing issue metadata.

Price step-up consent updates from Google Play RTDN are delivered as price_increase_consent. Nuxie hydrates purchases.subscriptionsv2 and forwards the recurring price, price-change mode/state, expected new-price charge time, consent deadline, and new price to analytics and customer webhooks.

Signup promotions preserve Google Play promotion type metadata from lineItems[].signupPromotion. Analytics events and customer webhooks include whether the subscription used a one-time code or vanity code, and include the vanity promotion code when Google returns it.

Installment subscriptions preserve Google Play committed-payment counts and pending cancellation status. Product sync uses the base plan billingPeriodDuration for the Nuxie price interval and stores the commitment/renewal settings in product metadata. Analytics events and customer webhooks include the initial, subsequent, and remaining committed payment counts when Google returns autoRenewingPlan.installmentDetails.

Refunds and voided purchases

Google Play can notify Nuxie about refunds through RTDN voided purchase notifications. Nuxie also runs scheduled Voided Purchases API sync so missed or delayed refund events are reconciled.

For quantity-based partial refunds, Nuxie reduces the customer product quantity and debits finite entitlement balances instead of revoking the whole product when Google provides voidedQuantity. If RTDN reports a quantity-based partial refund without voidedQuantity, Nuxie follows Google's guidance and reads refundableQuantity from purchases.productsv2 to determine the remaining quantity. Full refunds expire the affected customer product and record a refund transaction. Refund webhooks include Google Play refund type, voided source, voided reason, refunded quantity, remaining quantity, and hydrated Orders API refund amount, currency, tax, source, state, and timestamps when available.

Testing

Use Google Play license testers and an internal test track before going live. Google Play RTDN does not include an App Store-style sandbox environment field, so Nuxie classifies license-tester purchases from the hydrated Developer API purchase payload. Test subscription purchases are stored with isTestPurchase from testPurchase, one-time product test purchases are stored from testPurchaseContext, and analytics events include google_play_test_purchase.

Configure the Nuxie test environment webhook URL as the Pub/Sub push endpoint while testing.
Send a test RTDN message from Play Console.
Make a subscription purchase with a license tester.
Confirm that Nuxie creates the customer product, transaction, and entitlements.
Test renewal, cancellation, account hold/grace-period, one-time purchase, consumable, and refund scenarios.
Move the Pub/Sub push endpoint to the Nuxie live environment before production launch.

Next steps

Products & Prices -- configure products and pricing in Nuxie
Purchases & Subscriptions -- understand the full subscription lifecycle
Webhooks -- review webhook URL patterns and retry behavior