Skip to content

Billing ​

Programmatic access to your account's credit balance, transactions, invoices, per-call cost breakdowns, and spend alerts. Account billing in Studio is Account → Billing.

Secret keys, including legacy rymi_ keys, can no longer call billing writes (POST /v1/billing/checkout/start, POST /v1/billing/mandate/register, POST /v1/billing/reconcile, PUT /v1/billing/auto-recharge, PUT /v1/billing/extra-usage, PUT /v1/billing/alerts, PUT /v1/billing/country, DELETE /v1/billing/payment-methods/:id). Those return 403 scope_missing. Billing reads need billing:read. To add credits, top up in Studio. See API keys and scopes.

Rymi bills per minute of connected call audio against a prepaid credit balance, charged in 30-second increments rounded up. A 0–30s call bills 30 seconds, 31–60s bills one minute, and so on. Failed calls (busy, no-answer) don't bill. Only calls that connect and exchange audio do.

Pricing model ​

Every agent is billed on one of two tracks, set by its agent_kind:

  • Custom (agent_kind: "custom", the default): you choose the STT, LLM, and TTS models yourself. Billed at component cost (the sum of the per-minute rate of each model in the stack) plus the Rymi runtime fee. Managed from $0.035/min, or BYO providers at cost plus $0.02/min runtime. Channels where you bring your own API key (BYOK) contribute $0 to the component cost, but the runtime fee always applies. Use Estimate to price a stack before dialing.
  • Managed (agent_kind: "managed"): a ready-made agent on a tuned, locked stack (speech, model, and voice chosen for you). Billed at the SKU's fixed published price_per_min. List the available SKUs and their prices with List Managed SKUs.

Paid monthly plans (Starter $49/mo · 4,900 credits · 5% off, Scale $199/mo · 19,900 credits · 10% off, Business $999/mo · 99,900 credits · 15% off) discount every managed SKU (including Realtime Pro) and the $0.02/min custom agent runtime fee while active. Credits roll over and never expire. Buy a plan in Studio under Account → Billing or through checkout.


List Managed SKUs ​

GET/v1/managed-skus

Returns the active Rymi Managed agent SKUs your workspace can use, each with its effective per-minute price and locked STT/LLM/TTS stack. SKUs limited to other countries are left out of skus (see Country availability). Create a managed agent by passing the chosen managed_sku_id (with agent_kind: "managed") to Create Agent.

Response 200 ​

json
{
  "skus": [
    {
      "id": "mgd-...",
      "label": "...",
      "bestFor": "...",
      "description": "...",
      "features": ["..."],
      "pricePerMin": 0.05,
      "effectivePricePerMin": 0.05,
      "stt": { "provider": "...", "model": "..." },
      "llm": { "provider": "...", "model": "..." },
      "tts": { "provider": "...", "model": "..." },
      "voice": "...",
      "supportedLanguages": ["en-US"],
      "allowedCountries": null,
      "featuredCountries": null,
      "featured": true,
      "isActive": true,
      "sortOrder": 10
    }
  ],
  "restricted": [
    { "id": "mgd-...", "label": "...", "allowedCountries": ["IN"] }
  ],
  "country": "US"
}

Every value above is illustrative. The label, bestFor, description, features, the locked stt/llm/tts/voice stack, the price, and the ordering are all read from the SKU catalog and change without notice. Don't hard-code any of them. Read what List Managed SKUs returns.

Country availability ​

Some SKUs are limited to specific countries. The managed Hindi SKUs are available in India only. The English SKUs are available everywhere. allowedCountries is a list of ISO 3166-1 alpha-2 codes, or null when the SKU has no country limit.

Rymi checks your workspace's operating country (Settings → Compliance), and falls back to the account's billing country when no operating country is set. country in the response is the one it used, or null when neither is set.

  • skus lists only SKUs you can use. A workspace with no country set does not see country-limited SKUs.
  • featured is true when Studio shows the SKU up front for your country, and false when it lists it under "More agents". A false SKU is still available: you can create, switch to and call with it. featuredCountries is the list of countries it is featured in, or null for every country it is available in.
  • restricted lists the SKUs left out, so a client can say why.
  • To unlock the Hindi SKUs, set the operating country to IN with PUT /v1/compliance/settings.

Agent templates follow the same rule. GET /v1/agent-templates leaves out a template whose allowedCountries does not include your workspace's country, and a workspace with no country does not see country-limited templates. Today the Hindi real estate lead qualifier is the only one, and it is offered in India only.

