# Core concepts

Source: https://docs.orbytelabs.com/concepts

How credits, features, wallets, and usage fit together.

Credit keeps a prepaid balance for each customer and deducts credits when they use your product. Your application decides who pays, what counts as usage, and when to add funds.

For example, give a customer 100 credits, price an API call at 1 credit, then track a call. Credit records the transaction and leaves 99 credits in their wallet.

## Applications [#applications]

An application contains its own credit types, features, wallets, deposits, and usage. Each API key belongs to one application and selects it for every request.

Use Development while testing and Production for real usage. The same identity or feature key can exist in both, with separate balances and history. Your application does not send organization or application IDs with billing requests.

See [authentication](/authentication) for keys and permissions.

## Credits [#credits]

A credit type is a unit your customers spend. Most products can start with one type named `credits`. Add separate types only when their balances should stay separate, such as image credits and compute credits.

```ts
import { credit, usd } from "@orbytelabs/credit";

export const credits = credit("credits", "Credits").worth(usd("0.01"));
```

This defines a credit worth one cent for SDK price conversion. It lets you turn a dollar cost into a credit charge. It does not set up a checkout or exchange wallet balances.

Credit stores amounts in nanocredits. One credit equals `1,000,000,000` nanocredits, so fractional prices remain precise. The SDK accepts decimal credit amounts; the HTTP API sends and returns nanocredit amounts as decimal strings.

## Features [#features]

A feature is something your product charges for, such as an API call, an image, or a model request. It has a stable key, a display name, a usage unit, and a price in one credit type.

```ts title="orbyte.config.ts"
import { credit, feature, Orbit, usd } from "@orbytelabs/credit";

export const credits = credit("credits", "Credits").worth(usd("0.01"));

export default Orbit({
  features: {
    "api-call": feature("API call", "request", credits(1)),
    inference: feature(
      "AI inference",
      "request",
      usd
        .markup("10%", (data: { costUsd: string }) => data.costUsd)
        .in(credits),
    ),
  },
});
```

The first feature charges a fixed amount. The second calculates the charge from provider cost on your server, including a 10% markup. [Pricing](/pricing) covers quantities, callbacks, and conversion.

Deploy this configuration to register the credit types and features before sending usage. The [quickstart](/quickstart) walks through setup.

## Identities and wallets [#identities-and-wallets]

An identity is your application's identifier for whoever pays. Use a stable database ID such as `customer_123` or `organization_456`. Credit maps that identity to a wallet within the selected application.

A wallet can hold several credit balances. Each feature spends only its configured credit type. A balance omitted from the wallet response is zero.

You usually do not need to create wallets separately. Funding or tracking usage provisions them by identity. Reading or checking a missing wallet does not create one.

## Deposits and usage [#deposits-and-usage]

A deposit adds credits. A usage event charges a feature and records a transaction.

| Operation                       | What it does                                                                  |
| ------------------------------- | ----------------------------------------------------------------------------- |
| `topup(identity, credits(100))` | Adds 100 credits and records a deposit.                                       |
| `check(feature, identity)`      | Returns the current price and whether the wallet can afford it.               |
| `track(feature, identity)`      | Checks the balance, deducts the charge, and records a transaction atomically. |
| `getWallet(identity)`           | Reads the wallet and its stored balances.                                     |

`check` does not reserve funds. Another request can spend credits before `track`, so your application must handle a rejected charge even after an allowed check. See [checking and tracking](/checking-and-tracking).

Use [direct top-ups](/wallets-and-topups) after your own payment integration confirms payment, or when your grant policy awards credits. This operation records the funding without collecting money.

For hosted payment collection, [paid top-up checkout](/subscriptions) adds credits after Stripe confirms payment. Plans can grant recurring wallet credits after confirmed creation, renewal, or full-period migration invoices. They can also include feature usage before a customer starts spending credits. Included feature usage is a quantity allowance, separate from the wallet balance. Recurring credit grants add to that balance, and unspent credits carry over.

## Charging once per period [#charging-once-per-period]

Most features charge for every event. A feature can instead charge once per day, week, month, or wallet billing period. Later uses in the same period record zero-charge transactions.

For example, a monthly active resource feature can charge each resource once while still recording all of its activity. This controls usage counting. It does not automatically replenish a balance or create a subscription. See [usage periods](/usage-periods).