> For the complete documentation index, see [llms.txt](https://docs.younium.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.younium.com/platform/credits.md).

# Prepaid Credits and Overage

***

## 1. Overview

Prepaid Credits lets a customer sell credits up front, receive usage reported against them, and bill any usage beyond the credits as overage. A customer buys credits through a **Credits** charge on an order, either once or every billing period. Younium draws reported usage from the credits, shows the remaining balance, and either flags usage that exceeds the credits or bills it monthly in arrears.

Revenue for the prepaid amount is recognised as the credits are consumed, not when the invoice is posted. Credits that expire unused are recognised as breakage at expiry. Customers can buy more credits (a **top-up**) from the self-service portal, the embedded self-service components, the public API, or by changing the order.

Prepaid Credits is available to tenants on which the feature is enabled. It is built on top of orders, invoicing and revenue recognition, which are described in [Orders](https://docs.younium.com/platform/orders.md), [Billing](https://docs.younium.com/platform/billing.md) and [Revenue Recognition](https://docs.younium.com/platform/revenue-recognition.md).

***

## 2. Core Concepts

### Credit type

A credit type defines what is counted, for example API calls or SMS messages. It has a name, a unique code and an optional unit of measure. It also holds the defaults that every Credits charge of that type starts from: expiry, rollover at renewal, low balance alert, overage behaviour, a rate card, and prices per currency for overage and top-ups.

The defaults are copied onto the order charge when the order is created and can be edited there. Changing a credit type afterwards affects new orders only. Credit types are managed under Settings.

### Usage type

A usage type is a kind of action the customer reports, such as an API call or an LLM request. Each has a name and a unique code. Usage types are managed under Settings and are converted to credits through a rate card.

### Credits charge

A Credits charge is a product charge whose charge kind is **Credits**. The product carries the commercial terms: whether credits are granted once or every billing period, the price, and whether a zero-priced grant is shown on the invoice. The quantity of a Credits charge is the number of credits granted each time, for every pricing model (quantity, flat, tiered and volume). The rated pricing model is not available.

The order charge also carries the behaviour copied from the credit type: expiry, rollover, low balance alert and overage behaviour. The revenue recognition rule of a Credits charge is fixed to recognise on consumption.

### Pool

A pool is one grant of credits. It records the credits granted, the remaining balance, the value of each credit, the validity period and whether it came from the original plan or from a top-up. A one-time grant creates one pool, and each top-up adds another. A recurring grant creates one pool per billing period.

| Pool status     | Meaning                                                                                             |
| --------------- | --------------------------------------------------------------------------------------------------- |
| Pending funding | The credits are available but the invoice line that grants them is not yet posted                   |
| Active          | The grant invoice line is posted                                                                    |
| Depleted        | All credits are used                                                                                |
| Expired         | The validity period ended; the unused credits are recognised as breakage                            |
| Forfeited       | The unused credits were written off, for example when the order was cancelled or the charge removed |
| Refunded        | The unused credits were credited back                                                               |
| Withdrawn       | A change order took back every credit before any was used                                           |

The value of each credit is the total price of the grant divided by the number of credits, corrected to the amount on the posted invoice line.

### Wallet

A wallet is the balance of one credit type on one order. It shows the balance, credits granted, credits consumed, unfunded usage, unmatched usage, the low balance threshold and the health of the balance. The order view and the account view show a wallet card for each order.

### Rate card

A rate card converts usage types into credits. Each line gives a whole number of credits per unit of a usage type. A credit type has a default rate card that is copied to the order charge, where it can be overridden. An order has one rate card per credit type, and a usage type belongs to one credit type on an order.

### Credit usage record

A credit usage record is one consumption event sent to Younium. It is reported either in credits, with a credit type and quantity, or per usage type, with a usage type and a quantity of units. In the second case the order's rate card on the usage date gives the credit type and the credits per unit. Records cannot be edited. A correction reverses the record and stores a new one.

| Record status | Meaning                                                              |
| ------------- | -------------------------------------------------------------------- |
| Pending       | Received and not yet processed                                       |
| Allocated     | Drawn from credits                                                   |
| Overflowed    | The part beyond the credits was assigned to overage                  |
| Unfunded      | There were no credits to draw; the usage waits for credits to arrive |
| Reversed      | Cancelled by a reversal or correction                                |
| Unmatched     | The account, order, credit type or usage type could not be resolved  |

> **Note on Credits and the Usage charge type:** A *credit usage record* is the consumption event described here. It is unrelated to the legacy *Usage* charge type.

***

## 3. Selling Credits

### Grant frequency

A Credits charge grants credits once or every billing period. A one-time grant is a one-off charge. A recurring grant is a recurring charge, with a monthly, quarterly or annual billing period, and each period mints a new pool shortly before it starts. A recurring grant cannot use an order-level billing period of end of term or biannual.

### Pricing

The price covers the whole grant. With the quantity model, the price per credit multiplies the number of credits and may be zero. With the flat model, a single fee covers the grant. With tiered and volume pricing, tiers apply over the number of credits. A Credits charge is never split into one invoice line per tier.

A grant with a zero price appears on the invoice only when **Show free grants on invoice** is on. This separates credits that are included in a plan from a goodwill grant.

### Expiry and rollover

| Credit expiry  | Behaviour                                                                                                                                                                                    |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| End of period  | Recurring grants only. Credits expire at the end of the billing period they were granted for, with no rollover                                                                               |
| End of term    | Credits expire when the order term ends. Not available on evergreen orders                                                                                                                   |
| Rolling months | Credits expire the number of months set in **Expire after (months)** after the pool starts: the order start, the effective date of a change order that adds credits, or the date of a top-up |

With **Roll over at renewal** on, credits with an end-of-term expiry move to the new term when the order is renewed. Unused credits that reach their expiry are recognised as breakage.

### Settings

These settings are defined on the credit type, which provides the defaults, and can be edited per order charge.

| Setting                         | Description                                                                                                                             | Default   |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | --------- |
| **Name** and **Code**           | Name and unique code of the credit type                                                                                                 |           |
| **Unit of measure**             | The unit of every Credits charge of the credit type. It is set on the charge automatically and is locked once the credit type is in use | None      |
| **Credit expiry**               | End of period, end of term or rolling months                                                                                            |           |
| **Expire after (months)**       | Months until expiry when the expiry is rolling months                                                                                   |           |
| **Roll over at renewal**        | Moves credits to the new term at renewal                                                                                                |           |
| **Low balance alert**           | Credit balance at which the wallet crosses its threshold and a notification is sent                                                     |           |
| **Overage behavior**            | What happens when the credits run out: flag only, or bill overage                                                                       | Flag only |
| **Unused credits when removed** | Whether unused credits are written off or refunded when a Credits charge is removed and no choice is made                               | Write off |
| **Expiry warning days**         | Days before expiry that an expiry warning is sent                                                                                       |           |
| **Grant frequency**             | Once or every period, set on the product charge                                                                                         |           |
| **Show free grants on invoice** | Shows a zero-priced grant as an invoice line                                                                                            |           |

The credit type also holds the overage price per unit and the top-up price per credit for each currency the legal entity uses. A price in a currency the legal entity does not have is rejected.

***

## 4. Reporting Usage and Drawdown

Usage is reported through the public API, by import, or manually on the order's Wallet tab. Younium accepts every record. A record that cannot be resolved is kept as *Unmatched* with the details that were sent, and can be corrected later. Records are de-duplicated on an external identifier, and a request can carry an idempotency key. The API returns a receipt for each record with the credits drawn and, for usage types, the units and the rate. When usage is processed in the background, the response is accepted and a batch can be followed to see its status, the counts per record status and the records that remain open.

Usage belongs to an order. Younium draws only from that order's pools, earliest expiry first. Matching uses the order number, so a record keeps the order version it was matched to while pools follow the latest version.

Rates apply per usage date. The latest booked order version that is effective on the usage date supplies the rate card. A rate card change is made through a change order and never applies retroactively; a change is refused if per-usage-type usage is already processed on or after its effective date. Changing rates does not re-invoice anything, and the order versions show the rate history.

Drawdown records one entry per usage type per day. A negative usage record is a usage adjustment, entered manually in credits.

### Overflow

Usage beyond the available credits depends on **Overage behavior**.

| Overage behavior | What happens to usage beyond the credits                                                                         |
| ---------------- | ---------------------------------------------------------------------------------------------------------------- |
| Flag only        | The usage is recorded as unfunded, the wallet shows it and a notification is sent. Nothing is billed             |
| Bill overage     | The usage is added to a monthly overage period for the order and billed in arrears at the overage price per unit |

An order has one bill-overage Credits charge per credit type. Overage is always billed monthly in arrears, whatever the billing period of the grant. Unfunded usage is replayed when credits arrive. A one-time grant pool that is usable today, whether the original grant or a top-up, also covers earlier unfunded usage on the order, so the wallet shows what is left after it and the revenue lands in the month of the usage. A recurring grant pool never covers the usage of another period.

Pools are usable from the moment the order is activated, before the grant invoice is posted. Revenue is recognised once the grant line is posted and then catches up.

***

## 5. Top-ups

A top-up adds credits to an existing wallet. It is a change order that adds a one-time Credits charge, copied from the order's original Credits charge for the credit type, priced per credit at the order's top-up price and billed on the next invoice run. A top-up does not carry rate lines, threshold or overage billing of its own, and it takes effect on the day it is made. Its expiry follows the original charge. When the original charge is recurring with expiry at the end of the period, the top-up expires after one billing period.

A top-up needs a top-up price in the order's currency. There is no fallback to the plan price. A top-up made from the portal, the embedded components, the public API or the Wallet tab uses this top-up price and can be invoiced immediately, in which case the invoice is posted straight away.

A change order added in the UI, the API, a quote or a CRM that adds a one-time Credits charge for a credit type that already has an original charge on the order is also treated as a top-up. It keeps its own charge price. The credit type's top-up price applies only to self-service top-ups. Sold on its own or as a recurring grant, the same product is an original Credits charge.

Making a top-up requires the same permission as a change order.

***

## 6. Removing, Cancelling and Terminating

### Removing a Credits charge

When a change order removes a Credits charge, the outcome for unused credits depends on whether another original charge of the credit type remains on the order.

| Situation                                                                              | Choice                                                                   | Result                                                                     |
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
| Another original charge of the credit type remains or is added, for example an upgrade | No choice                                                                | The removed charge's pools are kept and run on as regular pools            |
|                                                                                        | Refund unused credits                                                    | The unused credits are refunded                                            |
|                                                                                        | Write off                                                                | The unused credits are forfeited                                           |
| The change removes the last original charge of the credit type                         | Refund unused credits                                                    | One credit charge per invoiced pool at the pool's own value                |
|                                                                                        | Write off                                                                | The credits are forfeited and stay usable until the day before the removal |
|                                                                                        | No choice, and another order of the account still grants the credit type | Kept until expiry                                                          |
|                                                                                        | No choice, otherwise                                                     | **Unused credits when removed** on the credit type                         |

Credits that are kept until expiry keep their value and expiry date, and breakage is recognised when they expire. Usage continues to draw from them. A pool that has never been invoiced is never billed, so only invoiced pools can be refunded when a charge is removed. A preview shows the outcome, and the order dialogs offer keep as the preselected third choice when it applies.

### Cancelling or terminating an order

The user chooses to forfeit or refund the unused credits. A refund adds one negative one-off charge per priced pool for the remaining credits at the pool's value, and the next invoice run bills it. A pool still waiting for its grant line is refunded at the order's value per credit, so the grant and the refund land on the same run.

### Restrictions

An order with a Credits charge cannot be used for quotes, split, copied, reverted or imported through the Data Management Tool. An order cannot be deleted once it has a pool.

***

## 7. Invoicing and Revenue

### Invoicing

The grant is invoiced like any other charge. An overage line is added at the end of each month for the overage of the period, in arrears. A pool becomes active when its grant invoice line is posted.

### Revenue

Revenue follows consumption. Each drawdown creates a revenue schedule item for the credits drawn multiplied by the value of a credit, in the accounting period of the usage date or the first open period after it. Credits given back by a reversal or adjustment create negative items. When credits expire or are forfeited, the exact remainder is recognised so that the schedule always adds up to the invoice line. Overage lines are recognised in the period of the usage. Refunds go through the normal credit note process.

***

## 8. Notifications and Integrations

### Webhooks

The following webhook events are available when Prepaid Credits is enabled.

| Event               | Webhook event name        | Sent when                                       |
| ------------------- | ------------------------- | ----------------------------------------------- |
| Pool created        | `CreditsPoolMinted`       | A pool is created                               |
| Pool activated      | `CreditsPoolActivated`    | A pool becomes active                           |
| Pool depleted       | `CreditsPoolDepleted`     | A pool is used up                               |
| Pool expiring       | `CreditsPoolExpiring`     | A pool is close to expiry                       |
| Pool expired        | `CreditsPoolExpired`      | A pool expires                                  |
| Pool closed         | `CreditsPoolClosed`       | A pool is closed, for example by a cancellation |
| Low balance reached | `CreditsThresholdCrossed` | A wallet crosses its low balance alert          |
| Wallet depleted     | `CreditsWalletDepleted`   | A wallet runs out of credits                    |
| Usage processed     | `CreditsUsageProcessed`   | Usage is processed                              |
| Usage unmatched     | `CreditsUsageUnmatched`   | A usage record cannot be matched                |
| Wallet topped up    | `CreditsWalletToppedUp`   | A wallet is topped up                           |
| Overage incurred    | `OverageIncurred`         | Usage is billed as overage                      |

Deliveries carry the event identifier and event type as headers. For webhooks created from now on, Younium also signs each delivery with a signature header, so the receiver can verify it. A failed delivery is retried with an increasing delay of 1, 2, 4 minutes and so on, up to 180 minutes between attempts. This retry behaviour applies to all webhooks, not only credits.

### Self service

In the self-service portal and the embedded components, a customer sees each wallet under its subscription: the balance, credits grouped by expiry date, consumption over time, the rate card and a plain message when usage exceeds the credits. They do not see pools, ledger entries or overage settings. A customer can buy credits when top-ups are enabled, and sees the quantity, price, expiry date and invoicing moment before confirming. Credits charges are read-only in the subscription view, so more credits are bought as a top-up.

### Public API

The public API (version 2.1) provides usage reporting, usage records and batches, wallet balance, consumption, top-ups, transactions, pools, credit types, usage types and the overage position of an order. Product and order charges expose the Credits fields, and the cancel request accepts a choice to refund unused credits.

***

## 9. Permissions and Availability

Prepaid Credits is turned on per tenant. When it is off, the credits screens, charge fields, imports and webhook events are not available.

| Capability                                   | Permission group |
| -------------------------------------------- | ---------------- |
| View wallets, pools and usage                | Credits          |
| Import usage manually                        | Credits          |
| View credit types and usage types            | Credits          |
| Create and edit credit types and usage types | Credits          |

A top-up is a change order and needs the permission to activate orders.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.younium.com/platform/credits.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
