Managing your subscription

Who can do this

billing.read and billing.update belong to OWNER and BILLING only.

Note

ADMIN cannot touch billing. Administering the platform and spending money are separate concerns — that’s why the BILLING role exists, so finance can see invoices and usage without seeing your models and datasets.

No API token scope reaches billing either. A leaked CI token can’t change your plan.

Current state

Organization settings → Billing, or:

curl -sS "https://cavsnode.com/api/v1/organizations/acme-ai/billing" \
  -H "Authorization: Bearer $CAVS_TOKEN"

Returns the current plan, subscription status, the period, usage against the plan’s limits, and an invoice preview including projected overage.

Upgrading

1. Go to Settings → Billing → Change plan and choose one.

2. You’re redirected to the payment provider’s hosted checkout. CAVS never sees your card details.

3. On success you come back and the plan applies — normally within seconds, once the provider’s webhook lands.

Over the API

curl -sS -X POST "https://cavsnode.com/api/v1/organizations/acme-ai/billing/checkout" \
  -H "Authorization: Bearer $CAVS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"plan_id": "team"}'

{ "url": "https://checkout.stripe.com/c/pay/…" }

Redirect the user to url.

If the plan doesn’t change immediately

Plan changes arrive by provider webhook. If it’s slow, nudge it:

curl -sS -X POST "https://cavsnode.com/api/v1/organizations/acme-ai/billing/confirm" \
  -H "Authorization: Bearer $CAVS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"plan_id": "team"}'

A 202 Accepted with {"status": "pending_webhook"} means the provider hasn’t confirmed yet — poll GET …/billing.

Caution

free and business have no checkout price by design: Free never checks out and Business is contact-sales. Attempting a checkout for a plan with no configured price fails with a clear message.

The billing portal

Cards, invoices, billing address, tax details and cancellation live in the provider’s portal:

curl -sS -X POST "https://cavsnode.com/api/v1/organizations/acme-ai/billing/portal" \
  -H "Authorization: Bearer $CAVS_TOKEN"

{ "url": "https://billing.stripe.com/p/session/…" }

The link is short-lived and single-use — generate a fresh one each time.

Downgrading

Same flow with a lower plan_id.

Check your usage first

A downgrade doesn’t delete anything, but it can leave you over the new plan’s limits. When that happens, writes are refused with 402 quota_exceeded until you’re back under. The read path keeps working.

Before downgrading, compare against the target plan:

curl -sS "https://cavsnode.com/api/v1/organizations/acme-ai/usage" -H "$H"
curl -sS https://cavsnode.com/api/v1/plans | jq '.plans[] | select(.id == "developer")'

Watch repositories (Free allows one), members, tokens and physical storage.

The BYOS add-on

Developer plans can add Bring Your Own S3 for $29/mo:

curl -sS -X POST "https://cavsnode.com/api/v1/organizations/acme-ai/billing/byos-addon" \
  -H "Authorization: Bearer $CAVS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

Team and Business include BYOS, so the add-on doesn’t apply. Disabling it while repositories use BYOS connections will fail — move or delete those repositories first.

Add-ons aren't separately charged yet

The BYOS add-on and extra storage connections appear in the invoice preview, but the current single-price checkout does not charge for them separately. Contact sales if you need accurate add-on billing today.

Payment problems

Event	Effect
billing.payment.failed	Notification + email to the organization
Repeated failure	The subscription lapses per the provider’s dunning policy
storage.quota.exceeded	The organization is marked PAST_DUE

A PAST_DUE organization keeps its data and its read access. Write operations are refused with 402 until the situation is resolved.

Fix payment details in the billing portal. The change takes effect as soon as the provider confirms.

Cancelling

1. Export or download anything you need first.

2. Cancel the subscription in the billing portal. You revert to the Free plan at the end of the paid period.

3. If you’re over Free’s limits, writes will be refused until you’re under them.

4. To leave entirely, delete the organization (OWNER only).

Danger

Deleting an organization removes its repositories and metadata. Managed-storage bytes are garbage-collected and unrecoverable. BYOS objects stay in your bucket. Cancelling the subscription and deleting the organization are separate actions — do both if you want billing to stop and the data gone.

Invoices and tax

Invoices, receipts, VAT/GST handling and billing addresses are all in the provider’s portal. CAVS stores only a reference to the subscription, never card details.

For annual billing, purchase orders, custom terms or an SLA, contact sales about the Business plan.

Audit trail

Every billing action is recorded in the audit log: billing.checkout_started, billing.subscription_updated, billing.byos_addon_updated — with actor and IP.

curl -sS "https://cavsnode.com/api/v1/organizations/acme-ai/audit" -H "$H" \
  | jq '.events[] | select(.action | startswith("billing."))'

Next

• Plans & quotas — what each plan includes.
• Usage & metering — reducing the bill.
• Tokens, webhooks & billing — the endpoint reference.