Picking a SKU is strict: Create Agent and POST /v1/agents/:id/apply-managed-sku reject a workspace whose country is not allowed, or not set, with 403 and code sku_not_available_in_country. Publishing and starting calls only reject a workspace whose country is known and not allowed, so agents already running in a workspace that never set a country keep working.

json
{
  "error": "Hindi · Standard is only available in IN. This workspace operates in GB.",
  "code": "sku_not_available_in_country",
  "allowed_countries": ["IN"],
  "country": "GB"
}

supportedLanguages is the list of BCP-47 language tags the SKU's stack supports (e.g. en-US, hi-IN), not bare language codes. pricePerMin may be null for a SKU whose price is not yet set; effectivePricePerMin is the display-safe equivalent (the explicit pricePerMin, or 0 when it is null).


Get Balance ​

GET/v1/billing/balance

Returns the tenant's current credit balance plus the composition signals the dashboard uses to render the right headline format (runway estimate, low-balance tone, onboarding state, etc.).

Response 200 ​

json
{
  "tenant_id": "550e8400-...",
  "balance_seconds": 25714,
  "balance_usd": 15.0,
  "balance_cents": 1500,
  "balance_credits": 1500,
  "estimated_minutes_remaining": 428,
  "topup_minutes_remaining": 60,
  "is_active": true,
  "tone": "ok",
  "tenant_state": "has_calls",
  "recent_daily_spend_usd": 1.20,
  "runway_days_estimate": 12
}
FieldDescription
balance_secondsRemaining seconds in the active credit bucket, estimated at the lowest managed rate (3.5¢/min), so it is the most talk time the bucket can buy. The active bucket is the included plan quota while any remains, then top-up credits
balance_usdThe active bucket in USD
balance_centsThe active bucket in cents (1 credit = 1 cent = $0.01)
balance_creditsTotal remaining credits across both buckets (included quota + top-up)
purchased_creditsTop-up bucket in cents (purchased credit that survives the included quota reset)
free_creditsIncluded monthly-allowance bucket in cents
estimated_minutes_remainingThe active bucket in whole minutes at the lowest managed rate (3.5¢/min). Agents on pricier stacks get fewer
topup_minutes_remainingTop-up bucket only, in minutes. Purchased credit that survives the included quota reset
is_activeThe tenant's account-active DB flag. It is independent of balance and stays true at a zero or negative balance; tone is the balance-derived signal in this response
toneUI hint: ok, low (under 1,800 seconds), or critical (under 300 seconds or inactive). Reflects total balance (included quota + top-up), so a draining included bucket doesn't false-alarm when top-up credit remains
tenant_stateno_agents, agents_no_calls, or has_calls
recent_daily_spend_usdAverage daily spend over the last 7 days. Only set when every one of those 7 days had a billable call and total spend is above zero; otherwise null. A long-established tenant with one idle day in the window gets null
runway_days_estimatebalance_usd / recent_daily_spend_usd, only set when both are populated

List Transactions ​

GET/v1/billing/transactions

Per-tenant credit ledger: top-ups, monthly grants, refunds, and per-call deductions.

Query Parameters ​

ParameterTypeDefaultDescription
limitinteger50Max records (cap 200)
fromISO date-Inclusive lower bound on created_at
toISO date-Inclusive upper bound on created_at (extended to end of day)

Response 200 ​

json
{
  "transactions": [
    {
      "id": "tx_...",
      "call_id": null,
      "amount_seconds": 36000,
      "amount_usd": 30.0,
      "transaction_type": "stripe_topup",
      "description": "Top-up via Stripe",
      "metadata": {},
      "created_at": "2026-04-01T10:00:00Z"
    }
  ]
}

Per-call deductions carry the call_id they were billed against; top-ups and grants have call_id: null.


List Invoices ​

GET/v1/billing/invoices

Cursor-paginated list of invoices for the tenant.

Query Parameters ​

ParameterTypeDefaultDescription
limitinteger25Max records (cap 100)
cursorstring-Resume token returned in next_cursor

Response 200 ​

