💳 Subscriptions & Payments

The Tuned Global platform separates entitlements, subscriptions and payment processing into independent components.

At the core of the platform are Packages, which define the rights and capabilities available to a user. Users obtain these rights by subscribing to a Plan, which is purchased through a Merchant.

This separation allows the same Package to be offered through multiple subscription plans and payment providers while maintaining a single entitlement model throughout the platform.

For a detailed explanation of Packages, Plans and Merchants, refer to the Packages and Plans documentation.

Platform Model

The relationship between Packages, Plans, Merchants and Subscriptions is illustrated below.

A user never purchases a Package directly.

Instead, the user purchases a Plan through a Merchant. Once the subscription has been successfully processed, the corresponding Package is assigned to the user.

The assigned Package determines the user's capabilities throughout the Tuned Global platform.

Examples include:

• Streaming permissions
• Audio quality
• Offline playback
• Downloads
• Playlist creation
• Playback limits
• Family membership
• API capabilities
• Feature availability

Subscription Lifecycle

A Subscription represents the relationship between a User and an active Package.

A Subscription typically contains:

• Package
• Plan
• Merchant
• Subscription Status
• Start Date
• Renewal Date
• Expiry Date
• Auto Renewal Status
• Trial Status
• Source

Once a subscription becomes active, the Package determines the user's rights across all Tuned Global applications and APIs.

Subscriptions may be:

• Created
• Renewed
• Upgraded
• Downgraded
• Cancelled
• Expired

without changing the Package definitions.

There may be some differences between Integration Models and the actual execution - but Regardless of the model, the final result is always the assignment (or update) of the user's Package.

Payment Providers

The Tuned Global platform is payment-provider agnostic.

Subscriptions may originate from virtually any payment provider capable of communicating subscription events to the platform.

Supported implementations include:

• Apple In-App Purchase
• Google Play Billing
• RevenueCat
• Stripe
• Recurly
• Telco Billing
• Carrier Billing
• Voucher Systems
• Gift Cards
• Custom Payment Providers

Multiple Merchants may provide Plans that grant access to the same Package.

Payment providers confirm commercial events. The Tuned Global platform remains the system of record for subscription state and user entitlements.

Integration Models

Two primary subscription integration models are supported.

Managed Integrations

Tuned Global provides native subscription management for several commonly used payment providers.

Currently these include:

• RevenueCat (In App Payments)
• Stripe
• Recurly

For these integrations, the Tuned platform receives subscription callbacks directly from the provider and automatically updates the user's subscription.

The client is not required to manage subscription callbacks.

This is the recommended implementation wherever possible as it reduces integration effort while providing consistent subscription behaviour across platforms.

Client Managed Integrations

Clients may also integrate directly with any payment provider, including:

• Direct Apple In-App Purchase
• Direct Google Play Billing
• Telco Billing
• Carrier Billing
• Custom Payment Providers
• Internal Billing Platforms

In these scenarios:

• the client manages payment processing;
• the client receives and validates payment callbacks;
• the client updates the user's subscription using the tConnect APIs.

This provides complete flexibility while allowing the Tuned platform to maintain subscription state.

Application Integration

Applications are responsible for presenting subscription options and initiating the appropriate purchase workflow.

Typical application behaviour includes:

• Displaying available subscription Plans
• Displaying pricing
• Launching native purchase flows
• Redirecting users to external subscription websites
• Displaying subscription status
• Displaying renewal information
• Displaying upgrade options

Applications should never determine user rights based solely on a successful payment.

User capabilities should always be determined from the active Package assigned to the authenticated user.

API Integration

The Subscription APIs allow client systems to manage subscriptions independently of the underlying payment provider.

Typical operations include:

• Retrieve available Packages
• Retrieve Plans for a Merchant
• Retrieve current Subscription
• Assign a Subscription
• Renew a Subscription
• Cancel a Subscription
• Retrieve Subscription Status

When using client-managed payment providers, subscription updates should normally occur following successful payment confirmation or receipt of a payment webhook.

Trials

Trial subscriptions are implemented using dedicated Plans associated with an appropriate Package.

The Tuned platform records whether a user has previously been allocated a trial subscription. This enables applications and websites to determine trial eligibility without maintaining their own trial history.

A typical workflow is:

1. Authenticate the user.
2. Retrieve the user's profile.
3. Determine whether a trial has previously been allocated.
4. If eligible, assign the trial Plan.
5. Otherwise, continue with the selected paid subscription.

This ensures trial eligibility is applied consistently across all client applications and websites.

Renewals and Cancellations

Renewal behaviour depends on the integration model.

For Managed Integrations, subscription renewals and cancellations are processed automatically by the Tuned platform following provider callbacks.

For Client Managed Integrations, the client is responsible for processing renewal or cancellation events and communicating those changes using the tConnect APIs.

In both cases, the Tuned platform maintains the authoritative subscription state and updates the user's Package accordingly.

Family Plans

Family subscriptions are implemented as specialised Packages and Subscription types.

Management of Family members, invitations and acceptance workflows is described in the Family Plans documentation.

Voucher Redemption

Voucher redemption provides an alternative mechanism for activating or extending subscriptions.

Depending on the voucher configuration, redemption may:

1. activate a new subscription;
2. extend an existing subscription; or
3. assign a different Package.

Voucher workflows, implementation requirements and platform restrictions are described in the Voucher Redemption documentation.

Best Practices

When integrating subscriptions with the Tuned Global platform we recommend the following:

• Treat the Tuned platform as the authoritative source for subscription status and user entitlements.
• Use Packages to determine user capabilities rather than inferring rights from payment information.
• Use Managed Integrations where available to minimise implementation effort.
• Keep subscription state synchronised by processing all renewal, cancellation and expiry events.
• Determine trial eligibility using the Tuned APIs rather than maintaining separate trial records.
• Reference Package, Plan and Merchant identifiers when updating subscriptions using the tConnect APIs.