Core Concepts

Tanso has a small set of entities that work together to track usage, control access, and handle billing. This page explains each from your perspective as an integrator — what it is, why it matters, and how it connects to the rest.

Some concepts apply in both Observe and Platform mode. Others are Platform-only. Each section notes which.

---

How Everything Connects

Customer is the root. In Observe mode, you send Events to track cost and revenue per customer and feature. In Platform mode, you also create Plans that bundle Features with pricing, subscribe customers to plans via Subscriptions, gate access with Entitlements, and collect payment through Invoices. Credits provide an alternative to per-unit billing.

---

Customer

Observe + Platform

A customer represents one of your end users or accounts. Three ways to identify customers:

• customerReferenceId — your internal ID (any string). Works in both Observe and Platform mode.
• stripeCustomerId — your Stripe customer ID (cus_...). Preferred for Observe mode — Tanso pulls name and email from Stripe automatically.
• customerId — Tanso's internal UUID. Returned after creating a customer via the API.

Use one per event, not multiple.

Customers are the root object. Subscriptions, events, entitlements, credit pools, and invoices all belong to a customer. You can register customers explicitly (with name and email for dashboard analytics) or let Tanso auto-create them the first time you send an event with an unknown identifier.

---

Event

Observe + Platform

An event is a single usage record — one API call, one chat completion, one file processed. Events are the foundation for everything: cost tracking in Observe mode, and metered billing in Platform mode.

Each event includes:

• eventName and featureKey — what happened and which feature it maps to
• Customer ID — who did it (customerReferenceId, stripeCustomerId, or customerId)
• usageUnits — how much (tokens, API calls, storage GB, etc.)
• costInput — pass model and modelProvider with inputTokens and outputTokens for accurate two-rate cost calculation. Tanso looks up current pricing automatically. Or pass costAmount directly if you have negotiated rates.
• revenueAmount — what you charged your customer, for margin analysis

Every event requires an eventIdempotencyKey. Duplicates return HTTP 409 — safe to retry on network failure without double-counting.

In Observe, events power your analytics dashboards. In Platform, events also feed into invoice calculations for usage-based features.

---

Feature

Observe + Platform

A feature is a capability you track or gate — ai_summarization, api_calls, seats, or anything else you want to meter.

Each feature has a unique key string. You pass this key when ingesting events (featureKey) and when checking entitlements. In Observe mode, features organize your analytics into per-feature cost and revenue breakdowns.

In Platform mode, features are linked to plans with pricing rules. Three pricing types are available:

• Included — bundled in the plan's base price, no per-unit charge
• Usage-based — charged per unit of consumption
• Graduated — tiered pricing with per-tier rates and optional flat fees

---

Plan

Platform only

A plan is a pricing bundle that packages features together with a base price. Plans define:

• Base price and currency — what the subscription costs per period
• Billing interval — how often to charge (monthly, quarterly, annual)
• Billing timing — IN_ADVANCE (charged at the start of the period) or IN_ARREARS (charged at the end)
• Feature pricing — each linked feature has its own pricing configuration (included, usage-based, or graduated)
• Credit allocations — optional credit grants included with the plan

Use the List Plans endpoint to power your pricing pages dynamically — no need to hardcode plan details on your frontend.

---

Subscription

Platform only

A subscription links a customer to a plan. It represents an active billing relationship and defines the customer's current billing period, grace period, and plan access.

Creating a subscription generates an initial invoice. From there, the lifecycle includes:

• Cancel — immediately or scheduled for end of the current billing period. Scheduled cancellations can be reverted before they take effect.
• Upgrade — takes effect immediately with a new invoice
• Downgrade — scheduled for end of period, then transitions automatically

The grace period controls how many days after an invoice's due date the customer retains access before the subscription is suspended. This gives customers time to resolve payment issues without immediate access loss.

---

Entitlement

Platform only

An entitlement is the real-time answer to "can this customer use this feature?" It's derived from the customer's subscription, plan limits, current usage, and credit balance.

Two ways to check:

• Check (GET) — lightweight boolean gate. No request body. Returns isAllowed with a reason if denied. Use this for high-frequency feature gating where latency matters.
• Evaluate (POST) — full evaluation with optional usage simulation. Before consuming expensive resources, pass usageUnits to simulate whether the request would be permitted — without recording real usage. The response includes wouldExceedLimit so you can decide before committing.

Both return current usage info: used, limit, and remaining. For credit-backed features, the response also includes the credit pool balance.

---

Credit

Platform only

Credits are pre-paid balances that customers draw down as they use your product. The credit system has three parts:

Credit Pool — A named balance with a denomination (e.g., "TOKENS", "credits") and a current balance. Each pool tracks lifetime totals: granted, consumed, expired, and reversed. Pools can be ACTIVE, FROZEN, DEPLETED, or ARCHIVED.

Credit Grant — An allocation of credits into a pool. Grants come from subscriptions, purchases, promotions, or manual adjustments. Each grant can have an expiration date.

Credit Transaction — The audit ledger. Every debit, credit, expiration, and reversal is recorded as an immutable transaction entry.

Key behaviors:

• Rollover policies — NONE (credits expire at period end), FULL (carry forward indefinitely), or CAPPED (carry forward up to a cap)
• Hard limits — when enabled on a pool, access is denied when the balance reaches zero
• Plan allocations — plans can include credit grants that are automatically issued when a customer subscribes

---

Invoice

Platform only

An invoice is a billing document generated automatically from subscriptions — on creation, on renewal, and at the end of metered billing periods for usage-based features.

Invoice statuses follow a lifecycle: PENDING (generated) → DUE (payment window open) → PAID (confirmed). Invoices can also be PAST_DUE, VOID, or CANCELLED.

Two paths to collect payment:

• Stripe Checkout — generate a hosted payment page URL and redirect your customer. No custom payment form needed.
• Mark as paid — for bank transfers, enterprise invoicing, or any payment collected outside Stripe, mark the invoice as paid via the API to activate the subscription.

Usage charges from events accumulate during the billing period and appear as line items on the next invoice.

---

What's Next

• Quickstart: Observe — start tracking cost and revenue in 5 minutes
• Quick Start: Platform — set up plans, subscriptions, and billing
• API Reference — full endpoint documentation