# Concepts & Terminology

A guide to the core primitives, resources, and terminology used throughout the Credyt product.

## Customers[​](#customers "Direct link to Customers")

Customers represent your end users in Credyt. Before billing can occur, you must register customers and subscribe them to products. When creating a customer, you can provide your own unique identifier (`external_id`) which can then be used when submitting usage events.

**Key points:**

* Customers are created via the Customers API
* They must be subscribed to products to be billed
* Can use either Credyt's customer ID or your own external ID
* No extensive personal data required - only what's needed for identification and billing

## Products and Pricing[​](#products-and-pricing "Direct link to Products and Pricing")

Products define what you're billing for and how customers are charged. Each product has a unique code and contains one or more prices that determine billing behavior.

### Prices[​](#prices "Direct link to Prices")

Prices are the building blocks of your billing configuration. Each price defines what event type triggers billing, how usage is measured, and the rates charged.

**Price Types:**

A price can be either:

* **Usage-based**: Charges based on actual consumption or events. Usage-based prices track and bill for customer activity as it happens - such as API calls, tokens consumed, minutes processed, or tasks completed.

* **Fixed**: Flat fees that don't vary with usage (e.g., monthly platform fee, seat license). These are billed as a set amount regardless of consumption.

### Billing Models[​](#billing-models "Direct link to Billing Models")

Each price has a billing model that determines *when* charges are applied:

* **Real-time**: Usage is billed immediately as events occur, deducting from the customer's wallet balance in real-time. This ensures customers always know their current balance and can't consume more than their available funds (plus any configured overdraft).

* **Recurring**: Usage accumulates over a billing period (typically monthly) and is billed at the end of that period. This is common for post-paid or invoice-based billing scenarios.

### Usage Calculation[​](#usage-calculation "Direct link to Usage Calculation")

For usage-based prices, the usage calculation configuration determines how usage is measured:

* **Unit-based**: Charges per occurrence of an event (e.g., $0.50 per video promoted, $2 per API call)
* **Volume-based**: Charges based on quantity consumed in the event payload (e.g., $0.001 per token, $0.10 per minute)
* **Unit and Volume**: Combines both approaches (e.g., $0.05 per chat + $0.0001 per token used in that chat)

### Dimensional Pricing[​](#dimensional-pricing "Direct link to Dimensional Pricing")

Prices can optionally vary based on attributes of the usage event, such as:

* Speed tier (fast vs regular)
* Quality level (standard vs premium)
* Model type (GPT-4 vs GPT-3.5)

This allows a single price to handle multiple variations without creating separate price configurations.

## Subscriptions[​](#subscriptions "Direct link to Subscriptions")

Subscriptions link customers to products, determining which pricing applies to their usage. When you subscribe a customer to a product, Credyt automatically provisions wallet accounts in the billing currencies defined by the product's pricing.

**Important:** Subscriptions in Credyt are distinct from traditional recurring subscription payments. They represent which products a customer has access to, not necessarily a recurring payment commitment.

## Wallets and Accounts[​](#wallets-and-accounts "Direct link to Wallets and Accounts")

Every customer has one wallet that can contain multiple accounts, each tracking a specific asset.

### Wallets[​](#wallets "Direct link to Wallets")

A wallet is the container for all of a customer's balance accounts. It's created automatically when a customer is subscribed to a product or initiates their first top-up.

### Accounts[​](#accounts "Direct link to Accounts")

Accounts hold balances in specific assets (currencies or custom units). They are provisioned automatically based on the products a customer subscribes to. Each account tracks:

* Available balance
* Pending incoming funds
* Pending outgoing charges

Accounts support overdrafts by default to ensure usage can be billed even when balances are low.

## Assets[​](#assets "Direct link to Assets")

Assets are the units of value used for billing. They can be:

* **Fiat currencies** (USD, EUR, etc.)
* **Custom units** you define (tokens, minutes, credits, etc.)

For custom assets, you define exchange rates from fiat currencies. These rates determine how much of your custom asset customers receive when topping up. Exchange rates can be updated and scheduled for future effective dates.

## Top-ups and Auto Top-up[​](#top-ups-and-auto-top-up "Direct link to Top-ups and Auto Top-up")

### Top-ups[​](#top-ups "Direct link to Top-ups")

Top-ups are how customers add funds to their wallet accounts. They can be initiated:

* Through the Billing Portal (self-service)
* Via the Top-up API (integrated into your product)
* Externally through your own PSP (reflected via Adjustments)

When using Credyt's payment processing, top-ups are handled through Stripe Checkout.