json
{
  "invoices": [
    {
      "id": "161bcec1-1108-4e9a-b8b0-0449af48c7d7",
      "invoice_number": "RYMI-2026-00000042",
      "tenant_id": "550e8400-e29b-41d4-a716-446655440000",
      "kind": "topup",
      "status": "paid",
      "currency": "USD",
      "subtotal_minor": 3000,
      "tax_minor": 0,
      "discount_minor": 0,
      "total_minor": 3000,
      "gateway": "stripe",
      "gateway_invoice_id": null,
      "payment_event_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "period_start": null,
      "period_end": null,
      "issued_at": "2026-04-01T10:00:00Z",
      "paid_at": "2026-04-01T10:00:05Z",
      "voided_at": null,
      "billing_snapshot": {
        "buyer_name": "Sharma Dental",
        "buyer_email": null,
        "buyer_phone": "+919800000002",
        "buyer_country": "IN",
        "buyer_tax_id": null,
        "buyer_tax_id_type": null
      }
    }
  ],
  "next_cursor": null
}

billing_snapshot records who was billed when the invoice was issued. Later account changes don't alter it. Any buyer field can be null; an account with only a phone number has no buyer_email. Older invoices can have an empty snapshot. AED and SAR invoices also carry reverse_charge and the VAT and FX details.

All monetary amounts (subtotal_minor, tax_minor, discount_minor, total_minor) are integer minor units in the invoice's own currency: cents for USD, paise for INR. The currency is copied from the originating payment event and never converted.

Ids are UUIDs, not prefixed strings. gateway_invoice_id is populated for subscription cycles only; top-up invoices leave it null, as do period_start and period_end.

Get Invoice ​

GET/v1/billing/invoices/:id

Returns the invoice plus its line items.

Response 200 ​

json
{
  "invoice": { "id": "161bcec1-1108-4e9a-b8b0-0449af48c7d7", "invoice_number": "RYMI-2026-00000042", "status": "paid", "currency": "USD", "total_minor": 3000 },
  "items": [
    {
      "id": "9f8c2b41-5d3e-4a17-9c6b-2e8d1a4f7b30",
      "invoice_id": "161bcec1-1108-4e9a-b8b0-0449af48c7d7",
      "kind": "topup",
      "description": "Top-up",
      "quantity": 1,
      "unit_amount_minor": 3000,
      "amount_minor": 3000,
      "plan_id": null,
      "credit_transaction_id": "3d594650-52c4-4f59-a9b1-c8f6d2e7a913"
    }
  ]
}

Invoice and line-item amounts are integer minor units (cents for USD).

StatusMeaning
404Invoice does not exist for this tenant

Per-Call Cost Breakdown ​

GET/v1/billing/calls

Lists recent calls with per-call cost metadata. Use it to reconcile against your own records.

Query Parameters ​

ParameterTypeDefaultDescription
limitinteger50Max records (cap 200)
fromISO date-Inclusive lower bound on started_at
toISO date-Inclusive upper bound on started_at
agent_idstring-Filter to a single agent

Response 200 ​

json
{
  "calls": [
    {
      "id": "call_...",
      "started_at": "2026-04-01T10:00:00Z",
      "agent_id": "agent_...",
      "agent_name": "Support Bot",
      "duration_seconds": 145,
      "customer_revenue": 0.29,
      "provider_cost": 0.07,
      "gross_margin": 0.22
    }
  ]
}

Export CSV ​

GET/v1/billing/export.csv

Downloads up to 5,000 calls as CSV. Filterable by date range, agent, and call status.

Query Parameters ​

ParameterTypeDescription
fromISO dateInclusive lower bound on started_at
toISO dateInclusive upper bound on started_at
agent_idstringFilter to a single agent
statusstringFilter by call status (completed, failed, …)

Returns text/csv with header row:

call_id,started_at,agent_id,duration_seconds,customer_revenue_usd,provider_cost_usd,gross_margin_usd

Spend Alerts ​

GET/v1/billing/alerts
PUT/v1/billing/alerts

Configure threshold-based spend alerts.

PUT Request Body ​

FieldTypeDescription
thresholds_usdnumber[]Spend thresholds in USD (max 10)
low_balance_pctinteger (0–100)Alert when remaining balance ≤ this percent of last top-up
email_enabledbooleanWhether to email the alert

GET Response 200 ​

json
{ "thresholds_usd": [50, 100], "low_balance_pct": 20, "email_enabled": true }

Tenants that have never saved preferences get the defaults shown above.

PUT Response 200 ​

json
{ "ok": true }

Spend-Velocity Alerts ​

GET/v1/billing/spend-alerts
POST/v1/billing/spend-alerts/:id/acknowledge

Returns un-acknowledged spend-velocity alerts (Phase 2B safety net) and the most recent ten acknowledged ones, plus an endpoint to dismiss a banner.

