Environments and deployment

Credit isolates data by application. Your workspace starts with Development. Open the application selector and choose Create Production when you are ready to use real customer balances.

Production starts empty. Credits, features, wallets, deposits, events, and API keys do not copy across automatically. The same catalog keys and customer identities can exist independently in both applications.

Verify your target

Create a key while the intended application is selected. With a key that has credits:read, inspect its target before deploying:

curl --fail-with-body "https://api.orbytelabs.com/v1/application" \
  -H "Authorization: Bearer $ORBYTE_API_KEY"

Check name, appId, and isLive in the response. Switching the dashboard selector does not change the key in your server environment.

Deploy your catalog

Keep orbyte.config.ts with your application code. The CLI creates and updates the definitions that config declares:

pnpm exec orbyte deploy --dry-run
pnpm exec orbyte deploy

The command prints the target organization and application before applying changes. It also writes _orbyte.ts with generated credit and feature keys in src if that directory exists, otherwise beside your config. A dry run performs no catalog writes and does not generate the file, but it still validates the permissions the proposed writes require.

To select another config:

pnpm exec orbyte deploy --config ./billing/orbyte.config.ts

The CLI loads .env.local from that config's directory. Existing environment variables take precedence. A continuous catalog watcher is available through pnpm exec orbyte dev; it deploys on startup and watches the config and its local imports. This is a catalog watcher, so you still run your own application separately.

Release to Production

Set ORBYTE_API_KEY to a Production setup key in the deployment environment. Development and Production use the same API address; the key selects the application. Then preview and apply the same config:

pnpm exec orbyte deploy --dry-run
pnpm exec orbyte deploy

Confirm that isLive is true when inspecting the key's target above.

Fund the intended production wallets separately. Give the running service an Ingestion key if it only needs check and track. Keep broader setup and deposit permissions with the services that need them.

Change prices deliberately

Fixed-price tracking uses the current deployed catalog. A price update affects future charges; it does not rewrite previous transactions. Keep feature keys stable when changing names or prices. Changing a key creates a different feature.

Removing a credit or feature from the config does not delete the stored definition. Deployment preserves existing catalog entries and ledger history.

Callback code runs in your server application. Deploy its code and catalog changes together, especially when changing between fixed and callback pricing. A request with the wrong pricing mode is rejected. Preserve the originally resolved amount when retrying an event after a callback change.

Period rules lock after the first period charge. To change a locked rule, create a new feature key. See usage periods.

Catalog writes are sequential. If a deployment fails halfway through, earlier changes may have applied. Fix the reported error and rerun; the CLI compares the current catalog again before applying the remaining changes.