Concepts

Lark models your billing integration using a few key domains that work together to create flexible pricing structures.

Quantity and Usage Events

You always bill your customers for a certain quantity of something (seats, API calls, LLM tokens, etc.). This quantity can either be specified directly upfront or inferred from usage events.

If you bill your customers based on how much they use your product, usage events help you track their activity. A usage event is a simple record representing customer usage activity. For instance, if you provide an API for an LLM that responds to messages, your usage event might look like this:

{
  "event_name": "message",
  "input_tokens": "500",
  "output_tokens": "200",
  "model": "gpt-4",
  "subject_id": "user_123",
  "timestamp": "2025-01-01T00:00:00Z",
  "idempotency_key": "1234567890"
}

In this example,

• event_name defines the type of the event as message
• subject_id identifies the user as user_123
• input_tokens and output_tokens are the number of tokens the LLM processed
• model is the LLM used to generate the response
• timestamp is the time the event occurred
• idempotency_key is a unique identifier for the event to ensure it is only processed once

Reporting usage events to Lark allows you to track and bill your customers based on their usage. Learn more about usage tracking.

Pricing Metric

A pricing metric defines how you aggregate usage events over a service period that gets billed to your customer. For example, you can choose to sum all usage events for a given event_name and bill on that total. You can also define pricing metrics using custom expressions for more complex aggregation logic.

Price

A price defines how you convert a quantity into an amount. For example, if you have a simple fee of $1, a quantity of 10 will translate into a total price of $10.

Lark supports flat fee, tiered, and package prices. Prices can also be defined in custom units (relevant if you use custom credits).

Rates

A rate is an abstraction over price and pricing metrics. It defines how your customer gets charged for specific things. Rates can either be fixed or usage-based.

• Fixed rates are charged upfront in a billing cycle. The quantity is specified upfront.
• Usage-based rates are charged in arrears (i.e. at the end of the billing cycle) based on the quantity from a pricing metric. Usage-based rates can also specify an included quantity (i.e. the quantity that is included for free).

Rate Card

A collection of rates makes up a rate card. You also specify the billing interval on the rate card (monthly, yearly, etc.).

Subscription

A customer subscribes to a rate card using a subscription. The subscription can have scheduled changes that make it easy to support free trials and other changes.