Subscriptions lifecycle

Overview

This page describes the overall lifecycle of a Purchase for a Subscription type Product. It contains an explanation for the several different states in the lifecycle that depend on numerous factors such as automatic renewals, payment decline cases and User and Developer actions.

To add Subscriptions to your application follow this page and to integrate them into your Application, use our Android Billing SDK solution.

States and events in Subcription lifecycle

When a Subscription state changes, you will receive a SubscriptionNotification event in your RTDN API.

The subscription lifecycle in this system includes seven distinct states, each representing a phase in the subscription's journey. Transitions between these states occur based on specific user or system events.

PENDING

Description:
The subscription is in the process of activation. This state occurs immediately after a purchase is finalized, but the purchase has not yet been consumed by the Developer. Users shouldn't have access to the subscription benefits at this point yet.

Key Characteristics:
- The user’s payment has been processed.
- The system awaits confirmation that the purchase has been consumed, which has to be initiated by the developer.
Transitions:
- To ACTIVE (SUBSCRIPTION_PURCHASED): The subscription transitions to the ACTIVE state when the purchase is consumed by the developer, indicating that the user is now entitled to the subscription benefits.
- To EXPIRED (SUBSCRIPTION_REVOKED): The subscription transitions to the EXPIRED state when the developer fails to consume the Purchase after 48 hours.

ACTIVE

Description:

The subscription is fully activated, and the user has access to all associated benefits. It is the main operational state of a subscription.

Key Characteristics:
- Entitlements are granted to the user.
- The subscription period begins and is actively billed.
Events Leading to Transitions:
- Payment Failure: If a recurring payment fails, the subscription may enter GRACE or HOLD states.
- Cancellation: If the user or developer cancels the subscription, it transitions to the CANCELED state. User can cancel the subscription in the AppCoins Wallet App following these steps: AppCoins Wallet > Settings > Manage Subscriptions in there, he can cancel the next payment, which will transition the Subscription to CANCELED.
- Revocation: If the developer explicitly revokes the subscription, it transitions to the EXPIRED state.
Transitions:
- To GRACE (SUBSCRIPTION_IN_GRACE_PERIOD): The subscription moves to GRACE if the user’s payment method is declined and a grace period is defined.
- To HOLD (SUBSCRIPTION_ON_HOLD): The subscription enters directly to HOLD when the active period ends and the grace period is not defined.
- To CANCELED (SUBSCRIPTION_CANCELED): The subscription transitions to CANCELED if canceled by the user or developer.
- To EXPIRED (SUBSCRIPTION_REVOKED): The subscription is revoked explicitly by the developer, terminating all entitlements.

GRACE

Description:
The subscription is in a grace period due to payment failure, providing the user with an opportunity to resolve the issue. During this time, the user retains access to the subscription benefits.

Key Characteristics:
- The system retries the payment within a defined grace period.
- Entitlements are not immediately revoked, offering a seamless user experience.
Events Leading to Transitions:
- Payment Method Fixed: If the user resolves the payment issue, the subscription transitions back to ACTIVE.
- Non-Resolution: If the payment issue is not resolved by the end of the grace period, the subscription transitions to HOLD or is EXPIRED if there is a direct action by the Developer.
Transitions:
- To ACTIVE (SUBSCRIPTION_RENEWED): The subscription is renewed upon successful payment resolution.
- To HOLD (SUBSCRIPTION_ON_HOLD): The subscription transitions to HOLD if the grace period ends without resolution.
- To EXPIRED (SUBSCRIPTION_CANCELED): The developer can cancel the subscription during the grace period. In this case, the state is directly changed to EXPIRED.
- To EXPIRED (SUBSCRIPTION_REVOKED): The developer can revoke the subscription, terminating it immediately.

HOLD

Description:
The subscription is temporarily suspended due to unresolved payment issues or after the grace period ends. During this state, the user loses access to subscription benefits, but the subscription is not yet fully terminated.

Key Characteristics:
- No entitlements are granted to the user.
- The system awaits payment resolution.
Events Leading to Transitions:
- Payment Method Fixed: If the user resolves the payment issue, the subscription transitions back to ACTIVE.
- Cancellation or Revocation: If no action is taken, the subscription transitions to EXPIRED or CANCELED depending on the behavior of the Developer.
Transitions:
- To ACTIVE (SUBSCRIPTION_RECOVERED): The subscription is recovered upon payment resolution.
- To EXPIRED (SUBSCRIPTION_REVOKED): The subscription transitions to EXPIRED if explicitly revoked by the developer.
- To CANCELED (SUBSCRIPTION_CANCELED): The subscription transitions to CANCELED if canceled by the developer or when the hold period ends without resolution.

