Pricing and Billing

Public Pricing

TutorFlow uses a single platform billing contract with per-unit pricing. You pay for what you generate, not for tier marketing. Pricing is defined by category (the API surface) and a single default tier per category. The full breakdown including unit price, unit count, and total billable amount is echoed back as priceSnapshot on every create response so billing remains stable even after a price change.

Pricing Catalog

Sub-Event Add-Ons

Optional heavy operations are metered independently of the base creation so you only pay for what you actually invoke:

priceSnapshot Shape

Every billable request stores its pricing on the request entity (and returns it on the create response) as a priceSnapshot jsonb blob:

{
  "category": "course",
  "catalogKey": "course.default",
  "tier": "default",
  "unit": "lesson",
  "unitPrice": 0.05,
  "units": 10,
  "amountUsd": 0.50,
  "currency": "USD",
  "source": "platform_pricing_catalog_v2",
  "stripeMeterEventName": "platform_course_lesson_v2"
}

Create responses omit internal stripeLookupKey values. The public GET /v1/platform/pricing-catalog endpoint includes Stripe metadata for operator tooling, but agents should base cost calculations on unit, unitPrice, units, and amountUsd.

Key fields agents should read:

• unit: what one billable unit is (request, lesson, item, slide, scene, image, call, video_minute)
• unitPrice: catalog price per unit (constant for a given category)
• units: count actually billed for this request
• amountUsd: total billable for this request (= unitPrice × units)

For sub-event add-ons (image generation, TTS regen, render), each invocation produces its own PlatformUsageRecord row with its own priceSnapshot. They do NOT roll up into the parent request's snapshot.

Live Pricing

Always-current pricing is available via:

curl https://api.tutorflow.io/v1/platform/pricing-catalog

Backwards Compatibility (tier field)

The tier field on every create endpoint is still accepted for backwards compatibility but has no effect on price after v2. Pricing is single-tier per category.

For new integrations, omit tier from request bodies. If an older client sends it, use only the legacy request values accepted by validation:

• Evaluations: fast, standard, advanced
• Courses, tests, slides, and videos: basic, standard, advanced

Do not send tier: "default" in create requests. default is the public tier shown in priceSnapshot and GET /v1/platform/pricing-catalog.

Why Per-Unit, Not Per-Request

The previous tiered model charged a flat fee per request regardless of how much was generated. A 30-lesson course paid the same as a 3-lesson course, which severely under-priced large requests and over-priced small ones. The v2 catalog aligns the bill with what was actually delivered:

• A 5-lesson course = $0.25; a 30-lesson course = $1.50, proportional to AI cost.
• A 10-item test costs less than a 30-item test, in line with how an agent would expect.
• Slide image generation is opt-in per slide rather than baked into the deck price, so text-only decks no longer subsidize image-heavy ones.

Workspace Credits

Today, the backend tracks:

• workspace credit balances
• optional workspace planCode
• optional workspace billingMode
• per-request usage records (per generation + per sub-event add-on)
• stored priceSnapshot on every request and usage record
• internal billing invoice aggregation for finalized usage
• invoice status sync

It also:

• grants $1.00 in free credits to every new workspace at signup
• allows API usage without a payment method while free credits remain

What Counts As A Billable Event

