Skip to main content

Concepts & Terminology

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

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 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 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​

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​

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​

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 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​

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

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 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 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​

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 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 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 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 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 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 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​

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 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 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.