Track usage for billing

Track feature usage for usage-based billing with the featureUsageCreate mutation, and choose Sum, Max, Last or Average usage calculation for each billing period.

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 calculationsLink to Usage calculations section

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. A record counts towards the billing period that its usageAt falls in.

• Sum - The billing process will take a sum of quantity values for all feature usage records in the billing period.
• Max - The billing process will take the maximum quantity value from all feature usage records in the billing period.
• Last - The billing process will take the quantity value of the record with the latest usageAt in the billing period.
• Average - The billing process will take the average quantity value of all feature usage records in the billing period.

PrerequisitesLink to Prerequisites section

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.
   \&#xNAN;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 recordLink to Create a feature usage record section

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

{
  "attributes": {
    "quantity": 1,
    "usageAt": "2018-10-21T11:53:12Z",
    "subscriptionId": 123456,
    "featureCode": "users"
  }
}

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

response = BunnyApp::FeatureUsage.create(
  quantity: 5,
  feature_code: 'users',
  subscription_id: 123456,
  usage_at: '2022-03-10'
)

let featureCode = 'sms'
let quantity = 25
let usageAt = '2018-10-21T11:53:12Z'
let subscriptionId = '123456'

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

Rules for usage recordsLink to Rules for usage records section

• The subscription must be active, trial or pending. Usage for a canceled or expired subscription is rejected.
• For active and trial subscriptions, usageAt must fall within the subscription: on or after its start date (its trial start date during a trial) and on or before its end date. Set overrideUsageAtLimit to true to record usage outside those dates.
• usageAt is read as a date and time in the timezone of the subscription’s entity, and any UTC offset you send is ignored. For example, 2026-03-31T23:30:00Z is recorded as 11:30 PM on March 31 in the entity’s timezone, whatever that is in UTC.