Subscription lifecycle

This topic describes vendor integration events—notifications sent to your integration endpoints when subscription status changes. For customer email and SMS notifications (for example, End of Contract reminders sent to the product owner), see Manage notifications v2.

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—Customers cannot use the subscription until the underlying issue is resolved. 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.

Integration event quick reference

The following table summarizes common lifecycle moments and the integration events vendors receive. For notice type details, see Subscription notice.

Lifecycle moment	Integration event	Notice type (if applicable)	Typical timing
New subscription	SUBSCRIPTION_ORDER	—	At purchase
Subscription updated	SUBSCRIPTION_CHANGE	—	When the customer or an agent changes the subscription
Customer cancels	SUBSCRIPTION_CANCEL	—	At cancellation
Upcoming invoice (usage reporting)	SUBSCRIPTION_NOTICE	UPCOMING_INVOICE	About 21 hours before the invoice run that includes the subscription (requires Enable upcoming invoice notification on Edit integration)
Payment overdue or account deactivated	SUBSCRIPTION_NOTICE	DEACTIVATED	When status changes to SUSPENDED or FREE_TRIAL_EXPIRED
Overdue payment resolved	SUBSCRIPTION_NOTICE	REACTIVATED	When status returns to ACTIVE or FREE_TRIAL
Subscription closed	SUBSCRIPTION_NOTICE	CLOSED	When status changes to CANCELLED after deactivation

📝 Note: UPCOMING_INVOICE is tied to the billing cycle, not necessarily to contract expiry. For a subscription with monthly billing on an annual contract, the notice can fire before each monthly invoice—not once at a fixed number of days before the contract end date.

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 notice type. The user can continue to use the subscription until the free trial period is over, at which point they begin to be invoiced.
  • In some update flows, a SUBSCRIPTION_CHANGE event occurs without a corresponding SUBSCRIPTION_NOTICE 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 event 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 notice type. The user can continue to use the subscription until the free trial period is over, at which point they begin to be invoiced.

Contract end and renewal

Subscriptions with contract terms follow additional lifecycle paths at the end of the contract period. Contract settings (auto-renewal, end-of-contract grace period, and cancellation period limit) are copied to the subscription when it is created and remain in effect until the subscription changes or ends.

Auto-renewal enabled

When a contract auto-renews at the end of its term:

• If the subscription renews on the same pricing plan, the existing purchase order is updated with the new contract end date. An END_OF_CONTRACT_MIGRATION purchase order is not created. A vendor integration event may not be triggered unless another change occurs (for example, a scheduled price change). See Purchase order types for how order types map to the API.
• If the subscription renews on a different pricing plan, an END_OF_CONTRACT_MIGRATION purchase order is created and a SUBSCRIPTION_CHANGE event can notify the vendor of the updated subscription.

Before each applicable invoice run, vendors who enable Enable upcoming invoice notification on the product's Edit integration page can receive a SUBSCRIPTION_NOTICE event with notice type UPCOMING_INVOICE. This notice fires about 21 hours before the invoice run—not at a fixed number of days before contract expiry. For annual or longer billing frequencies (YEARLY, TWO_YEARS, THREE_YEARS), the notice aligns with that billing cycle. For monthly billing on an annual contract, the notice can fire before each monthly invoice.

Auto-renewal disabled or renewal fails

When a contract ends and is not renewed:

1. The subscription enters the end-of-contract grace period with status SUSPENDED. The marketplace triggers a SUBSCRIPTION_NOTICE event with notice type DEACTIVATED.
2. If the grace period expires without renewal, the subscription status changes to CANCELLED and the marketplace triggers a SUBSCRIPTION_NOTICE event with notice type CLOSED.

If contract renewal fails (for example, payment failure at renewal), the subscription status changes to SUSPENDED and the marketplace triggers a SUBSCRIPTION_NOTICE event with notice type DEACTIVATED.

For status definitions, see Order and subscription statuses.

Which notification fires when a subscription is within 30 days of expiry?

Readers often ask which notification is triggered when an annual or longer subscription is within 30 days of contract expiry. The answer depends on the notification type:

Notification type	What fires near contract expiry
Vendor integration event	No integration event is documented at a fixed 30-day mark before contract expiry. SUBSCRIPTION_NOTICE with notice type UPCOMING_INVOICE fires about 21 hours before each applicable invoice run (see above). Status-change notices (DEACTIVATED, CLOSED) fire when the contract ends or grace period expires—not 30 days in advance.
Customer email (v2)	The End of Contract notification type can email the product owner that a contract is approaching expiration. Reminder timing uses the {REMINDER_DAYS} parameter and is configured in the notification template. See Manage notifications v2 and Parameter descriptions.
Cancellation period limit	If configured on the contract, this setting defines how many days before contract end a customer must cancel to prevent auto-renewal. It is a contract rule, not a vendor integration event. See Contracts.

To test UPCOMING_INVOICE delivery from Account Details, see Test subscription integration from Account Details.

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.

Subscriptions can reach CANCELLED in several ways:

• Customer or agent cancellation—The customer or an authorized agent cancels the subscription on the 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.
• Contract grace period expires—When auto-renewal is disabled and the end-of-contract grace period ends without renewal, the subscription status changes to CANCELLED. The marketplace triggers a SUBSCRIPTION_NOTICE event with notice type CLOSED before or as part of this transition. See Contract end and renewal above.
• Free trial grace period expires—When a free trial ends and the free trial grace period expires without conversion to a paid subscription, the subscription status changes to CANCELLED and a SUBSCRIPTION_NOTICE event with notice type CLOSED is sent. See Free trial support above.