Subscriptions

Subscriptions are handled via Stripe.

While seeding the application, three plans must be created both in the database and on Stripe:

1. Free
2. Growth
3. Business

Architecture

Plan

A Plan maps to a Stripe plan.

Customer

An Organization maps to a Stripe customer.

Card

An Organization::Card corresponds to the latest customer's Stripe source, which is a Stripe card.

Subscription

A Subscription maps to a Stripe subscription. A Subscription is associated to a single Bot, allowing each bot to be billed separately, and to be on different plans.

Invoice

An Invoice maps to a Stripe invoice.

Use cases

Registration

1. A user creates an account and an Organization via the RegistrationsController

2. A Stripe customer is created for the Organization

3. A Bot is created for the Organization

   3.1 With a free plan

   • If the plan param is free, then the plan is fetched and associated with the bot's Subscription right away. Failing to provide a plan_id will fallback to the free plan.

   3.2 With a paying plan

   • If a plan other than free is passed in the params, the user is redirected to the cards#new controller action
   • The user is prompted to enter a credit card, which will be associated to his Organization. A Subscription will be created with the given plan and bot passed in the params.

Subscription creation

When a subscription is created Stripe will:

1. Create an invoice
2. Pay the invoice
3. Close the invoice

Subscription renewal

When a subscription is automatically renewed Stripe will:

1. Create an invoice
2. Leave the invoice open for an hour
3. Pay the invoice
4. Close the invoice

During that hour window we add additional charges to the open invoice. Recurring costs are charged upfront and usage based fees are added to the next month's charges.

Card creation

Users registered with a free account are able to add a credit card to their Organization. That could be useful when they plan to switch to a paying subscription.

Users starting an account with a paying plan will see the card as already set, and can choose to update it later.

Subscription update

When a user on a free plan changes for a paying plan, he can select the new plan and will be asked to enter a credit card if his Organization doesn't already have one.

When a user on a paying plan changes for another paying plan, the subscription is simply updated with the new plan.

Lifecycle events

These are the Stripe events the application listens to.

Customer

customer.created

Update Organization with Stripe attributes

customer.updated

Update Organization with Stripe attributes

Source

customer.source.created

Update Organization::Card with Stripe attributes

customer.source.updated

Update Organization::Card with Stripe attributes

customer.source.deleted

Nullify Organization::Card

Subscription

customer.subscription.created

Update Subscription with Stripe attributes

customer.subscription.updated

Update Subscription with Stripe attributes

customer.subscription.deleted

Update Subscription with Stripe attributes

Invoice

invoice.created

Create Invoice with Stripe attributes. If the invoice's subscription plan requires additional charges, Stripe Invoice Items are added accordingly.

invoice.updated

Update Invoice with Stripe attributes

invoice.payment_succeeded

Update Invoice with Stripe attributes