Purchases & Subscriptions
Subscription lifecycle, status tracking, and payment processing
When a customer buys a product, Nuxie processes the purchase, creates a subscription record, and grants entitlements. From that point forward, Nuxie tracks the subscription through its entire lifecycle – trials, renewals, cancellations, and expiry – keeping your app’s access controls in sync automatically.
Subscription statuses
Every subscription has a status that determines whether the customer has access.
| Status | Access granted | Description |
|---|---|---|
| Active | Yes | The subscription is current and paid |
| Trialing | Yes | The customer is in a free trial period |
| Past due | Yes | Payment failed but the subscription has not been canceled yet |
| Scheduled | No | The subscription is scheduled to start in the future |
| Canceled | No | The customer canceled; access ends at the current period’s end |
| Expired | No | The subscription period ended without renewal |
| Paused | No | The subscription is temporarily paused |
| Billing issue | No | A payment problem requires customer action |
Entitlement checks treat active, trialing, and past due subscriptions as granting access. All other statuses deny access.
Tip: You can configure whether past-due subscriptions grant access in your app settings using the Include past due option.
How purchases work
The purchase flow depends on your payment processor, but the overall pattern is the same:
- Your app presents a paywall (via a campaign or directly).
- The customer taps a purchase button.
- The SDK sends the purchase request to Nuxie.
- Nuxie validates the product and price, processes payment, and creates the subscription.
- Entitlements are granted based on the product’s configuration.
- The SDK receives the updated feature list and refreshes the local profile.
App Store purchases
For App Store apps, purchases follow the StoreKit 2 flow:
- Your app uses StoreKit to initiate the purchase.
- After the transaction completes, the SDK sends the signed transaction to Nuxie.
- Nuxie decodes the transaction, matches it to a product, and provisions entitlements.
- The SDK receives the updated feature list.
Products must already exist in Nuxie with a processor ID matching the StoreKit product identifier. See App Store Connect for setup instructions.
Google Play purchases
For Google Play apps, purchases follow the Play Billing Library flow:
- Your app uses Google Play Billing to initiate or observe the purchase.
- After Google Play returns a purchase token, the app sends the token to Nuxie.
- Nuxie calls the Google Play Developer API, matches the purchase to a product or base plan, and provisions entitlements.
- Nuxie acknowledges completed purchases or consumes eligible consumables when requested.
- The SDK receives the updated feature list.
Products must already exist in Nuxie with processor IDs matching Google Play product IDs and, for subscriptions, base plan IDs. See Google Play for setup instructions.
Switching products
When a customer already has a subscription and purchases a different product, Nuxie handles the transition:
- Upgrades and downgrades – Nuxie modifies the existing subscription to swap the price.
- Add-ons – products marked as add-ons are attached alongside existing subscriptions rather than replacing them.
Subscription timing
Nuxie tracks key dates throughout the subscription lifecycle:
| Field | Description |
|---|---|
| Starts at | When the subscription began |
| Trial ends at | When the free trial expires (if applicable) |
| Current period start | Start of the current billing period |
| Current period end | End of the current billing period |
| Last renewed at | When the subscription last renewed |
| Canceled at | When the customer requested cancellation |
| Expired at | When the subscription fully expired |
These dates are updated automatically as Nuxie receives lifecycle events from your payment processor.
Renewals and cancellations
Nuxie receives lifecycle events from the App Store and Google Play to keep subscription state current:
- Renewals – when a subscription renews, Nuxie updates the period dates and maintains the active status. Entitlements continue without interruption.
- Cancellations – when a customer cancels, Nuxie marks the subscription and sets an expiry date at the end of the current period. Access continues until that date.
- Failed payments – if a renewal payment fails, the subscription moves to past due. Nuxie continues granting access while the processor retries payment.
- Refunds – Nuxie handles App Store refund notifications and Google Play voided purchases, including quantity-based partial refunds for eligible one-time products.
Viewing subscriptions in the dashboard
Open a customer’s profile in the dashboard to see all their subscriptions. Each subscription shows:
- The product name and external ID
- Current status
- Billing period dates
- Processor details (App Store original transaction ID)
- Granted entitlements and current balances
You can also adjust metered entitlement balances manually from the dashboard when needed.
Reconciliation
Nuxie keeps subscription state consistent across all layers:
- Processor to Nuxie – App Store server notifications and Google Play RTDN/voided-purchase sync update subscription records and entitlement balances.
- Edge to database – entitlement changes processed at the edge are reconciled back to the database for dashboard visibility.
- Background jobs – periodic jobs handle balance resets, usage billing, and drift correction to ensure accuracy over time.
This multi-layer approach means your app always sees accurate entitlement state, whether checking from the SDK, the API, or the dashboard.
Next steps
- Products & Prices – configure what your customers buy
- Features & Entitlements – define what products unlock
- App Store Connect – set up App Store server notifications
- Google Play – set up Google Play product sync and RTDN
- Cookbook: Revenue Tracking – track subscription revenue in your analytics