Customer Billing Overview - Naïve

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 agent profile Billing (credits).

Endpoints

Method	Path	Description
`GET`	`/v1/plans`	List plan definitions (company)
`POST`	`/v1/plans`	Create / update a plan (upsert by `key`)
`GET`	`/v1/users/:user_id/billing/subscription`	Get a tenant’s subscription
`PUT`	`/v1/users/:user_id/billing/subscription`	Set a tenant’s subscription (optionally assign the plan’s kit)
`GET`	`/v1/users/:user_id/billing/usage`	Current-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.