---
name: orbyte-integrate
description: Connect Orbyte Labs credit checks and usage tracking to real server operations. Use for customer identities, billing retries, AI SDK integration, test funding, and development verification.
---

# Integrate credit billing

Follow the project's instructions. Inspect authentication, billable operations, retries, and tests.

Read [checking and tracking](https://docs.orbytelabs.com/checking-and-tracking.md) for the contract and [SDK events](https://docs.orbytelabs.com/sdk/events.md) for usage examples. Other languages use the [HTTP API](https://docs.orbytelabs.com/openapi.json).

## Confirm the catalog

Read `orbyte.config.ts` before adding billing calls. Every billable feature must exist in its `features` map, with a price and aggregation matching the operation. If the file, a required feature, or the server key is missing, complete [setup](https://docs.orbytelabs.com/skills/orbyte-setup/SKILL.md) first. Deploy catalog changes to the development environment and wait for readiness before testing `check` and `track`.

## Connect billable work

Use the stable authenticated account or tenant ID that owns the credits, never an arbitrary request field. Keep `ORBYTE_API_KEY` and billing calls on the server.

Use the public SDK's `check`, `track`, and `balance` functions, or the public HTTP API for other languages. Deploy the catalog through the CLI and verify that the resulting customers and usage are visible in the dashboard.

At each existing billable operation, check access before work and track actual usage after success:

```ts
import { check, track } from "orbytelabs";

const access = await check("requests", authenticatedCustomerId);
if (!access.allowed) throw new Error(access.reason);

const result = await performBillableWork();
await track("requests", authenticatedCustomerId, undefined, {
  idempotencyKey: persistedOperationId,
});
return result;
```

Use deployed feature keys and match payloads to their aggregation, such as `{ tokens: actualTokenCount }` for `sum("tokens")`. Distinct checks need the same grouping payload as tracking. Preserve the project's rule for failed work and its error responses.

Derive event keys from durable request or job IDs, unique per billable event. Retry with the same key, identity, feature, payload, and optional cost. A check reserves no credits, so tracking can still fail after allowed work. Retry the charge without repeating completed work, using the existing job or outbox mechanism where available. The SDK does not retry automatically. Surface unresolved billing failures and report any missing durable delivery path.

Do not let a new `check` block confirmation of an uncertain earlier charge. That charge may have consumed the last credit. Retry `track` directly with its original idempotency key and terms. SDK tracking still rejects a new charge without eligible credits.

For Eve agents, use [the Eve integration](https://docs.orbytelabs.com/integrations/eve.md). Export `creditHooks(...)` from one file under `agent/hooks/`. Resolve `identity` from authenticated Eve context, such as `({ session }) => session.auth.current?.principalId`, or a trusted billing-account lookup. The hook checks access before model and tool execution, then tracks `usage.recorded` and successful tool completion. Persist tracking failures through `onError`.

For a compatible Vercel AI SDK app, use [the existing integration](https://docs.orbytelabs.com/integrations/ai-sdk.md) instead of duplicating model or tool charges. Preserve streaming, cancellation, telemetry, and error handling. Do not upgrade a framework solely to fit an example.

## Fund and verify

Fund an isolated development identity. Adapt the amount and feature keys to the deployed prices:

```sh
npx orbytelabs grant 1 --identity onboarding_test --features requests \
  --idempotency-key onboarding_test_initial_grant
```

Keep the grant key stable when retrying. For requested paid funding, follow [grants and top-ups](https://docs.orbytelabs.com/grants-and-topups.md) or [subscriptions](https://docs.orbytelabs.com/subscriptions.md). Confirm payment through the supported payment lifecycle before granting paid access; a checkout redirect is insufficient.

Run focused typechecks and tests against the real application billing boundary:

- Authentication determines whose credits are used, and cross-customer attempts fail.
- Denied checks prevent work; failed work follows the charging rule.
- Successful work records actual usage. Replaying the event returns the same ID without a second debit; changing its terms conflicts.
- An uncertain charge retries with the same key without rerunning completed work.

When account access is available, also exercise the application in development and inspect its balance and ledger. Use `check`, `track`, and `balance` for API smoke checks, including an identity without eligible credits to verify denial. CLI-only checks do not verify the application's authentication or execution boundary.

Follow project rules for servers and browser automation. Report the changed entry points, checks actually run, and anything left unverified.
