Subscription lifecycle

AppDirect manages the lifecycle of subscriptions to products purchased through the marketplace. A subscription can have one of the following statuses at a time:

• FREE_TRIAL—The subscription is in the free trial period. The customer is not charged.
• FREE_TRIAL_EXPIRED—The free trial is expired. When the free trial grace period is over, the status changes to CANCELLED. If the customer wants to continue to use their product, they must upgrade to a paid subscription, at which point the status changes to ACTIVE.
• ACTIVE—Regular subscription in good standing. If the application is not free, the customer is charged the appropriate amount.
• INITIALIZED—Subscription activation is pending, either because provisioning is asynchronous or requires vendor or Marketplace Manager approval.
• SUSPENDED—An invoice for this subscription is overdue. Customers cannot use the subscription until they pay the invoice. This status appears in the following situations:
  • There is an unpaid, overdue invoice and the end of the grace period has been reached.
  • The end of the contract has been reached, the contract has not been renewed, and the end-of-contract grace period is in effect. If the grace period expires without renewal, the status changes to CANCELLED.
  • The initial purchase payment failed.
  • Only superusers can suspend the latest order through the UI or API. Other users can only suspend orders through the API.
  • The contract renewal failed.
• CANCELLED—The subscription is cancelled and no longer active. The subscription does not appear in the customer marketplace account.
• FAILED—Subscription provisioning failed and the subscription was never created.

Subscribe to products

The entry state for a subscription can either be FREE_TRIAL (if the edition purchased by the user has a free trial period) or ACTIVE. When a user purchases a subscription to a product, the marketplace notifies the vendor with a SUBSCRIPTION_ORDER event.

Free trial support

When customers subscribe to free trials, the subscriptions are in the FREE_TRIAL state. Customers can do one of the following:

• Allow the free trial subscription to expire—When the free trial expires and the user does not convert to a paid subscription, the subscription moves from the FREE_TRIAL state to the FREE_TRIAL_EXPIRED state. The marketplace triggers a SUBSCRIPTION_NOTICE event notification to the vendor that contains the notice type DEACTIVATED and the new subscription state of FREE_TRIAL_EXPIRED.
• Cancel the free trial before it expires—When customers cancel the free trial before it expires, the free trial moves to CANCELLED state . The marketplace triggers a SUBSCRIPTION_CANCEL event notification to the vendor. There is no SUBSCRIPTION_NOTICE event triggered.
• Convert the free trial subscription to a paid subscription before the free trial expires—The subscription moves from the FREE_TRIAL state to the ACTIVE state. The exact behavior varies depending on the conversion method:
  • If the owner clicks Upgrade to Paid Edition either through the MyApps page or through the Manage Applications page, or if the owner clicks Update subscription on the Manage Applications page and selects a paid edition, a SUBSCRIPTION_CHANGE event occurs, followed by a SUBSCRIPTION_NOTICE event with a REACTIVATED status. The user can continue to use the subscription until the free trial period is over, at which point they begin to be invoiced.
  • If the owner clicks Update subscription on the Manage Applications page and selects a paid edition, a SUBSCRIPTION_CHANGE event occurs, but there is no event.
• Convert the free trial subscription to a paid subscription after the free trial expires—First the subscription moves from the FREE_TRIAL state to the ACTIVE state and the marketplace triggers a SUBSCRIPTION_NOTICE event notification to the vendor, which contains the notice type REACTIVATED and the new subscription state of ACTIVE. Then a SUBSCRIPTION_CHANGE event occurs.
• Free trial ends and owner has not upgraded to a paid edition—Events, status changes, and notifications depend on how the editions are configured and what actions the product owner takes:
  • Automatic upgrade to paid edition—If the free trial is marked for automatic upgrade to a paid edition, then at the end of the free trial period, the marketplace sends a SUBSCRIPTION_NOTICE event notification to the vendor, which contains the notice type REACTIVATED. There is no SUBSCRIPTION_CHANGE event.
  • Free trial without a grace period—At the end of the free trial period, the subscription status changes to FREE_TRIAL_EXPIRED and a SUBSCRIPTION_NOTICE event of the type DEACTIVATED is sent. The subscription stays in the FREE_TRIAL_EXPIRED state until the owner manually cancels and then activates it.
  • Free trial with a grace period—At the end of the free trial period, the subscription status changes to FREE_TRIAL_EXPIRED and a SUBSCRIPTION_NOTICE event of the type DEACTIVATED is sent. When the free trial grace period expires, the subscription status changes to CANCELLED and a SUBSCRIPTION_NOTICE event of the type CLOSED is sent.
  • Expired free trial is cancelled—When a product owner cancels a subscription in the FREE_TRIAL_EXPIRED status, a SUBSCRIPTION_CANCEL notice is sent.
  • Expired free trial is activated—When a product owner activates a subscription in the FREE_TRIAL_EXPIRED status,a SUBSCRIPTION_CHANGE event occurs, followed by a SUBSCRIPTION_NOTICE event with a REACTIVATED status. The user can continue to use the subscription until the free trial period is over, at which point they begin to be invoiced.

Delinquent subscriptions

By default, AppDirect considers a subscription to be delinquent when three payments are missed.

When a customer misses an invoice payment for a subscription in the ACTIVE state, the subscription state changes to SUSPENDED. The marketplace triggers a SUBSCRIPTION_NOTICE event notification to the vendor, which contains the notice type DEACTIVATED, the new subscription state of SUSPENDED, and the company_entitlement is updated with a suspension reason of PAYMENT_OVERDUE.

When the customer pays the overdue invoice, the subscription state returns to ACTIVE and suspension reason and message are set to null. The marketplace triggers a SUBSCRIPTION_NOTICE event notification to the vendor, which contains the notice type REACTIVATED and the new subscription and suspension reason states.

When the customer fails to pay an overdue invoice, the owner can manually cancel the subscription (it does not happen automatically), which triggers a SUBSCRIPTION_CANCEL event notification to the vendor. If the customer does not pay the overdue invoice, the subscription remains in the SUSPENDED state indefinitely.

Modify subscriptions

A customer can modify the items ordered for subscriptions including metered items (where the customer has to choose the number of seats purchased, or some other items at purchase time). The marketplace sends a SUBSCRIPTION_CHANGE event that contains an updated list of the new items to the vendor.

Subscription end of life

The subscription life cycle ends when subscriptions are in the CANCELLED state.

Customers cancel a subscription on their marketplace account. That triggers a SUBSCRIPTION_CANCEL event from the marketplace to notify the vendor, and the subscription is cleared from the customer account and charges stop.