Billforward FAQs
Subscription
Back to home

Subscriptions Overview

Subscriptions define the schedule, price and how a customer is charged. For example a customer may be billed monthly for a private e-mail address.

When defining a subscription we should consider:

  • What price to charge
  • Quantities purchased
  • Billing schedule
  • How payment is made
  • Subscription completion
Subscription API documentation

Price

When a subscription is created a rate-plan is specified. The rate-plan defines pricing via its components. Each pricing-component generates a charge at the start of a new billing period and in-turn these charges become invoice lines. Thus the rate-plan associated with the subscription defines the price calculation.

For example:
The rate-plan may have a pricing component called Widgets which is priced at $5.00 a widget.

Quantity

Every time the subscription enters a new billing period the charges for the subscription are calculated. Each pricing-component from the rate-plan takes a value to calculate a price. This value is associated with the subscription and known as the pricing-component-value. If no value is set on the subscription the default value of the pricing-component is used.

For example:
A customer may have purchased five widgets. Given our earlier pricing definition of Widgets a charge of

$5.00 * 5 widgets = $25.00

would be created each billing cycle.

Schedule

A schedule defines when and how often the subscriptions billing cycle lasts for. The schedule is defined using a duration and billing period dates.

Duration

In a similar manner to pricing the duration of the billing period is also defined on the rate-plan. Billing frequency can range from a single minute to multiple years.

For example:
A subscription has a rate-plan which defines a one month duration.

Dates

There are two key dates when understanding the schedule of a subscription;

  1. When did the current billing period start
  2. When will the next billing period start

Billing periods are contiguous, meaning when one ends another one starts, thus the start of the next billing period can be thought of as the end of the current billing period.

Each time a new billing period is entered the end of the departing period becomes the start of the new period and the Duration is added to this date.

These dates are well defined and precise to the second. This well defined nature allows reasoning to be performed around proration, scheduling changes and aligning billing periods.

For example:
Given our earlier monthly duration.

If the subscription starts on exactly 4:29 am of October 21st, 2015, thus currently:

    current period start : 4:29 am, October  21st, 2015
    current period end   : 4:29 am, November 21st, 2015

At midnight on the November 21st the bill period would change and:

    current period start : 4:29 am, November  21st, 2015
    current period end   : 4:29 am, December  21st, 2015

Payment

At the end of a period and once all the charges have been calculated an invoice is generated. This invoice has a total invoice cost, which is simply the sum of all the charges. It is this cost that must be met via payment for the invoice and subsequently the subscription to be designated as Paid.

Completion

Invoices will stop being automatically issued when certain conditions are met.

  1. Subscription canceled
  2. Payment Failure

Subscription State

When a subscription is defined it is initially in a provisioned state. The Provisioned state allows alteration of the subscription, for example setting a specific start date or changing the units of measure. When a subscription leaves the provisioned state it enters the Trial or AwaitingPayment state. Whilst in Trial state invoices are generated with the full cost, but this cost is offset by automatically generated credit-notes. This allows correct accounting and cost tracking to be performed – you can see the theoretical loss of issuing trial periods! If a subscription goes straight to the AwaitingPayment state the same value invoice is generated as a Trial but no Credit-Notes are generated, thus the invoice must be paid. The initial subscription invoice is a special case, where only a single execution is attempted. If this execution attempt succeeds the subscription is set to a paid state.

A subscription can either end naturally, for example a fixed term subscription comes to an end and the subscription does not continue, this is marked as an expired subscription. Failed subscriptions are those which have ended with one of more unpaid invoices. A cancelled invoice is one which has been cancelled by administrator or user.

Subscription Dates

A subscription has a number of key dates associated with it. The start of a subscription is defined by two dates, the Effective Start Date and the Actual Start Date. The effective start is the date that subscription began regardless of if the subscription began as a trial or non-trial. The actual start date represents the date the subscription entered a non-trial. In the case when no trial exists these periods will be the same date. The effective and start date are automatically calculated when a subscription is taken out based on any trial period defined on a product. The effective and actual start dates can be explicitly defined when creating a subscription. This is useful in the case when you want to offer a trial period on a product which does not have one explicitly defined or two lengthen or shorten a subscriptions trial period. The current period end explicit option can be used to define an absolute time to align the subscription to a particular time of day. For example it can be used to align the end time of the subscription to 19:00 UTC no matter the start time.

Whilst a subscription is active the current period start and current period end is updated to represent the state of the subscription. The time betweens these two dates is the period defined in the product. When a subscription moves from one period to another the start and end time are updated, with the start time becoming the previous end time.

When a subscription ends the subscriptionEnd value is set. This is an indication of when the service should end for that subscription. When a subscription is set to expire at the end of the current period the service end is equivalent to the currentPeriodEnd, in the case when a subscription is cancelled immediately the value is set to the time at which the immediate cancellation is executed.

Evergreen Subscriptions

Software as a service (SaaS) and other subscription businesses often choose to offer evergreen subscriptions. With evergreen subscriptions the choice is given to the customer to cancel at any point. Services such as ZenPayroll or Olark rely on evergreen subscriptions for it’s customer enablement and flexibility

Fixed-Term Subscriptions

Fixed term subscriptions form a contract with a customer that the service will be provided for a minimum period. This lock-in offers a number of advantages and downsides over evergreen subscriptions. With fixed-term the customer is obligated to pay for the fixed-term period, this means they can not suspend the service, with this deterministic income it is possible for the service provider to offer discounts. At the end of the fixed term the subscription can either enter a new fixed term, expire, become evergreen.

Terminology

Here are some of the key concepts to understand when using charge models:

  • Anniversary This is the date on which the current subscription period began.
  • Duration The time period a subscription will last for before either renewing or automatically cancelling
  • Renewal Date This is the date that the subscription will renew on
  • Termed and Evergreen Evergreen subscriptions renew until cancelled. Termed subscriptions cancel after a certain period of time.

Fixed-Term and Evergreen Subscriptions

The type setting defines the number of periods a subscription will last for. Fixed-Term subscriptions represent a subscription which has a set number of periods, and locks the customer into the pricing at time of purchase. Evergreen subscriptions are represented by the Evergreen type, these subscriptions recur indefinitely until cancelled.

  • Fixed-Term subscriptions have a pre-defined start and end date. At the end of the initial fixed termed the subscription can enter a subsequent fixed term, cancel, or become evergreen.

  • Evergreen subscriptions automatically renew until cancelled. The default subscription type is Evergreen. The definition of the fixed term can be defined when creating the pricing plan.

Pausing or Cancelling a Subscription

For guidance on how to pause or cancel one of your subscriptions in Billforward, take a look at this short tutorial video.

Was this article helpful?
YesNo