Usage billing (coming soon)

Introduction

Usage-based billing allows you to charge customers based on their actual usage of your product or service. This model is ideal for businesses that offer services where consumption can vary significantly between customers. This flexible model is ideal for SaaS companies, cloud services, and any business where usage can be easily measured.

The usage-based billing process typically involves the following steps:

1. Create a meter: Set up a meter to track and aggregate usage data.
2. Add meter to a plan or fee: Associate the meter with a plan or fee to define how usage will be billed.
3. Record usage: Your application sends usage events to Billingrails.
4. Usage aggregation: Billingrails aggregates the usage data over a specified period.
5. Billing: At the end of the billing cycle, customers are billed based on their aggregated usage.
6. Invoicing: Usage charges are added to customers' invoices for the billing period.

Events

Events are the building blocks of usage tracking. They represent individual actions or occurrences that you want to monitor and analyze. Each event can have associated properties that provide additional context about the action. Some examples of events include:

• Song played
• Message sent
• File upload
• API call

You must record usage events in Billingrails to make sure you bill your customers the correct amounts each billing period. Events can be sent using the Events API. Here is an example of an event:

{
  "event_name": "Song played",
  "properties": {
    "song_id": "12345",
    "artist": "The Beatles",
    "album": "Abbey Road",
    "duration": 240,
    "billingrails_account_id": "acct_67890"
  },
  "idempotency_key": "unique_event_id_12345",
  "timestamp": "2023-10-01T12:00:00Z"
}

Idempotency

By using an idempotency_key, you can ensure that the same event is not recorded multiple times. This is particularly useful in scenarios where network issues might cause retries. The idempotency_key should be a unique identifier for each event, such as a UUID or a combination of event attributes. If you don't provide an idempotency_key, the server will generate one for you, but it's recommended to supply your own to avoid duplicates.

Event timestamp

The timestamp field is used to specify when the event occurred. If not provided, the server will use the current time.

Batching events

You can send multiple events in a single API request by batching them together. This can help reduce the number of network requests and improve performance. When batching events:

• Make sure to include an idempotency_key for each event to ensure they are processed correctly.
• The maximum number of events that can be sent per batch is 100.
• If any event in the batch is invalid, the entire batch will be rejected to maintain data integrity.

Meters

Meters define how events are aggregated and filtered. For example:

• A "calls" meter that counts the number of calls made by a user.
• A "messages" meter that sums the total number of messages sent by a user.

Meters can be attached to plans or fees to form the basis of what's billed or attached to features to measure entitlement usage. Each meter can have multiple profiles, each with its own aggregation type and filtering criteria.

Meter profiles

Meter profiles allow you to define different ways to aggregate and filter the same event type in a single meter. For example, you might have a "local calls" meter profile that counts the number of local calls made by a user, and an "international calls" meter profile that counts the number of international calls made by a user. Each profile will have its own aggregation type and filtering criteria but will share the same event type from the meter.

Aggregation types

Billingrails allows various aggregations, making it suitable for a wide range of applications.

• Sum: The total sum of a numeric property associated with an event. For example, summing the total duration of calls.
• Count: The total number of occurrences of an event. For example, counting the number of messages sent.
• Count unique: The number of unique occurrences of an event based on a specific event property. For example, counting the number of unique users who sent messages.
• Max: The maximum value of a numeric property associated with an event. For example, finding the longest duration of a call.
• Min: The minimum value of a numeric property associated with an event. For example, finding the shortest duration of a call.
• Latest: The most recent value of a property associated with an event. For example, tracking the latest storage usage.

Filters

Meters can filter events based on their properties. This allows you to create more specific meters that only count certain types of events. For example, you might have a meter that only counts events where the country property is set to USA. Here's an example of a filter:

{
  "value": "USA",
  "operator": "in",
  "property": ["country"]
}