Skip to Content
Orbyte Labs

Grants and top-ups

Fund a customer and read the available balance.

Automatic grant policies

Set grantPolicies in orbyte.config.ts 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.

EventStatusTrigger
customer.createdAvailableOrbyte creates a customer.
subscription.paidComing soonA subscription invoice is settled.
topup.paidComing soonA 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

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

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

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.

On this page