Skip to main content
Monetize your own SaaS customers: define plans (plan → Account Kit + per-primitive quotas), subscribe each tenant user, and Naive meters usage and enforces quotas. Distinct from your own operator Billing (credits).

​
Endpoints

MethodPathDescription
GET/v1/plansList plan definitions (company)
POST/v1/plansCreate / update a plan (upsert by key)
GET/v1/users/:user_id/billing/subscriptionGet a tenant’s subscription
PUT/v1/users/:user_id/billing/subscriptionSet a tenant’s subscription (optionally assign the plan’s kit)
GET/v1/users/:user_id/billing/usageCurrent-period usage rollup + quotas

​
Plans

curl -X POST https://api.usenaive.ai/v1/plans \
  -H "Authorization: Bearer nv_sk_live_..." -H "Content-Type: application/json" \
  -d '{"key":"pro","name":"Pro","accountKitId":"<kit-id>","stripePriceId":"price_123","quotas":{"seo":1000,"aeo":250},"period":"month"}'
quotas maps a primitive slug to its max calls per period (month | day).

​
Subscription

curl -X PUT https://api.usenaive.ai/v1/users/<user-id>/billing/subscription \
  -H "Authorization: Bearer nv_sk_live_..." -H "Content-Type: application/json" \
  -d '{"planKey":"pro","status":"active","stripeCustomerId":"cus_123","assignKit":true}'
assignKit (default true) also assigns the plan’s Account Kit to the tenant — one call applies tier permissions + quotas. Drive this from your Stripe webhook.

​
Usage & quota enforcement

curl https://api.usenaive.ai/v1/users/<user-id>/billing/usage \
  -H "Authorization: Bearer nv_sk_live_..."

{ "plan": "pro", "status": "active", "period": "month",
  "quotas": { "seo": 1000, "aeo": 250 }, "usage": { "seo": 42, "aeo": 3 } }
Metered primitives (seo, aeo, email) record one usage event per successful call. Exceeding a quota returns 429 rate_limited. Tenants with no subscription are not limited.

​
SDK

await naive.plans.upsert({ key: "pro", name: "Pro", accountKitId, quotas: { seo: 1000 } });
await naive.forUser(userId).billing.setSubscription({ planKey: "pro" });
await naive.forUser(userId).billing.usage();
See the Customer Billing guide and the billing sub-client.