> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperline.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up credit-based billing for an AI platform

> Step-by-step guide to implement a credit system with weighted consumption across multiple AI models

This guide walks you through setting up a complete credit-based billing system in Hyperline, where customers purchase credits and consume them at different rates depending on which AI model they use.

## Context

You run an AI platform that offers access to multiple LLM models with different capabilities and costs. Rather than billing per token for each model separately, you want to sell credit packs that customers can spend across all models — with more powerful models consuming more credits per usage.

Your platform offers three model tiers:

| Model        | Use case                 | Credits per 1,000 tokens |
| ------------ | ------------------------ | ------------------------ |
| `nova-fast`  | Quick tasks, high volume | 1                        |
| `nova-pro`   | Balanced performance     | 4                        |
| `nova-ultra` | Complex reasoning        | 15                       |

A customer with 10,000 credits could use them flexibly: heavy usage of the budget model, occasional use of the premium model, or any combination.

## Prerequisites

Before you begin, make sure you have:

* Access to your Hyperline account (we recommend using [test mode](../docs/getting-started/sandbox) for this setup)
* An [API key](../api-reference/docs/authentication) to send usage events
* A clear understanding of the models you want to bill and their relative cost ratios

<Info>
  When signed up and landed on Hyperline, you can use the [test mode](../docs/getting-started/sandbox) to experiment before going live.
</Info>

## Steps

### 1. Send usage events via the API

Every time a customer uses one of your models, your backend should send a billable event to Hyperline with the model name and the number of tokens consumed.

```sh theme={null}
curl -X POST https://ingest.hyperline.co/v1/events \
  -H "Authorization: Bearer <API key>" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "customer_id": "cus_xxxxxxxxxxxxx",
        "event_type": "llm_token_usage",
        "timestamp": "2026-03-25T14:30:00Z",
        "properties": {
          "model": "nova-pro",
          "tokens": 1500
        }
      }
    ]
  }'
```

Each event should include:

* `customer_id`: the Hyperline customer ID (or `external_id` if you've mapped your internal IDs)
* `event_type`: a consistent name for your token usage events (e.g., `llm_token_usage`)
* `properties.model`: the model identifier used for the request
* `properties.tokens`: the total number of tokens consumed (input + output)

<Tip>
  For testing, you can skip this step and use [simulated events](../docs/usage/simulate-usage-data) directly in test mode to generate fake usage data.
</Tip>

<Note>
  Learn more about event ingestion in our [send usage data guide](../docs/usage/send-usage-data).
</Note>

### 2. Create one aggregator per model

Each model tier needs its own [aggregator](../docs/usage/aggregators) so that Hyperline can track consumption separately and apply a different credit weight to each.

Go to [**Usage > Aggregators**](https://app.hyperline.co/app/events/aggregators) and create three aggregators:

| Aggregator name     | Event type        | Operation | Property | Filter                 |
| ------------------- | ----------------- | --------- | -------- | ---------------------- |
| `nova-fast tokens`  | `llm_token_usage` | Sum       | `tokens` | `model` = `nova-fast`  |
| `nova-pro tokens`   | `llm_token_usage` | Sum       | `tokens` | `model` = `nova-pro`   |
| `nova-ultra tokens` | `llm_token_usage` | Sum       | `tokens` | `model` = `nova-ultra` |

All three aggregators listen to the same `llm_token_usage` event type but use a filter on the `model` property to isolate each model's consumption. The **Sum** operation on `tokens` gives you the total number of tokens consumed per model.

<Card title="Example 💡">
  When a customer sends 3 requests to `nova-pro` consuming 1,200, 800, and 2,000 tokens respectively, the `nova-pro tokens` aggregator reports a total of 4,000 tokens for that period.
</Card>

### 3. Create a credit product with weighted aggregators

Now create a credit product that ties all three aggregators together with their respective weights.

<Steps>
  <Step title="Create a new credit product">
    Go to [**Products**](https://app.hyperline.co/app/products), click **New product**, and select **Credit**.
  </Step>

  <Step title="Configure the aggregators and weights">
    In the **Aggregators** section, add the three aggregators you just created and set the weight for each:

    | Aggregator          | Weight |
    | ------------------- | ------ |
    | `nova-fast tokens`  | 1      |
    | `nova-pro tokens`   | 4      |
    | `nova-ultra tokens` | 15     |

    The weight determines how many credits are consumed per unit of usage. With these weights, 1,000 tokens on `nova-ultra` consumes 15 credits, while the same 1,000 tokens on `nova-fast` consumes only 1 credit.

    <Frame>
      <img src="https://mintcdn.com/hyperline/xf0N3w6isUSqYacy/images/guides/credit-ai-aggregators.png?fit=max&auto=format&n=xf0N3w6isUSqYacy&q=85&s=cee065e2099423cb46bd955b7a9582d0" width="1762" height="1272" data-path="images/guides/credit-ai-aggregators.png" />
    </Frame>
  </Step>

  <Step title="Set up bundle pricing">
    In the **Prices** section, configure your credit packs. For example:

    | Bundle size     | Price   |
    | --------------- | ------- |
    | 10,000 credits  | \$100   |
    | 50,000 credits  | \$400   |
    | 200,000 credits | \$1,200 |

    These bundles will be available for purchase via the customer portal and auto-topup.
  </Step>

  <Step title="Save the product">
    Click **Save** to add the credit product to your catalog.
  </Step>
</Steps>

<Note>
  For more details on multi-aggregator credit products, see the [credits overview](../docs/credits/overview#multiple-aggregators-with-weights).
</Note>

### 4. Set up a credit balance on a customer

With your credit product ready, enable a credit balance on a customer.

<Steps>
  <Step title="Navigate to the customer's Credits tab">
    Go to [**Customers**](https://app.hyperline.co/app/customers), select a customer, and click the **Credits** tab.
  </Step>

  <Step title="Add a credit balance">
    Click **Add credit balance** and select the credit product you created.

    Configure the initial settings:

    * **Starting balance**: the number of credits to grant immediately (e.g., 10,000)
    * **Warning limit**: the threshold at which a low-balance warning appears on the customer portal (e.g., 1,000 credits)
  </Step>
</Steps>

### 5. Add the credit product to a subscription

To automate credit replenishment and invoicing, add the credit product to a subscription.

<Steps>
  <Step title="Create or update a subscription">
    From the customer's page, click **Actions** > **Assign new subscription**, or open an existing subscription.
  </Step>

  <Step title="Add the credit product">
    Click **Add product**, select your credit product, and choose a bundle pricing tier.
  </Step>

  <Step title="Configure auto-topup (optional)">
    To ensure your customer never runs out of credits, configure auto-topup on their credit balance:

    * **Threshold**: when the balance drops below this number, auto-topup triggers (e.g., 500 credits)
    * **Amount**: how many credits to add (e.g., 10,000)
    * **Pricing**: select a bundle price or set a custom amount

    Auto-topup automatically creates an invoice, charges the customer's payment method, and adds credits to their balance.
  </Step>
</Steps>

<Warning>
  Auto-topup requires the customer to have a valid payment method on file. If the payment fails, the topup will not be processed.
</Warning>

### 6. Monitor consumption

Once the customer starts using your models, you can track credit consumption from the customer's **Credits** tab.

The **credits chart** shows balance evolution over time. Use the date range and granularity controls (day, week, month) to analyze consumption patterns.

<Frame>
  <img src="https://mintcdn.com/hyperline/xf0N3w6isUSqYacy/images/guides/credit-ai-balance.png?fit=max&auto=format&n=xf0N3w6isUSqYacy&q=85&s=af7f2acafaacad70d30f06e8579d0675" width="1680" height="806" data-path="images/guides/credit-ai-balance.png" />
</Frame>

Click **All transactions** to view the full **transactions table**, which lists every credit movement — top-ups, usage deductions, and expirations. For multi-aggregator products, an **Aggregator** column shows which model triggered each usage transaction. Click **Explore** on any usage transaction to inspect and export the underlying consumption events.

<Frame>
  <img src="https://mintcdn.com/hyperline/xf0N3w6isUSqYacy/images/guides/credit-ai-transactions.png?fit=max&auto=format&n=xf0N3w6isUSqYacy&q=85&s=36dceb3870212e74b3084ab43b5212ea" width="2480" height="874" data-path="images/guides/credit-ai-transactions.png" />
</Frame>

<Card title="Example 💡">
  A customer starts the month with 10,000 credits. They make:

  * 2,000 `nova-fast` calls averaging 1,000 tokens each → 2,000 x 1 = **2,000 credits**
  * 300 `nova-pro` calls averaging 1,500 tokens each → 450 x 4 = **1,800 credits**
  * 50 `nova-ultra` calls averaging 2,000 tokens each → 100 x 15 = **1,500 credits**

  Total consumption: **5,300 credits**. Remaining balance: **4,700 credits**.

  The transactions table shows each deduction tagged with the corresponding aggregator, so you can see exactly which model is driving consumption.
</Card>

## Next steps

<CardGroup cols={2}>
  <Card title="Credits overview" icon="layer-group" href="../docs/credits/overview">
    Learn more about credit products and configuration options
  </Card>

  <Card title="Credit expiration" icon="clock" href="../docs/credits/overview#credit-expiration">
    Configure credits to expire after a set period or at the end of each billing cycle
  </Card>

  <Card title="Customer portal" icon="user" href="../docs/customers/portal">
    Let customers view their balance and purchase credits from the portal
  </Card>

  <Card title="Credits API" icon="code" href="../api-reference/endpoints/customers->-credits/list-credit-products">
    Manage credits programmatically via the API
  </Card>
</CardGroup>

<Info>
  Is something still unclear? Don't hesitate to reach out to our team via the in-app chat if you need additional support.
</Info>