Ledger

#What is a ledger?

The Ledger is a record of usage transactions. You can grant usage credits to a subject. Subjects burn down credits in real time based on metered consumption. You can also enforce usage quotas and rate limits based on the real-time balance of the subject or check the history of usage transactions.

#Examples

Examples require to creation of a meter and a feature first:

1. Create a meter to measure the usage of the GPT-4 tokens.
2. Create a feature called GPT-4 Tokens.

#Enforcing Monthly Limit

Imagine you are an AI company that provides a plan with a monthly usage limit of 10,000 GPT-4 tokens. You can use the Ledger to grant 10,000 GPT-4 tokens to the subject at the beginning of the month in a couple of steps:

1. Grant credit of 10,000 GPT-4 tokens to the subject with a full amount rollover configuration.
2. The subject burns down the granted tokens based on the metered usage.
3. You can read the ledger balance to enforce the monthly usage limit.
4. At the end of the month, you can reset the ledger balance and re-grant tokens

#Prepaid Billing and Wallets

Imagine you are an AI company that sells prepaid GPT-4 tokens. You can use the Ledger to grant tokens at the time of purchase and rollover the unused tokens to the next period in a couple of steps:

1. Grant credit at the time of purchase with a remaining amount rollover configuration.
2. The subject burns down the granted tokens based on the metered usage.
3. You can read the ledger balance to check the remaining tokens and prompt for top-up.

#Ledger Operations

The following operations are supported by the Ledger:

#Grant Credit

You can grant credits to a subject. The credits can be granted with an effective date, expiration date, priority and rollover configuration.

#Burn Down Credit

The subject burns down credits based on the metered usage in real time. The usage is deducted from the credit balance.

#Void Grant

You can void unused grants. Partially or fully used credits cannot be voided. The credits granted to the subject will be removed from the balance and the grant will be marked as voided. Voided credits don't roll over to the next period.

#Ledger Reset

You can reset the ledger balance of a subject. The balance will be set to zero then all the non-expired grants with rollover will be re-granted.

#Balance

The balance of a subject is the sum of all the credits granted to the subject minus the usage burned down by the subject. The balance can be negative if the subject has burned down more credits than granted.

Balances are per feature and calculated in real-time based on the usage of the subject.

#History

The history of a subject is the list of all the usage transactions of the subject. The history includes the grants, burns, voids, and resets of the subject for a given period.

#When to reset the ledger?

We recommend resetting the ledger balance at the beginning of the billing period. You can reset the ledger using the webhooks of your billing system or manually. The ledger reset will re-grant the unused credits of the subject with rollover configuration.