Use the Treefort subscription POST endpoint to create subscriptions and the Treefort subscription PATCH endpoint to update subscriptions. A user’s subscription state is determined by four properties on the user’s subscription: deactivatedAt, canceledAt, currentPeriodEndsAt, and trialEndsAt.
A user has access to content through their subscription as long the deactivatedAt property is null and loses access as soon as deactivatedAt is set to a date. The canceledAt property should be null if the user is planning to renew their subscription and should be set to the current date if they request to cancel their subscription. The currentPeriodEndsAt property should be set to the last day in the subscription’s billing period that the user has paid for. If the user is on a free trial then trialEndsAt should be set to the last day in the free trial, otherwise it should be null. If your implementation is correct then for healthy, renewing subscriptions canceledAt and deactivatedAt will be null and currentPeriodEndsAt will always be a future date.
In almost all cases changes to Web Payment subscription state will only occur as a result of you calling the Treefort API subscription POST or PATCH endpoints. The one exception is that if a subscription’s currentPeriodEndsAt date is more days in the past than the grace period you specify in the responses from your subscription plan endpoint, we will automatically set deactivatedAt to the current date, putting the subscription into the lapsed state.
🚧 We do not recommend create subscriptions in a deactivated state. These subscriptions will not be usable, but you will still be billed for them in the month they were created.
Possible subscription states
If a user has a subscription it can be in one of six different states. You can view in your admin dashboard in the Audience tab if you click the Subscriptions drop down.
canceledWithTimeLeft:
canceledAtis set to a date anddeactivatedAtis null. The user’s subscription has been canceled but they will retain access until the end of the billing period, at which point you should setdeactivatedAtto the current date.canceled:
canceledAtanddeactivatedAtare both set to dates. The user has canceled their subscription and they no longer have access. When the Treefort API sends a request to your API to cancel a user’s subscription, it’s up to you whether to deactivate their subscription immediately or put them in thecanceledWithTimeLeftstate and give them access until the end of the billing period.lapsed: The subscription isn’t in one of the above states and
deactivatedAtis set to a property. Use this state when a user should no longer have access to their subscription for a reason other than voluntary cancellation. For instance, payment failed because of an invalid payment method.freeTrial: The subscription isn’t in one of the above states and
trialEndsAtis set to a future date. Use this state when a user is on a free trial and you don’t plan to bill them until thetrialEndsAtdate.paymentPastDue: The subscription isn’t in one of the above states and
currentPeriodEndsAtis set to a date in the past. Use this state if the user should retain access to their subscription but hasn’t paid for the current billing period. If a subscription remains in thepaymentPastDuestate longer then the grace period you specify in the response from your subscription plan endpoint then Treefort will deactivate the user’s subscription when they attempt to use the app.subscribed: The subscription is not in any of the above states (
canceledAtis null,deactivatedAtis null, andcurrentPeriodEndsAtis a date in the future).
Multiple subscriptions
Whether you rely on the Treefort API or your own internal system to keep track of subscriptions, it’s up to you to prevent users from getting into a state where they have multiple active subscriptions (subscriptions that have deactivatedAt set to null). If the user has multiple active subscriptions they will see a message in the app menu telling them that they have multiple subscriptions and should contact support to resolve the issue.
Subscription state example
In general a healthy subscription flow will look something like the following. If a user subscribes to a $7.99 monthly plan on March 1 then you would bill them for the $7.99 and then call the Treefort API subscription POST endpoint to create the subscription in the Treefort system. In your request body canceledAt would be null, deactivatedAt would be null, and currentPeriodEndsAt would be April 1. When April 1 comes and the user’s subscription renews you would bill them again for $7.99 and call the Treefort API subscription PATCH endpoint to update the subscription’s currentPeriodEndsAt property to May 1, one month in the future. If the user canceled their subscription on April 15 you would call the Treefort API subscription PATCH endpoint to update the subscription’s canceledAt property to the current date, and then when May 1 comes you would call the PATCH endpoint again to set deactivatedAt to the current date. This would give the user access to their subscription for the duration of the billing period they had already paid for and then end their subscription at the end of the billing period.