Best practices for monthly usage resets with annual plans

[marckohlbrugge]

Many SaaS services have usage limits or credits that reset each month. When the customer is subscribed to a monthly plan, these monthly usage resets are easy to implement as we can simply listen for one of the monthly payment hooks our payment processor sends.

But what if the customer subscribes to an annual plan?

In many cases, you still want to run certain code like credit resets each month. But now we cannot rely on payment processor posting to our webhook each month at the right time.

What's a good approach to solve this issue?

Here's my current thinking:

1. Create a Billing::UsagePeriod (belongs_to :user, belongs_to :pay_subscription, starts_at:datetime, ends_at:datetime) model which represents a single month of a user's usage.
2. Extract all current "monthly usage reset" logic from the invoice.paid webhook to Billing::UsagePeriod with an after_create_commit callback that takes care of resetting the usage, issuing new credits, etc.
3. Anytime the invoice.paid webhook is called, create a new Billing::UsagePeriod
4. Run a daily/hourly cronjob that finds all relevant annual subscriptions (see below), and creates a Billing::UsagePeriod record

The hard part is finding the relevant subscriptions. The first billing period is already taken care of by our regular invoice.paid webhook for monthly payments.

So we'll need to find subscriptions that are still status = active, and their most recent Billing::UsagePeriod has an ends_at that's in the past.

For example

class Billing::UsagePeriod < ApplicationRecord
  belongs_to :user
  belongs_to :pay_subscription, class_name: "Pay::Subscription"

  validates :starts_at, presence: true, uniqueness: { scope: :pay_subscription_id }
  validates :ends_at, presence: true, uniqueness: { scope: :pay_subscription_id }
  validate :start_before_end

  after_create_commit :reset_usage

  private

  def reset_usage
    # Your logic here
  end

  def start_before_end
    return if starts_at.blank? || ends_at.blank?

    errors.add(:ends_at, "must be after the start date") if ends_at <= starts_at
  end
end

# Run the following in a frequent cron job (e.g. every hour)

# NOTE: Can this be done in a nicer way?
active_yearly_subscriptions = Pay::Subscription.active.where("current_period_end - current_period_start > '32 days'::interval")

# NOTE: This will NOT return subscriptions that have just started (because they don't have a Billing::UsagePeriod yet), but those are taken care of by our `invoice.paid` webhook that's called upon subscription creation.
recent_periods = Billing::UsagePeriod
  .select('DISTINCT ON (pay_subscription_id) *')
  .order('pay_subscription_id, ends_at DESC')
  .joins(:pay_subscription)
  .merge(active_yearly_subscriptions)

ended_recent_periods = recent_periods.where('ends_at < ?', Time.current)

ended_recent_periods do |previous_period|
  # Using previous_period dates as base (instead of Time.current) to prevent "drift"
  Billing::UsagePeriod.create(user: period.user, pay_subscription: previous_period.pay_subscription, starts_at: previous_period.starts_at + 1.month, ends_at: period.ends_at + 1.month)
end

What do you think of this approach? Are the other best practices to consider?

[excid3]

This is pretty close to what we do with metered billing for Hatchbox. We have a job that runs every few hours and records usage since the last update.

Running every hour will be good for distributing credits throughout the day whenever someone had purchased which is good. And if cron didn't run for some reason, you'd be able to catch it in the next hour and their credits would only be behind a short bit.

I wish that Stripe was able to take care of this for us and send webhooks monthly for annual plans!

[marckohlbrugge]

Re: monthly Stripe webhooks for annual plans:

Some people use a bit of a workaround where they subscribe annual customers to a second, $0/mo plan.

This will then fire the monthly hook as expected.

The downside, I believe, is that it requires some code to keep things in sync and I’m not sure if this $0/mo subscription will show up in places like the Billing Portal which could get confusing.

[excid3]

Clever hack, but definitely would require worth to keep it in sync. I'd probably stick to the Cron.