Credit grants

Introduction

Prepaid balances are commonly used to track and bill usage. However, a single undifferentiated prepaid balance is often insufficient to support operational needs such as revenue recognition, expiry enforcement, tax calculation at redemption, promotional credits, and plan-specific incentives. These requirements call for more granular tracking and management of prepaid value.

Credit grants provide this structure.

A credit grant represents a discrete allocation of prepaid value with its own lifecycle, purpose, and financial attributes. Instead of treating a wallet account as one undifferentiated pool of funds, Credyt models it as a sequence of grants - each independently issued, consumed and monitored with its own distinct lifetime. This approach enables prepaid usage billing to operate correctly across billing, accounting, and compliance.

A core primitive of real-time usage billing

API Reference

Credit grants are the fundamental units of a prepaid balance and lie at the core of Credyt’s real-time, usage-based billing model.

Each grant defines:

• Its effective and expiry dates
• The amount of value it holds
• How it should be treated for billing, revenue, and compliance purposes

Issuing credit grants

Credit grants enter a wallet through a small number of well-defined entry points. Each entry point determines the purpose of the grant and how its expiry is set - two attributes that are then exposed directly via the Get credit grants endpoint.

When a customer initiates a top-up, and the payment is successfully processed, Credyt automatically creates a credit grant with the purpose set to paid. Paid credit grants have a default expiry of one year, ensuring that prepaid value is time-bound while remaining predictable for both the platform and the end user.

Credit grants can also be created through wallet adjustments and may be used for promotional credits or for credits included in bundled packages or entitlements. In these cases, Credyt derives the purpose and expiry of the grant from the adjustment itself. The reason and expires_at parameters submitted via the Wallet adjustments API determine how the grant is classified and how long it remains valid.

Credit grants do not have to become available immediately - the platform can define when they become effective using the effective_from parameter in the Top-ups and Wallet adjustments APIs. Top-ups initiated directly from the Billing Portal become effective immediately by default.

By standardizing how grants are issued, Credyt ensures that every credit grant has a clear origin, a defined purpose, and an explicit lifetime, all of which are visible and auditable at the grant level.

Consumption at grant level

An account’s balance is the sum of its active grants. Usage draws down from these grants following platform-defined rules, such as prioritizing included or promotional credits before paid ones, or consuming the earliest-expiring grants first.

Because consumption deducts from grants as it occurs:

• Revenue can be recognized at the time of consumption
• Exchange rates/cost basis for custom units can be locked at purchase
• Expiry and breakage are handled appropriately at the grant level
• Taxes can be applied accurately using relevant jurisdiction and service metadata

Handling credit expiry

When a credit grant expires, it is flagged as inactive and no longer available for usage. This triggers a set of processes to ensure accurate billing, accounting, and auditability:

• Revenue recognition - any remaining deferred revenue linked to the expired credit grant is recognized as actual revenue. This moves the value from deferred revenue to recognized revenue in the underlying ledger.

• Usage drawdown - expired credit grants are excluded from the available balances. Subsequent usage will draw from the next active credit grants according to platform-defined consumption rules.

• Auditability - even after expiry, the credit grant record remains available for auditing purposes. These records can be retrieved through the Get credit grants endpoint, providing full visibility into grant history and status.

• Grace Periods - Credyt implements a grace period for credit expiry, delaying the effective expiration by several hours. This delay accommodates late event submissions and synchronization issues, ensuring usage events are processed accurately without premature expiry.

Revenue recognition at consumption

Revenue in Credyt is recognized when credits are consumed or expire, not when they are purchased. When a customer tops up, the value is recorded as deferred revenue and only becomes recognized revenue as usage draws down from the associated credit grants.

Each credit grant retains the transaction price and, where applicable, the exchange rate (cost basis) from the time of purchase. This ensures that, as usage is billed, whether in fiat or custom units, revenue can be calculated accurately in fiat and posted correctly to the general ledger, even if exchange rates change between top-up and consumption.

By tying revenue recognition directly to grant-level consumption, Credyt avoids the accounting ambiguity that arises from flat prepaid balances and maintains precise, auditable revenue reporting.

Example

GET /customers/:customerId/wallet/default:USD/grants?exclude_expired=true

{
  "items": [
    {
      "id": "9a946e9c-ee30-4af2-9e80-070337504190",
      "effective_at": "2026-01-01T00:00:00Z",
      "expires_at": "2026-12-31T23:59:59Z",
      "purpose": "paid",
      "created_at": "2025-01-01T00:00:05Z",
      "available": 17.58
    },
    {
      "id": "009d2d65-b2ef-4308-b81d-074b611254e2",
      "effective_at": "2026-01-15T00:00:00Z",
      "expires_at": "2026-02-15T23:59:59Z",
      "purpose": "promotional",
      "created_at": "2026-01-14T00:00:02Z",
      "available": 3.25
    }
  ],
  "total_count": 2,
  "limit": 2,
  "offset": 0
}