GET Response 200 ​

json
{
  "unacknowledged": [
    { "id": "alert_...", "alert_type": "spend_velocity", "severity": "critical", "amount_usd": 12.5, "threshold_usd": 10.0 }
  ],
  "recent": []
}

Acknowledging returns { "id": "...", "acknowledged_at": "..." }, or 404 if the alert doesn't exist, was already acknowledged, or belongs to another tenant.


Estimate ​

POST/v1/billing/estimate

Prices a custom model stack: the sum of each channel's per-minute component cost plus the Rymi runtime fee. Managed from $0.035/min, or BYO providers at cost plus $0.02/min runtime. The studio's call-planner uses it. Managed agents don't need an estimate; their price is the SKU's fixed price_per_min, returned by List Managed SKUs.

Request Body ​

FieldTypeDescription
stt_modelstringSpeech-to-text model ID
llm_modelstringLanguage model ID (a realtime model covers STT/TTS too; leave those empty)
tts_modelstringText-to-speech model ID
duration_secondsnumberOptional; when provided, est_for_duration_usd is included in the response

Omitting a channel (or bringing your own key for it) drops that component to $0, but the Rymi runtime fee always applies.

Response 200 ​

json
{
  "agent_kind": "custom",
  "rate_per_min": 0.0569,
  "est_for_duration_usd": 0.1708
}

Usage Summary ​

GET/v1/billing/usage-summary

Lane-aware usage summary across the three metered surfaces: voice runtime (in minutes, the customer-facing unit), Studio AI units, and post-call intelligence units. The dashboard's usage cards render this, and the SDKs' billing.usage_summary() returns it.

Response 200 ​

json
{
  "voice_runtime": { "remaining_minutes": 300, "status": "ok" },
  "studio_ai": {
    "used_units": 12,
    "included_units": 100,
    "quota_percent": 12,
    "status": "ok",
    "overage_enabled": false
  },
  "post_call_intelligence": {
    "status": "quota",
    "used_units": 4,
    "included_units": 50,
    "quota_percent": 8
  }
}

Plan & Billing State ​

GET/v1/billing/plans
GET/v1/billing/plan
POST/v1/billing/checkout/start
POST/v1/billing/plan/cancel
POST/v1/billing/plan/downgrade

The dashboard uses these to list available plans, read the current plan state, start prepaid top-up or plan checkout, and manage scheduled cancellations or downgrades.

bash
curl https://api.rymi.live/v1/billing/plans \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X POST https://api.rymi.live/v1/billing/plan/downgrade \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "plan_id": "starter" }'
ts
const { plans } = await rymi.billing.listPlans();
const plan = await rymi.billing.getPlan();
await rymi.billing.downgradePlan({ plan_id: "starter" });
await rymi.billing.cancelPlan();
python
plans = rymi.billing.list_plans()["plans"]
plan = rymi.billing.get_plan()
rymi.billing.downgrade_plan("starter")
rymi.billing.cancel_plan()

GET /billing/plans Response 200 ​

Lists the plans you can buy, cheapest first. Returns 404 while monthly plans are switched off.

json
{
  "plans": [
    { "id": "free", "display_name": "Pay As You Go", "monthly_fee_cents": 0, "credits": 0, "usage_discount_pct": 0, "max_workspace_seats": 1, "support_tier": "community" },
    { "id": "starter", "display_name": "Starter", "monthly_fee_cents": 4900, "credits": 4900, "usage_discount_pct": 5, "max_workspace_seats": 3, "support_tier": "email" },
    { "id": "scale", "display_name": "Scale", "monthly_fee_cents": 19900, "credits": 19900, "usage_discount_pct": 10, "max_workspace_seats": null, "support_tier": "priority_email" },
    { "id": "business", "display_name": "Business", "monthly_fee_cents": 99900, "credits": 99900, "usage_discount_pct": 15, "max_workspace_seats": null, "support_tier": "priority_email" }
  ]
}

credits is what the plan adds to your wallet (1 credit = $0.01). max_workspace_seats: null means no seat limit.

GET /billing/plan Response 200 ​

json
{
  "plan_id": "free",
  "plan": { "id": "free", "display_name": "Free", "monthly_credit_cents": 100, "byok_allowed": false },
  "monthly_credit_remaining_cents": 80,
  "monthly_credit_resets_at": "2026-05-01T00:00:00Z",
  "topup_balance_cents": 1500,
  "extra_usage_enabled": true,
  "plan_active_since": "2026-04-01T00:00:00Z",
  "preferred_gateway": "razorpay",
  "preferred_currency": "USD",
  "billing_country": "IN",
  "billing_country_locked": false,
  "usd_to_inr_rate": 84.0,
  "billing_mode": "prepaid_only"
}

