---
name: orbyte-migrate
description: Replace custom credit billing or another billing provider with Orbyte Labs. Map existing rules, migrate and verify development code, and prepare any live balance or subscription cutover.
---

# Migrate billing to Orbyte Labs

Follow the project's instructions. Complete development code and tests; make live balance or payment changes only within an explicitly requested cutover.

## Map existing billing

Trace authentication, grants, checks, usage, retries, subscriptions, top-ups, refunds, and webhooks in the code and schemas. Record the mapping in the project's existing documentation:

| Existing concept            | Orbyte target                                             |
| --------------------------- | --------------------------------------------------------- |
| Account or tenant ID        | Customer `identity` with the same credit owner            |
| Billable operation and unit | Feature key and aggregation                               |
| Unit price                  | Credit cost rule with explicit conversion and rounding    |
| Balance buckets             | Grants preserving feature scope, expiry, and paid value   |
| Usage record or job ID      | Stable event idempotency key                              |
| Subscription or top-up      | Supported payment lifecycle with a defined charging owner |

Preserve known business rules. Ask for missing conversion decisions. Do not silently limit an unlimited entitlement or merge buckets with different expiry or access rules. Check [pricing](https://docs.orbytelabs.com/pricing.md), the installed SDK types, and [OpenAPI](https://docs.orbytelabs.com/openapi.json) before assuming a transfer operation exists.

## Implement and verify

1. Follow [orbyte-setup](https://docs.orbytelabs.com/skills/orbyte-setup/SKILL.md) to write or update `orbyte.config.ts` and deploy the mapped catalog to a development target.
2. Follow [orbyte-integrate](https://docs.orbytelabs.com/skills/orbyte-integrate/SKILL.md) at the existing billing boundary. Reuse the app's abstraction where present and preserve authentication, jobs, streaming, and retries.
3. Update callers, environment examples, tests, and project notes. Remove obsolete development code while retaining handlers that still own live payments or refunds.
4. Keep one charging owner per operation. If both systems remain temporarily, use existing environment or customer configuration to select one. Verify the old provider does not also charge migrated usage.

Run the integration skill's checks with representative existing customers and operations. Compare balances and prices against the mapping, including scoped or expiring credits when used. Keep fixtures bounded and production exports out of source control.

Manual grants have zero paid USD value. They can fund development tests but cannot preserve purchased balances' revenue allocation. If paid grants or active subscriptions lack a supported transfer operation, finish the code migration and report the exact missing capability. Do not invent import endpoints or recreate paid history with free grants.

## Prepare live cutover when requested

Define the customers, balances, subscriptions, and in-flight jobs being moved, when charging ownership changes, and how rollback reconciles usage already accepted by Orbyte. Preserve durable event IDs, grant scopes and expiry, paid valuation, and records needed for refunds or disputes. Account for late webhooks and existing payment-provider IDs.

For supported data transfers, use bounded batches, checkpoints, and deterministic migration keys so retries can resume. Reconcile totals before broadening the transfer. Never assume that recreating a subscription will avoid another charge.

Report which code, test, data, and production steps actually completed, and any unsupported transfers or missing access.
