Subscription Management

This page describes how Subscription Management works in Frappe Cloud.

DocTypes

These are the key doctypes that are related to subscription:

1. Plan: List of plans
2. Subscription: Record of active subscriptions
3. Usage Record: Record of usage on a date
4. Invoice: Document that collects all usage records and creates a Stripe invoice at the end of the month
5. Balance Transaction: Document that keeps track of credits (Free Credits, Prepaid Credits, Transferred Credits)
6. Site: Site that is charged

Example scenario:

John registers on frappecloud.com with the email john@doe.com on 5 January, 2021. A Team record will be created with the name john@doe.com and a Stripe customer record will also be created and linked to this Team record.

Now, he completes the onboarding steps, which involves adding their card for future billing. This card is added directly on Stripe. On adding a card, he also gets a free $25 credit. A Balance Transaction of amount +$25 is created to track this.

Now, he creates a site called tennismart.frappe.cloud on the $10 plan.

• A site record of tennismart.frappe.cloud will be created.
• A subscription record saying that this site is on $10 plan will be created.

Frappe Cloud charges you based on how many active sites you have per day. So, the per day charge of an active site is $10 / 31 = $0.32. We divide by 31 since that is the total number of days in January.

Now, the site is active for 5 days. The total usage amount will $0.32 * 5 = $1.6.

This is how it will look in the invoice:

Now, John decides to upgrade the plan to $25 because he needs more CPU time for the kind of tasks he is running on his site. The plan in the Subscription record will be updated to $25 and now for each day his site is active $25 / 31 = $0.8 will be charged.

This is how it will look in the invoice:

Now, John creates another site cafelegals.frappe.cloud on the $50 plan. After 10 days of usage, this is how his invoice will look:

Now, John deletes the site cafelegals.frappe.cloud because he doesn't have any use for it. Frappe Cloud will stop charging for the site. After 2 days, this is how his invoice will look:

If you notice, only the usage for tennismart.frappe.cloud was updated.

Now, let's fast forward to the end of the month on 31 January, 2021. This is how his invoice will look like:

Notice that since he started using the Frappe Cloud service from 5 January, he was only charged from that day.

Now, at 6pm IST his invoice will be finalized with the total usage amount $35.3. But he already has a $25 credit. So, the total amount due is $35.3 - $25 = $10.3.

A Stripe invoice will be created with the amount $10.3 and his card will be charged. A new invoice will be created for the upcoming month of February.

Scheduler Events

subscription.create_usage_records (hourly_long)

This job runs hourly and creates a Usage Record for every active Subscription. It will not create more than one record per day for one Subscription even if it runs hourly. This is to minimize abuse of our service in the scenario where someone creates a site in the morning and deletes in the night only to create it in the morning again.

Now, for every Usage Record that is created, the amount is updated in the corresponding invoice for that month. For e.g., if a Usage Record of $0.32 is created in the month of January, the amount will updated in the January invoice.

invoice.finalize_draft_invoices (Daily at 6pm IST)

This job runs every day at 6pm IST. It will go through every Draft Invoice whose periodend date has ended (today or before) and has a total amount greater than 0. When an invoice is finalized, credits are applied first if any, and then if the amountdue is greater than 0 a Stripe invoice is created.

After a Stripe invoice is created, Stripe will initiate the charge after one hour of invoice creation. This means if the invoice was created at 6pm, Stripe will charge the card at 7pm.

Stripe will send a webhook for the payment status. If the payment was successful, the Invoice status will be changed to Paid. If the payment was unsuccessful, the Invoice status will be changed to Unpaid. Stripe will attempt the charge for 3 more times.