Track usage for billing

If your product offers a usage based billing component such as monthly active users then you will need a way to track usage and calculate the invoice total at the end of each period.

Bunny provides an API for tracking feature usage and will take care of the billing calculations for you.

Usage calculations

When a usage based charge is added to a price list in Bunny you will need to set the Usage Calculation Type to one of the following values. This will determine how the usage is calculated at billing time.

• Sum - Default. The billing process will take a sum of quantity values for all feature usage records created during the billing period.

• Max - The billing process will take the maximum quantity value from all feature usage records created during the billing period.

• Last - The billing process will take the quantity value of the last feature usage record created during the billing period.

For example, If you wanted to charge based on the number of SMS messages sent during a period then you use the Sum calculation and create a feature usage record for every SMS that is sent. Or, alternatively if you wanted to track monthly active users then you would need to keep note of each tenants billing day from Bunny. You would then do a calculation to find the total users for the period and send this in a single request to Bunny using the Last option.

Prerequisites

Before you can start tracking feature usage from your SaaS application you need to complete the following steps on the Bunny side first.

1. Create an API client & install a Bunny SDK

2. Create a Feature in Bunny with Is Unit enabled. Then create a product plan and price list with a usage based charge using the feature unit. Take note of the code that you set for the feature as you will need that in the next step.

3. Create a subscription based on the plan and price list that you setup in the previous step and take note of the Subscription ID number.

Create a feature usage record

Feature usage is tracked via the featureUsageCreate mutation. If the usageAt attribute is not supplied then it will default to the current datetime.

GraphQL

FeatureUsageAttributes

{
  "attributes": {
    "quantity": 1,
    "usageAt": "2018/10/21 11:53:12 00",
    "subscriptionId": 123456,
    "featureCode": "users"
  }
}

Mutation

mutation featureUsageCreate ($attributes: FeatureUsageAttributes!) {
  featureUsageCreate (attributes: $attributes) {
    errors
  }
}

Ruby

res = BunnyApp::Usage.track(
    quantity: 1,
    usage_at: '2018/10/21 11:53:12 00'.
    feature_code: 'sms', 
    subscription_id: 123456
)

Node.js

let featureCode = 'sms'
let quantity = 25
let usageAt = '2018/10/21 11:53:12 00'
let subscriptionId = 123456

res = await bunny.featureUsageCreate(featureCode, quantity, subscriptionId)

If a billing period has already passed and been processed then setting a historical date for usageAt will not be picked up in the next billing run.