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.

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 (via server notifications) 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 -- for App Store refunds, Nuxie receives a notification and can revoke entitlements.

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 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