Skip to content

Billing And Entitlements

Last refreshed: 2026-05-18

Concepts

Anuva uses plans, content entitlements, wallets, transactions, credit packs, AI interaction records, and Zoho Billing integration.

Billing state is stored in Payload collections under src/collections/anuvax/index.ts.

Plans

subscription_plans includes Zoho plan mapping, render/content limits, support level, and silverCoinsPerMonth.

The initial free/basic plan constants live in src/lib/coins/free-tier.ts.

Current free/basic behavior treats initial content as included and sets unlock cost to zero.

flowchart LR
  zoho["💳 Zoho Billing"] --> customer["zoho_billing_customers"]
  zoho --> webhooks["zoho_webhook_events"]
  plans["subscription_plans"] --> subscription["user_subscriptions"]
  subscription --> entitlements["content_entitlements"]
  packs["credit_packs"] --> purchases["credit_pack_purchases"]
  purchases --> wallet["credit_wallets"]
  wallet --> transactions["credit_transactions"]

Gold Coins

Gold Coins are used for AI and generation metering.

Key files:

  • src/lib/coins/metering.ts
  • ai_interactions
  • credit_wallets
  • credit_transactions
  • credit_packs
  • credit_pack_purchases
  • ai_model_conversion_rates

AI metering records provider/model/action metadata, checks Gold wallet balance for billable non-admin actions, and links successful or failed interactions to transaction records where applicable.

Silver Coins

Silver Coin allocation currently lives on subscription plans. Before extending Silver behavior, verify whether there is active wallet/transaction usage or only plan-level allocation.

Entitlements

content_entitlements grants access to set variants, bot variants, or similar content. Entitlements can be linked to transactions and scoped to workspace/user.

Content store surfaces are in:

  • src/app/(frontend)/app/content-store
  • sets, set_variants, bots, bot_variants

Zoho Billing

Zoho integration files:

  • src/lib/billing/zoho/config.ts
  • src/lib/billing/zoho/client.ts
  • src/lib/billing/zoho/webhooks.ts
  • src/lib/billing/zoho/reconciliation.ts
  • src/app/api/zoho-billing/webhook/route.ts
  • scripts/zoho-billing-reconcile.ts

Zoho-related collections:

  • zoho_billing_customers
  • zoho_webhook_events
  • billing_reconciliation_reports

Webhook handling must remain idempotent, especially for paid Gold Coin grants.

Payment Provider Environment

Zoho config keys are documented in .env.example and active .env includes the same core keys. Never log secrets or copy values into docs.