CANCELED

Description:
The subscription has been canceled by the user or developer. However, the user retains access to subscription benefits until the end of the current billing period.

Key Characteristics:
- Entitlements remain active until the entitlement period ends.
- The subscription will transition to EXPIRED or ACTIVE.
Events Leading to Transitions:
- Reactivation: The user can reactivate the subscription before the entitlement period ends.
- Entitlement Period Ends: The subscription transitions to EXPIRED.
Transitions:
- To ACTIVE (SUBSCRIPTION_RESTARTED): The subscription becomes ACTIVE again if reactivated by the user. To reactivate the subscription, the User can follow this steps: AppCoins Wallet > Settings > Manage Subscriptions in there, he can Re-activate the Subscription billing, which will transition the Subscription to ACTIVE.
- To EXPIRED (SUBSCRIPTION_EXPIRED): The subscription expires when the entitlement period ends.
- To EXPIRED (SUBSCRIPTION_REVOKED): The developer can revoke the subscription immediately.

EXPIRED

Description:
The subscription period has ended, and the user no longer has access to the subscription benefits or if the subscription has been explicitly revoked by the developer. This action immediately terminates the subscription and all entitlements, regardless of the billing or entitlement period.

Key Characteristics:
- Entitlements are fully revoked.
- The subscription cannot be reactivated.

This is an End State for the Subscriptions, which means, that they cannot transition to any other state.

Developer Compliance

To ensure a seamless experience for users and prevent misbehavior, developers must adhere to guidelines that uphold the integrity of the subscription lifecycle. This section outlines best practices for developers to maintain proper access to entitlements.

Honor the Subscription States and Transitions
- Always follow the defined subscription state transitions to avoid removing user access prematurely or incorrectly.
- For example, users in the GRACE or CANCELED state must retain access to entitlements until their rightful expiration period ends.
Implement Robust Grace and Hold Periods
- Configure adequate grace and hold periods to give users a fair opportunity to resolve payment issues.
- Avoid shortening these periods arbitrarily, as it may lead to unnecessary subscription disruptions.
Communicate Clearly with Users
- Notify users promptly when payment failures, cancellations, or state changes occur.
- Provide clear instructions on how to recover their subscriptions or resolve payment issues.
Use Revocation Sparingly
- Only revoke subscriptions in cases of abuse, fraud, or user request.
- Revocation immediately terminates user access and must not be used as a substitute for regular cancellations or expirations.
Provide Transparent Cancellation Policies
- Ensure users understand the implications of cancellations and how entitlements are managed until the end of the billing cycle.
- Clearly explain the process for reactivation, if applicable.
Maintain Accurate Records
- Store the necessary subscription-related events, including state changes, payments, and user actions in your system to have a better grasp of the subscription state for each User.
- Use these records to address disputes or verify system behavior in case of errors.

Avoiding Common Issues

Early Removal of Access
- Do not remove entitlements from users in the CANCELED state until the entitlement period ends.
- Ensure that the transition to EXPIRED is deliberate and justified.
Failure to Notify Users
- Avoid silent state transitions. Always notify users about changes to their subscription status, including payment failures and cancellations.
Inconsistent Behavior Across States
- Ensure entitlements and access rights align consistently with each subscription state. For example:
  - Users in GRACE must retain access while payment retries are ongoing.
  - Users in HOLD lose access until payment is resolved but must not transition prematurely to CANCELED or EXPIRED.

FAQ

What is the Grace Period of a Subscription?

The grace period is defined when creating the Subscription product in the Aptoide Connect platform.

Can a Subscription be restored once in EXPIRED state?

No. Subscriptions in EXPIRED state cannot be restored. For that, initiate a new Subscription to that User.

How can I revoke or cancel a Subscription?

To revoke or cancel a Subscription, write to our technical team to make this step manually.

How can I get access to all the state changes of my Subscriptions?

To gain access to the state changes and receive automatic updates from our services, you need to implement a Server to which we will communicate to you the different state changes. Follow our RTDN (Real Time Developer Notifications) documentation.