Billing & Plans

Atlas uses a tiered billing model. SaaS workspaces on app.useatlas.dev start with a 14-day trial, then require a paid plan. Self-hosted deployments are free with no enforcement. Billing includes automatic usage metering and graceful overage handling.

Plan Tiers

• Trial — Auto-assigned on SaaS signup. Same limits as Team. Expires after 14 days, then queries are blocked until the workspace upgrades.
• Team — Standard paid tier. Monthly or annual billing via Stripe.
• Enterprise — Custom contracts. No metered limits. Includes SSO, SCIM, and priority support.
• Self-Hosted (free) — No billing enforcement. All features available, no Stripe needed.

BYOT (Bring Your Own Token)

BYOT lets workspaces supply their own LLM API keys instead of using Atlas-provided tokens. When enabled:

• The workspace is billed at a lower rate on the Team plan (BYOT is a configuration flag, not a separate Stripe product)
• Token usage is still metered for analytics, but token limits are not enforced
• Admin or owner role is required to toggle BYOT

Toggle via the billing API:

curl -X POST https://your-atlas.example.com/api/v1/billing/byot \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-token>" \
  -d '{ "enabled": true }'

Usage Dashboard

The admin usage dashboard is available at Admin > Usage (/admin/usage). It shows:

• Query count — total SQL queries executed this billing period, with progress bar toward limit
• Token count — total LLM tokens consumed, with progress bar toward limit
• Active users — unique users who logged in this period (requires login event instrumentation; may show 0 if not yet configured)
• Current plan — tier name and trial expiry date (if applicable)
• Daily usage chart — queries and tokens over the last 30 days
• Per-user breakdown — sortable table of usage by individual user (top 50)

If the workspace has a Stripe subscription, a Manage Plan button opens the Stripe Customer Portal for self-service plan changes.

API Endpoints

Usage data is also available programmatically via the admin API. See Usage Metering for endpoint details.

Overage Handling

Atlas uses a 4-tier degradation model instead of a hard cutoff. Enforcement runs before every agent execution, checking query and token usage against plan limits.

The worst status across all metered dimensions (queries and tokens) determines the outcome. For example, if token usage is at 85% (warning) and query usage is at 105% (soft limit), the soft limit behavior applies.

Enforcement Skipped

Billing enforcement is skipped entirely when:

• No internal database is configured (self-hosted without managed auth)
• The user is not in an organization
• The workspace is on the free or enterprise tier

Trial Expiry

Trial workspaces have a separate check: if the trial has expired (14 days from creation or past the trial_ends_at date), all requests are blocked with HTTP 403 and a message to upgrade.

Metering Failures

If workspace or plan data cannot be fetched, the request is blocked with HTTP 503 as a security precaution. If usage metering data specifically cannot be read (e.g., metering database is temporarily unavailable), the request is allowed with a warning that usage tracking may be inaccurate. Enforcement is best-effort for metering — Atlas prefers availability over strict enforcement.

Customer Portal

Workspaces with a Stripe subscription can access the Stripe Customer Portal for self-service plan management:

• Upgrade or downgrade plans
• Update payment methods
• View invoices and billing history
• Cancel subscriptions

Available features depend on your Stripe Customer Portal configuration.

Access via the Manage Plan button on the usage dashboard, or programmatically:

curl -X POST https://your-atlas.example.com/api/v1/billing/portal \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{ "returnUrl": "https://your-atlas.example.com/admin/usage" }'

The response contains a url field — redirect the user to this URL to open the portal.

Stripe Setup (Self-Hosted)

Set these environment variables to enable billing:

When STRIPE_SECRET_KEY is set:

• Billing routes mount at /api/v1/billing
• The Better Auth Stripe plugin handles checkout, webhooks, and subscription lifecycle at /api/auth/stripe/*
• Plan changes from Stripe webhooks automatically update the workspace tier

Webhook Configuration

Point your Stripe webhook endpoint to:

https://your-atlas.example.com/api/auth/stripe/webhook

For local development, use Stripe CLI to forward webhooks:

stripe listen --forward-to localhost:3001/api/auth/stripe/webhook

Self-Hosted Deployments

Self-hosted Atlas has no billing enforcement. The free tier is assigned by default with unlimited queries, tokens, members, and connections. No Stripe configuration is needed.

To run Atlas without any billing:

1. Omit all STRIPE_* environment variables
2. The billing routes will not mount
3. The usage dashboard still works for monitoring (if DATABASE_URL is configured) but shows "Unlimited" for all limits

Troubleshooting

Stripe webhooks not arriving

• Verify STRIPE_WEBHOOK_SECRET matches the signing secret from your Stripe dashboard or stripe listen output
• Ensure the webhook endpoint (/api/auth/stripe/webhook) is publicly reachable
• Check Stripe dashboard Developers > Webhooks for failed delivery attempts
• For local development, confirm stripe listen is running and forwarding to the correct port

Plan not syncing after payment

• Stripe webhook events update the workspace tier. Check that webhooks are being received (see above)
• The plan cache has a 60-second TTL — changes may take up to a minute to propagate
• Call GET /api/v1/billing to check the current billing status for the workspace

Usage not updating

• Usage events are fire-and-forget with a circuit breaker. After 5 consecutive write failures, events are dropped for 60 seconds before the circuit breaker resets and retries
• Verify DATABASE_URL is set and the internal database is accessible
• Historical summaries are aggregated on-demand when the dashboard or /history endpoint is accessed

Trial expired unexpectedly

• Trial duration is 14 days from workspace creation (or from trial_ends_at if set)
• Check the workspace's creation date via GET /api/v1/billing — the trialEndsAt field shows the expiry

See Also

• Usage Metering — Detailed metering API and aggregation
• Environment Variables — Full variable reference including Stripe config
• Enterprise SSO — SAML/OIDC single sign-on (Enterprise tier)
• Stripe Docs — Stripe API and dashboard reference