Nuxie/Docs
Monetization

Purchases & Subscriptions

Subscription lifecycle, status tracking, and payment processing

Purchases & Subscriptions

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.

StatusAccess grantedDescription
ActiveYesThe subscription is current and paid
TrialingYesThe customer is in a free trial period
Past dueYesPayment failed but the subscription has not been canceled yet
ScheduledNoThe subscription is scheduled to start in the future
CanceledNoThe customer canceled; access ends at the current period's end
ExpiredNoThe subscription period ended without renewal
PausedNoThe subscription is temporarily paused
Billing issueNoA 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:

  1. Your app presents a paywall (via a campaign or directly).
  2. The customer taps a purchase button.
  3. The SDK sends the purchase request to Nuxie.
  4. Nuxie validates the product and price, processes payment, and creates the subscription.
  5. Entitlements are granted based on the product's configuration.
  6. 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:

  1. Your app uses StoreKit to initiate the purchase.
  2. After the transaction completes, the SDK sends the signed transaction to Nuxie.
  3. Nuxie decodes the transaction, matches it to a product, and provisions entitlements.
  4. 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:

  1. Your app uses Google Play Billing to initiate or observe the purchase.
  2. After Google Play returns a purchase token, the app sends the token to Nuxie.
  3. Nuxie calls the Google Play Developer API, matches the purchase to a product or base plan, and provisions entitlements.
  4. Nuxie acknowledges completed purchases or consumes eligible consumables when requested.
  5. 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:

FieldDescription
Starts atWhen the subscription began
Trial ends atWhen the free trial expires (if applicable)
Current period startStart of the current billing period
Current period endEnd of the current billing period
Last renewed atWhen the subscription last renewed
Canceled atWhen the customer requested cancellation
Expired atWhen 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