# Grants and top-ups

Source: https://docs.orbytelabs.com/grants-and-topups

Fund a customer and read the available balance.

## Automatic grant policies [#automatic-grant-policies]

Set `grantPolicies` in [`orbyte.config.ts`](/pricing) to issue credits automatically.
Each named policy issues a separate grant when its event occurs. Customer creation
is available now, with more events coming soon.

| Event               | Status      | Trigger                            |
| ------------------- | ----------- | ---------------------------------- |
| `customer.created`  | Available   | Orbyte creates a customer.         |
| `subscription.paid` | Coming soon | A subscription invoice is settled. |
| `topup.paid`        | Coming soon | A credit purchase is confirmed.    |

For `customer.created`, grants are issued once, including through the first tracked
event, manual grant, or checkout creation. Starting checkout can issue these credits
even if the customer never completes payment. Application signup alone does not
create an Orbyte customer.

Policies can have different credit amounts, feature lists, and expiry periods.
Retries do not issue another grant. Redeploying, renaming a policy, or spending the
balance does not issue new grants to existing customers.

Optional `expiresAfterDays` on each policy sets its lifetime from customer creation,
in whole days. Omit it for no expiry. Retries, redeployment, and expiry never extend
the original deadline or issue replacement credits.

Policy grants require no payment or subscription. They remain separate from
purchased credits in the grant ledger and have zero paid value.

## Grant credits [#grant-credits]

```typescript title="TypeScript"
import { Orbyte, credits } from "orbytelabs";

const client = new Orbyte({ accessToken: process.env.ORBYTE_API_KEY });
await client.grants.create({
  identity: "customer_123",
  credits: credits(5),
  featureKeys: ["requests"],
  idempotencyKey: "welcome_customer_123",
});
```

Manual grants create the customer if needed and add credits without collecting
payment. Feature keys must be distinct keys in the
active catalog. `[]` grants no access. Optional `expiresAt` is a future Unix timestamp
in milliseconds; omit it for no expiry. Reusing the key with identical terms is safe.

## Sell credits [#sell-credits]

```typescript title="TypeScript"
const session = await client.topups.checkout({
  identity: "customer_123",
  credits: credits(5),
  featureKeys: ["requests"],
  successUrl: "https://app.example.com/billing/success",
  cancelUrl: "https://app.example.com/billing",
});
// Redirect the customer to session.url.
```

Top-ups require a Stripe connection. One credit costs $1 USD.
Amounts must be exact cents, between $0.50 and $999,999.99. No subscription is
required. Each request creates a new checkout session.

Credits arrive only after confirmed payment through Stripe webhooks. A success
redirect is not payment proof. Purchased credits use their explicit feature list
and optional expiry independently of subscriptions and plan rollover.

## Read a balance [#read-a-balance]

```typescript title="TypeScript"
import { balance } from "orbytelabs";

const result = await balance("customer_123");
console.log(result.availableCredits); // bigint ledger units
```

An unknown identity previews the sum of `customer.created` grant policies, or
returns zero if none are configured. Reads create no customer, grant, or event.
Existing customers receive only their actual balance, including zero after
exhaustion. The result also includes `asOf` and optional `nextChangeAt`. A feature
check can return less than this overall balance because grants have different
feature scopes.