The rivano.billing resource gives you programmatic access to plan information, usage limits, and Stripe checkout flows — useful for building upgrade prompts or usage dashboards in your own tooling.

Billing status

Returns the current plan, usage, and limits for the tenant:

import Rivano from '@rivano/sdk';

const rivano = new Rivano({ apiKey: 'rv_...' });

const status = await rivano.billing.status();

console.log('Plan:', status.plan);
console.log('Subscription:', status.stripeSubscriptionId ?? 'none');
console.log('Trial ends:', status.trialEndsAt ?? 'not on trial');

console.log('Usage:');
console.log('  Traces this month:', status.usage.tracesThisMonth);
console.log('  Agents:', status.usage.agents);

console.log('Limits:');
console.log('  Max traces/month:', status.limits.tracesPerMonth);
console.log('  Max agents:', status.limits.agents);

import requests

response = requests.get(
    'https://api.rivano.ai/api/billing/status',
    headers={'Authorization': 'Bearer rv_...'},
)
status = response.json()
print('Plan:', status['plan'])
print('Traces this month:', status['usage']['tracesThisMonth'])
print('Max traces/month:', status['limits']['tracesPerMonth'])

curl https://api.rivano.ai/api/billing/status \
  -H "Authorization: Bearer rv_..."

Status response fields

Field	Type	Description
`plan`	`string`	Current plan: `free`, `pro`, `team`, `enterprise`
`stripeSubscriptionId`	`string \| null`	Stripe subscription ID (null if no subscription)
`trialEndsAt`	`string \| null`	ISO 8601 trial expiry date, or null
`usage.tracesThisMonth`	`number`	Traces consumed in the current billing period
`usage.agents`	`number`	Active agent count
`limits.tracesPerMonth`	`number`	Monthly trace cap for current plan
`limits.agents`	`number`	Maximum active agents for current plan

Create a checkout session

Generates a Stripe-hosted checkout URL to upgrade the tenant to a paid plan:

import Rivano from '@rivano/sdk';

const rivano = new Rivano({ apiKey: 'rv_...' });

const { url } = await rivano.billing.createCheckout('pro');

// Redirect the user to complete payment
console.log('Checkout URL:', url);
// e.g. window.location.href = url;

import requests

response = requests.post(
    'https://api.rivano.ai/api/billing/checkout',
    headers={
        'Authorization': 'Bearer rv_...',
        'Content-Type': 'application/json',
    },
    json={'plan': 'pro'},
)
print('Checkout URL:', response.json()['url'])

curl https://api.rivano.ai/api/billing/checkout \
  -X POST \
  -H "Authorization: Bearer rv_..." \
  -H "Content-Type: application/json" \
  -d '{"plan": "pro"}'

Available plans for createCheckout: pro, team, enterprise.

Create a billing portal session

Generates a Stripe-hosted customer portal URL where the tenant can manage their subscription, invoices, and payment method:

import Rivano from '@rivano/sdk';

const rivano = new Rivano({ apiKey: 'rv_...' });

const { url } = await rivano.billing.createPortal();
console.log('Portal URL:', url);

import requests

response = requests.post(
    'https://api.rivano.ai/api/billing/portal',
    headers={'Authorization': 'Bearer rv_...'},
)
print('Portal URL:', response.json()['url'])

curl https://api.rivano.ai/api/billing/portal \
  -X POST \
  -H "Authorization: Bearer rv_..."

⚠

Checkout and portal URLs expire after 24 hours. Generate them immediately before redirecting the user — do not cache them.

Error handling

Error	When it occurs
`SdkAuthError`	Invalid API key
`SdkForbiddenError`	Only tenant admins can access billing
`SdkError`	Invalid plan name or Stripe configuration error

SDK Costs — Cost breakdowns and budget alerts within the current plan
SDK Keys — API key management

SDK — Billing

Billing status

Status response fields

Create a checkout session

Create a billing portal session

Error handling

Related