While monthly plans are switched on, the response also carries:

FieldTypeDescription
period_endstring or nullWhen the current 30-day pass ends
auto_renewbooleantrue when a saved card or UPI mandate will renew the pass
pending_plan_idstring or nullPlan that takes over at the next renewal, after a downgrade
usage_discount_pctnumberDiscount on call rates right now (0, 5, 10 or 15)
last_30d_spend_centsnumberCall spend across all your workspaces in the last 30 days, in credits

billing_mode is prepaid_with_plan while a paid plan is active and prepaid_only otherwise.

billing_country is an ISO code or null until you set one. billing_country_locked is true when a country is saved and the workspace has a paid invoice. It is false when billing_country is null, even if a paid invoice exists. Studio reads these for Settings → Billing and for the country field on a top-up.

POST /billing/checkout/start Body ​

Send pack_usd for a top-up or plan_id for a plan, never both.

FieldTypeRequiredDescription
pack_usdnumberone of the twoDollar value to add to the prepaid wallet, 1 to 10000
plan_idstringone of the twostarter, scale or business. Buys a 30-day pass at the plan's price; any amount you send is ignored
billing_countrystringnoISO country code used for gateway selection. After the first paid invoice, a value other than the saved billing country returns 409 billing_country_locked
tax_idstringnoTax identifier used for gateway selection
save_cardbooleannoRegister the card for auto-recharge and plan renewal when supported

Returns a Razorpay order payload for India-region checkout or a Stripe Checkout URL when Stripe checkout is enabled for the tenant region. Plans are sold through Razorpay only.

Buying the plan you already have starts a fresh 30 days and adds its credits. Buying a more expensive plan switches you to it straight away. To move to a cheaper plan, use downgrade.

POST /billing/plan/cancel and POST /billing/plan/downgrade ​

Owner or Billing role. A secret key for the workspace counts as the owner. Both return 404 while monthly plans are switched off.

  • POST /billing/plan/cancel stops renewal. You keep the plan and its discount until period_end, then move to Pay As You Go. Credits stay in the wallet. Returns { "ok": true, "cancel_at_period_end": true }.
  • POST /billing/plan/downgrade takes { "plan_id": "starter" } (any active plan cheaper than yours, including free) and sets pending_plan_id. The renewal charges the cheaper plan. Returns { "ok": true, "pending_plan_id": "starter" }.

Errors ​

StatusMeaning
400Provide either pack_usd or plan_id: the checkout body had both or neither
400invalid_plan: the plan does not exist, is not for sale, or monthly plans are switched off
400use_downgrade: checkout for a plan cheaper than your current one. Call POST /billing/plan/downgrade instead
400plan_gateway_unsupported: plan checkout resolved to Stripe. Plans are sold through Razorpay only
400no_active_plan: cancel or downgrade with no paid plan
400not_a_downgrade: the downgrade target costs the same as or more than your current plan
403role_forbidden: your role cannot buy, cancel or downgrade
409billing_country_locked. The body is { "error": "billing_country_locked", "billing_country": "IN" } with no code field. Sent when the workspace has a saved billing country and a paid invoice, and this request's billing_country is a different country. Omit billing_country, or send the saved one, and checkout continues
503Gateway not configured (missing Stripe / Razorpay env)

Set billing country ​

PUT/v1/billing/country

Owner only. A secret key for the workspace counts as the owner. Admins and the client role get 403 role_forbidden. Sets the country that drives currency, gateway, and tax treatment. Past invoices keep the country they were issued with.

You can change it until the workspace has a paid invoice. After that, sending a different country returns 409. Sending the saved country again returns 200.

In Studio this is the Billing country block under Settings → Billing. While it is unlocked, the dropdown lists the eight supported countries. After the lock, Studio shows the country name and "Contact support to change it." The top-up dialog disables its country field and says "Locked after your first paid invoice. Contact support to change it."

Request body ​

FieldTypeRequiredDescription
billing_countrystringYesTwo-letter ISO code: US, IN, AE, SA, QA, KW, BH, or OM. Stored upper case

Example ​

bash
curl -X PUT https://api.rymi.live/v1/billing/country \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "billing_country": "IN" }'
ts
const result = await rymi.billing.setCountry("IN");
python
result = rymi.billing.set_country("IN")