A billable event is either a completed create-flow generation (counted in units of the category's primary unit) or an explicit sub-event invocation:

All other edit-token mutations are free. Documented PATCH/POST edit-token endpoints for content updates, reorder, scene edits, and similar editor changes do not incur additional charges.

The backend records usage per request and per sub-event with:

• input and output tokens (when applicable)
• provider cost
• internal credit cost
• public price snapshot (category, catalogKey, unitPrice, units, amountUsd)
• billable + finalized USD amounts
• billing status
• request metadata

The priceSnapshot.catalogKey is the easiest field to group on. Post-v2 values are simply evaluation.default, course.default, test_creation.default, slide.default, slide_image.default, video.default, video_tts_regenerate.default, video_render.default.

Internal Credit Ledger

The backend uses internal credits for metering and balance management. Credits are a fixed internal settlement unit beneath the public USD pricing above. They let TutorFlow support monthly included usage, enterprise discounts, and future pricing changes without changing the public contract. Each generation request deducts credits proportional to its USD price (unitPrice × units × USD-to-credit ratio).

Credits are stored as cents: 1 credit = $0.01.

Every new self-serve workspace receives $1.00 (100 cents) in free credits at signup. No payment method is required while free credits remain. Once free credits are exhausted, the workspace must add credits through the TutorFlow checkout page or, when enabled, through x402 USDC deposit top-up. The minimum card checkout purchase is $5 and the maximum is $5,000. Internal manually-created workspaces still start with creditBalance: 0 unless credits are added through internal management flows.

Billing Model

In the current MVP, workspaces maintain a credit balance. Usage records are captured per request and deducted from that balance.

Billing finalization can now pin a USD amount from the stored price snapshot into the usage ledger. This lets TutorFlow separate:

• internal balance deduction via creditCost
• commercial billing via billableAmountUsd and finalizedAmountUsd

The backend now supports two billing execution modes.

internal_invoice

This remains the default.

• usage deducts internal credits
• finalized usage stores billable and finalized USD amounts
• monthly or manual invoice drafts can be created internally
• a Stripe invoice can optionally be created from the internal invoice draft

stripe_metered

This is the new usage-based billing path.

• usage still deducts internal credits for TutorFlow's internal ledger
• finalized usage is also reported to Stripe billing meters keyed off the per-category Stripe meter event names (e.g. platform_course_lesson_v2)
• Stripe invoice items are not manually created by TutorFlow for these workspaces
• internal billing invoices still exist, but they act as audit statements rather than the source of Stripe charges

For Stripe metered billing, the backend expects:

• billingMode = stripe_metered
• a configured billing customer in TutorFlow's billing system

If a meter report fails, the backend stores the error on the usage record and a reconciliation scheduler retries unreconciled finalized usage.

Finalized usage can also be aggregated into an internal billing invoice for a time period. For internal_invoice workspaces, that invoice can optionally create an external invoice through TutorFlow billing.

When a Stripe invoice is created, the backend emits separate invoice items per category (e.g. course.default, slide_image.default) so customers see exactly which API events drove the bill rather than a single aggregated line.

There is also a scheduler in the backend that closes older uninvoiced finalized usage into monthly billing invoice drafts, plus a reconciliation scheduler that retries failed or missing Stripe meter reports for stripe_metered workspaces.

This gives TutorFlow two commercial operating modes today:

• prepaid or internally-managed invoice billing through internal_invoice
• Stripe subscription billing through stripe_metered

New self-serve workspaces purchase credits through the TutorFlow checkout page ($5 minimum, $5,000 maximum). The purchased amount is added to the workspace balance as credits.

Buying Credits

Workspaces can purchase additional credits at any time through the TutorFlow dashboard. Dashboard billing operations use admin-authenticated internal APIs and are intentionally not part of the public agent API surface.

Agents can also request a checkout page URL via POST /v1/platform/agent/billing/session, which returns a TutorFlow-hosted checkout page where the human operator chooses the amount and completes payment through Stripe. The workspace email must be verified before the billing session can be created.

USDC Payments (x402)

Workspaces can also add credits using USDC on the Base network via the x402 protocol when it is enabled. In the current backend, the workspace email must be verified before an exhausted workspace can enter the paid x402 path.

When an API request reaches the billing guard with no credit balance and no payment method, the platform can return HTTP 402 Payment Required with x402 payment requirements. The current guard returns a $0.01 deposit requirement, then credits that amount to the workspace after the X-Payment retry is verified.

Supported:

• Asset: USDC
• Network: Base (mainnet)
• Scheme: exact (pay the exact amount)
• Current deposit amount: $0.01 per x402 payment requirement

x402 payments require the feature to be enabled on the platform. Check GET https://api.tutorflow.io/v1/platform/.well-known/agent.json for x402.enabled.

Agent note: generation services also run a pre-flight credit check based on the actual request estimate. If a request costs more than the credited x402 deposit, the retry can still return platform_credits_exhausted. In that case, top up through POST /v1/platform/agent/billing/session or repeat the x402 deposit flow until creditBalance covers the request.

Auto-Reload Credits

Workspaces can enable auto-reload to avoid service disruptions when their balance runs low. When the credit balance drops below a configured threshold, credits are automatically purchased using the saved payment method.

For example, setting autoReloadThresholdUsd: 10 and autoReloadTargetUsd: 50 means that when the workspace balance drops below $10, TutorFlow charges the saved payment method for the difference needed to bring the balance back to about $50. The backend skips auto-reload when the calculated charge would be less than $5.

Why We Do Not Price By Tokens

Token pricing is accurate for infrastructure providers, but confusing for most education teams. TutorFlow is positioned as an education product, not a raw LLM router, so we bill on the user-facing unit of value: per evaluation, per lesson, per item, per slide, per scene.

This makes spend predictable: an agent generating "20 ten-lesson courses" knows the cost is exactly 20 × 10 × $0.05 = $10.00, no token math, no surprise overages from chatty model output. Optional sub-events (image generation, video render, TTS regen) are explicit endpoint calls so agents opt in to them deliberately rather than getting bundle-priced into them.

Enterprise

Enterprise contracts are appropriate when you need:

• high monthly volume
• SLA and priority throughput
• custom rubric or model tuning
• procurement-friendly invoicing

Contact TutorFlow for enterprise pricing and minimum-commit agreements.