When is subscription expired?

[miuosz]

Hi,

I am doing some paypal subscription integration with my dashaboard however there is too little information about subscription statuses in docs.

According to docs there are 6 different possible subscription statuses.

• APPROVAL_PENDING. The subscription is created but not yet approved by the buyer.
• APPROVED. The buyer has approved the subscription.
• ACTIVE. The subscription is active.
• SUSPENDED. The subscription is suspended.
• CANCELLED. The subscription is cancelled.
• EXPIRED. The subscription is expired.

Everything seems to be clear except EXPIRED one. In my understanding subscription status is changed to expired after it runs out of cycles or it fails to renew or it is cancelled by user but in my case (tried only canceling by user) status is never changed to EXPIRED it stays CANCELLED.

So my question is if I understood EXPIRED status incorrectly or i set up something wrong? I wanted to track subscription status using webhooks but since subscription status stays CANCELLED instead of switching to EXPIRED i do not receive BILLING.SUBSCRIPTION.EXPIRED and I don't know when should I revoke user's permissions.

I know I could run some intervals on my own but EXPIRED webhook/status seems to be more elegant.

[MTS-Aaron]

Hi @miuosz 

This is a great question and I will reach out to our documentation team to see if they can add in some information to the "expired" status description. 

Subscriptions "Expire" when the final payment/cycle is complete and the subscription no longer is taking payments due to all the payments being made. If I purchased a subscription from you for 6 1-month cycles, on the 7th month, I shouldn't be billed and the subscription should show as expired.

I hope that helps!

-Aaron

[miuosz]

Hi @MTS-Aaron ,

Thank you for your quick response.

According to your answer I am not sure if EXPIRED status works only with plans with limited cycles and subscription status is set to EXPIRED after subscription hits end of plan?

Correct me if I am wrong. If I have a plan with total_cycles=0 which means billing can be executed infinite times and if user cancels his subscription it goes into CANCELLED status until time when next payment was supposed to take place(time when subscription ends) and after this next payment date, subscription should be EXPIRED instead of CANCELLED?

In my case above description does not work (tested on sandbox).

1. I created plan with infinite billing cycles and with 1 day frequency.

2. On June 9 I created subscription and activated it, everything went smoothly as expected

3. On june 10 I cancelled this subscription, received hooks, status updated all good

4. On june 11 (end of current billing cycle) nothing changed, subscription is still cancelled, no subscription expired webhook, nothing

[MTS-Aaron · Accepted solution]

Hi @miuosz 

If a customer cancels a plan, the status should remain as cancelled. So, for my explanation, this does not apply to "cancelled" subscriptions. The expired status will not happen if a customer initiated the cancel, the cancelled status will remain just that.

However for "Limited cycle" plans, the expired status will happen if it runs out with no action from the customer or the merchant to cancel. There's not really a way that I know of for the "expired" status to happen for infinite plans. When a plan is cancelled, it is cancelled and it will not change to expired if my understanding is correct.

I hope that helps, but do let me know if you need clarification and I'm working with the documentation team to get the "expiration" status description clarified in our documentation.

-Aaron

[miuosz]

Thank you for clarification @MTS-Aaron, everything is clear now. Lack of documentation made me think that expired is just successor of cancelled. I wanted to track subscription status using this expired status which as I previously understood, would have happened in next billing cycle after customer cancelation, unfortunately as you explained it is not possible.

[NickBettes]

This explanation is clear - "EXPIRED" = no more payments are scheduled, which is a useful trigger to some kind of sales activity.

It does leave the application to deal with the remaining portion of the subscription post last payment though.  Usually there will be a final period before the subscription actually "expires".