Response 200 ​

json
{ "ok": true, "billing_country": "IN" }

Errors ​

StatusCodeMeaning
400unsupported_country{ "error": "Unsupported country" }
400billing_country missing, or not exactly two characters
401Missing or invalid API key. The handler's body is { "error": "Missing authentication context" } when the session has no user
403role_forbidden{ "error": "Your role in this workspace does not allow this" }
403Publishable key: { "error": "Publishable keys cannot change billing" }
409billing_country_locked{ "error": "Billing country is locked after the first paid invoice. Contact support to change it.", "code": "billing_country_locked", "billing_country": "IN" }. billing_country in the body is the saved country

Top-Up Packs ​

GET/v1/billing/topup-packs

Lists the active top-up packs (with any volume bonus) the dashboard offers on the checkout screen.

Response 200 ​

json
{
  "packs": [
    {
      "id": "pack_...",
      "display_name": "Top-up pack",
      "price_cents": 3000,
      "bonus_cents": 0,
      "sort_order": 0
    }
  ]
}

Payment Methods ​

GET/v1/billing/payment-methods
DELETE/v1/billing/payment-methods/:id

List the tenant's saved payment methods, or detach one. Detaching soft-deletes the method and best-effort detaches it on the gateway; if it was the only remaining method, auto-recharge is switched off.

GET Response 200 ​

json
{
  "payment_methods": [
    {
      "id": "pm_...",
      "gateway": "razorpay",
      "method_type": "card",
      "upi_vpa": null,
      "card_brand": "visa",
      "card_last4": "4242",
      "card_country": "IN",
      "is_default": true,
      "created_at": "2026-04-01T10:00:00Z"
    }
  ]
}

DELETE Response 200 ​

json
{ "ok": true }
StatusMeaning
404Payment method not found for this tenant

Auto-Recharge ​

GET/v1/billing/auto-recharge
PUT/v1/billing/auto-recharge

Read or update automatic top-up: when the balance falls below threshold_usd, Rymi charges the saved method for pack_usd. For Razorpay tenants, auto-recharge requires a confirmed e-mandate (see Register Mandate).

GET Response 200 ​

json
{
  "enabled": true,
  "pack_usd": 30,
  "threshold_usd": 5,
  "gateway": "razorpay",
  "mandate_required": true,
  "has_mandate": true,
  "billing_phone": "+15551234567"
}

PUT Request Body ​

All fields optional; only provided fields are changed.

FieldTypeDescription
enabledbooleanTurn auto-recharge on or off
pack_usdnumber (1–1000)Dollar value to recharge each time
threshold_usdnumber (0–100)Balance level that triggers a recharge

pack_usd must be greater than threshold_usd, otherwise a 400 is returned (a smaller pack would immediately re-trigger a recharge loop).

PUT Response 200 ​

json
{ "ok": true }
StatusMeaning
400pack_usd is not greater than threshold_usd

Register Mandate ​

POST/v1/billing/mandate/register

Creates a Razorpay order that registers a recurring e-mandate alongside an immediate first charge. The frontend opens Razorpay Checkout with the returned order_id; bank-side OTP confirms the mandate, and a webhook persists the token.

Request Body ​

FieldTypeRequiredDescription
first_charge_usdnumber (1–10000)yesAmount charged immediately when the mandate is set up
max_amount_usdnumber (1–10000)yesMaximum per-debit cap for future recurring charges. Must be ≥ first_charge_usd
contactstringyesBilling phone (7–20 chars), required by Razorpay for recurring debits
methodstringnocard or upi

Response 200 ​

json
{
  "gateway": "razorpay",
  "razorpay": {
    "order_id": "order_...",
    "key_id": "rzp_...",
    "amount": 250000,
    "currency": "INR",
    "customer_id": "cust_..."
  }
}
StatusMeaning
400max_amount_usd is less than first_charge_usd
404Tenant not found
503Razorpay gateway not configured

Extra Usage ​

GET/v1/billing/extra-usage
PUT/v1/billing/extra-usage

Controls whether the tenant's purchased top-up balance is spent once the included plan quota is exhausted. When off, usage stops at the included quota.

GET Response 200 ​

json
{ "enabled": true }

PUT Request Body ​

FieldTypeRequiredDescription
enabledbooleanyesWhether top-up balance covers usage beyond the included quota

PUT Response 200 ​

json
{ "ok": true }