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:

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

In this example,

• event_name defines the type of the event as message
• subject_id identifies the user to attribute the usage to. This can be the user’s ID in your system or the subject ID created by Lark.
• timestamp is the time the event occurred
• idempotency_key is a unique identifier for the event to ensure it is only processed once
• data contains the values that are used to aggregate the usage. The fields in data are defined by the pricing metrics you create.
• data.input_tokens and data.output_tokens are the number of tokens the LLM processed
• data.model is the LLM used to generate the response

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 defines how your customer gets charged for specific items. Rates can either be fixed or usage-based.

• Fixed rates are charged upfront in a billing cycle. The quantity is specified upfront.
  • For example, you can use a fixed rate to bill your customer $10 per month for a seat.
• 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).
  • For example, you can use a usage-based rate to bill your customer $0.10 per API call with 100 API calls 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.