### Auto Top-up[​](#auto-top-up "Direct link to Auto Top-up")

Auto top-up keeps wallets funded automatically by defining balance thresholds and recharge amounts per asset. When a balance drops below the threshold, Credyt initiates an off-session payment and credits the wallet.

**Configuration:**

* Set per asset in the Billing Portal
* Requires saved payment card authorization
* Prevents service interruption during variable usage

## Credit Grants[​](#credit-grants "Direct link to Credit Grants")

Credit grants are the fundamental units of a prepaid balance. Rather than treating a wallet as one undifferentiated pool, Credyt tracks each discrete allocation of value separately.

**Each grant defines:**

* Effective and expiry dates
* Amount of value
* Purpose (paid, promotional, included)
* How it should be treated for revenue recognition

**Key characteristics:**

* Created from top-ups, adjustments, or entitlements
* Consumed according to platform-defined rules
* Enable proper revenue recognition at consumption
* Support time-limited promotional credits
* Remain auditable even after expiry

## Entitlements[​](#entitlements "Direct link to Entitlements")

Entitlements are "right-to-use" grants that represent bundled allocations included with a product subscription. Unlike direct credit purchases, entitlements decouple service access from payment and enable hybrid billing models that combine recurring fees with usage-based pricing.

**How entitlements work:**

When a customer subscribes to a product with entitlements, Credyt automatically:

* Grants the specified credit amount to the customer's wallet
* Refreshes this allowance according to your defined schedule (daily, monthly, etc.)
* Tracks consumption against the entitlement balance
* Charges overage fees when credits are exhausted

**Entitlement types:**

* **Bundled entitlements**: Credits included as a feature of a fixed-fee plan (e.g., "$20/month includes 1,000 credits"). The subscription fee is recognized ratably while the credit value typically has a revenue basis of $0.

* **Promotional entitlements**: Free credits granted to incentivize signups, login streaks, or referrals. No revenue is recognized. These track a cost basis to record marketing expense when consumed.

**Key characteristics:**

* Can grant credits in fiat currency or custom assets
* Support flexible refresh strategies (expire-and-replace, rollover)
* Enable priority-based consumption rules (e.g., use promotional credits before bundled credits)
* Integrate with revenue recognition for proper accounting
* Enable hybrid billing models combining subscriptions with usage overages

## Payments[​](#payments "Direct link to Payments")

Payments in Credyt are processed through Stripe. When using Credyt's built-in payment processing:

* Customers complete checkout via Stripe's hosted interface
* Payment confirmation automatically updates wallet balances
* All payment data and PCI compliance is handled by Stripe
* Platforms can connect their own Stripe account or use Credyt's for testing

For platforms using external PSPs, payments are reflected in Credyt via the Adjustments API.

## Adjustments[​](#adjustments "Direct link to Adjustments")

Adjustments allow direct manipulation of account balances outside normal usage processing. They're used for:

* External PSP payments (subscriptions, top-ups)
* Refunds
* Promotional credits and gifts
* Manual corrections

Each adjustment requires:

* A unique transaction ID (idempotency key)
* A reason code (external\_topup, external\_refund, gift, other)
* The asset and amount
* Optional expiry date and metadata

## Fees[​](#fees "Direct link to Fees")

Fees are charges generated when usage events are processed. They represent the actual billable amount deducted from a customer's wallet.

**Fees include:**

* Product and price references
* Calculated amounts based on usage
* Dimensional attributes (if applicable)
* Usage type (unit, volume, or both)
* Description of what was billed

Fees are created automatically when usage events match product pricing configurations.

## Billing Portal[​](#billing-portal "Direct link to Billing Portal")

The Billing Portal is a hosted, self-service interface where customers can:

* View wallet balances across all assets
* See usage history and charges
* Review transaction history
* Initiate top-ups
* Configure auto top-up settings
* Manage saved payment cards

**Access:**

* No customer sign-up required
* Accessed via pre-authenticated session links
* Sessions expire after 10 minutes if unused
* Fully customizable with your branding

## Vendors[​](#vendors "Direct link to Vendors")

Vendors represent external services or infrastructure that power your product (AI model providers, compute platforms, third-party APIs). They're used in profitability tracking to correlate costs with revenue.

## Costs[​](#costs "Direct link to Costs")

Costs represent expenses incurred from vendors when serving usage. They're attached to usage events to enable profitability analysis.

**Costs can be attributed at:**

* Customer level
* Event level
* Subject level (task or outcome)

When combined with revenue from fees, costs enable calculation of gross revenue, net revenue, and margin per event, customer, or product.