Add AI Monetization group to Use Cases

fern/docs.yml

@@ -42,6 +42,16 @@ navigation:
         contents:
           - page: Overview
             path: ./docs/pages/use-cases/overview.mdx
+          - section: AI Monetization
+            contents:
+              - page: Pre-flight cost previews
+                path: ./docs/pages/use-cases/pre-flight.mdx
+              - page: Surprise-throttle protection
+                path: ./docs/pages/use-cases/surprise-throttle.mdx
+              - page: Protect your margins
+                path: ./docs/pages/use-cases/margin-protection.mdx
+              - page: Real-time ledger & holds
+                path: ./docs/pages/use-cases/credit-ledger.mdx
           - section: Product-Led Growth
             contents:
               - page: Convert and expand users self-serve
@@ -56,6 +66,10 @@ navigation:
                 path: ./docs/pages/use-cases/usage-billing.mdx
               - page: Run credit-based billing
                 path: ./docs/pages/use-cases/credit-billing.mdx
+              - link: Pre-flight cost previews
+                href: /use-cases/pre-flight
+              - link: Real-time ledger & holds
+                href: /use-cases/credit-ledger
           - section: Sales-Led Growth
             contents:
               - page: Close custom deals
@@ -72,14 +86,18 @@ navigation:
                 path: ./docs/pages/use-cases/usage-signals.mdx
               - page: Stay ahead of renewals and expirations
                 path: ./docs/pages/use-cases/renewals.mdx
+              - link: Surprise-throttle protection
+                href: /use-cases/surprise-throttle
           - section: Operations
             contents:
               - page: Reprice and repackage safely
                 path: ./docs/pages/use-cases/plan-versioning.mdx
-              - page: Keep Stripe in sync
+              - page: Keep your billing system in sync
                 path: ./docs/pages/use-cases/stripe-sync.mdx
               - page: Automate with webhooks and AI
                 path: ./docs/pages/use-cases/automation.mdx
+              - link: Protect your margins
+                href: /use-cases/margin-protection
       - section: Playbooks
         contents:
           - page: Overview

fern/docs/pages/use-cases/credit-billing.mdx

@@ -19,4 +19,5 @@ Create a credit type, grant credits on a plan each billing period, and set how m
 ## Learn more
 
 - [Credit Burndown Billing Model](/billing/credit-burndown) — set up credit types, grants, consumption rates, and bundles.
+- [Meter on a real-time credit ledger](/use-cases/credit-ledger) — the ledger, holds, and exactly-once semantics underneath credits.
 - [Usage Based Billing Models](/billing/usage-based-billing) — how credit burndown relates to the other usage models.

fern/docs/pages/use-cases/credit-ledger.mdx

@@ -0,0 +1,23 @@
+---
+title: Meter on a real-time credit ledger
+slug: use-cases/credit-ledger
+description: Drive enforcement and billing off an accurate, real-time ledger instead of a stale snapshot.
+---
+
+Credit-based and usage-based pricing is only as trustworthy as the metering underneath it. Enforcing limits, refunding failed actions, and billing accurately all depend on a ledger that is correct in real time, not a number you reconcile after the period closes.
+
+## Common approaches
+
+A common shortcut is to stream usage events to a warehouse like Snowflake or Databricks and pull a snapshot every 24 hours. It's quick to stand up and perfectly fine for analytics and reporting, so it's often the first thing teams reach for.
+
+A 24-hour snapshot is not a ledger, though. It isn't transactional, so it can't safely drive enforcement; it's always stale, so customers blow past limits before the numbers catch up; and without idempotency, a retried event double-counts while a dropped one disappears. Once real money and real enforcement ride on these numbers, "approximately right, eventually" stops being good enough, and bolting correctness onto an analytics pipeline after the fact is a hard retrofit.
+
+## How Schematic fits in
+
+Schematic gives you a real-time credit ledger with exactly-once event semantics, idempotent writes, and replay safety, so every action draws the balance down accurately and enforcement evaluates against current state. Holds let you reserve credits before an action and then commit or release them based on the outcome, so an in-flight agent can't overspend or get charged for work that failed. And pricing versioning keeps legacy customers on their old rates while new customers get the new ones, with no migration scramble.
+
+## Learn more
+
+- [Credit Burndown Billing Model](/billing/credit-burndown) — credit grants, consumption, and balances on the ledger.
+- [Creating a metered feature](/playbooks/metering) — send the usage events the ledger is built from, including idempotency keys.
+- [Backfills and usage corrections](/playbooks/backfill-and-corrections) — correct and replay events safely.

fern/docs/pages/use-cases/margin-protection.mdx

@@ -0,0 +1,23 @@
+---
+title: Protect your margins
+slug: use-cases/margin-protection
+description: Enforce the limits you priced for in real time, before heavy usage erodes a profitable plan.
+---
+
+In usage-based and AI products, a few heavy users can quietly turn a profitable plan into a loss. Protecting your margins means enforcing the limits you priced for at runtime, the moment usage reaches them, rather than discovering the overage after the model and compute spend is already gone.
+
+## Common approaches
+
+Without runtime enforcement, limits are effectively on the honor system: usage is tracked in analytics and reviewed after the billing period closes. By the time a report surfaces a runaway account, the cost has already been incurred, and the best you can do is have an awkward conversation or eat the loss.
+
+The homegrown alternative is to scatter cap checks through application code, but those checks drift from your pricing configuration, miss edge cases, and turn every pricing change into an engineering change. Hard caps that are supposed to protect the business become one more brittle thing to maintain, and the gap between "what we priced" and "what we actually enforce" is where margin leaks out.
+
+## How Schematic fits in
+
+Schematic enforces entitlements and usage limits at runtime, soft limits, hard caps, and overage thresholds, so a heavy user is held to what their plan allows the instant they reach it, not at the end of the month. The caps are configured from the UI alongside the rest of your pricing, so the guardrails that protect your margins move with your pricing instead of lagging a deploy behind it, and the business team can tune them without pulling in engineering.
+
+## Learn more
+
+- [Usage Based Billing Models](/billing/usage-based-billing) — configure soft limits, hard caps, and overage.
+- [Company Overrides](/feature-management/overrides) — set per-customer limits where a deal requires it.
+- [Entitlement & Credit Trigger Webhooks](/integrations/webhooks/entitlement-triggers) — alert internally when an account runs hot.

fern/docs/pages/use-cases/overview.mdx

@@ -4,18 +4,29 @@ slug: use-cases/overview
 description: The common things teams build with Schematic, and where to start with each.
 ---
 
-Schematic gives product, growth, and engineering teams one place to define what customers get, enforce it in real time, and bill for it, without hard-coding pricing and access into your application.
+Schematic gives product, growth, and engineering teams one place to define what customers get, enforce it in real time, and bill for it, without hard-coding pricing and access into your application. It's purpose-built for monetizing AI and usage-based products: metering, credits, real-time limit enforcement, and custom plans.
 
 These use cases cover the things teams most often want to do. Each one explains the goal, how it's usually approached, and how Schematic fits in, then points you to the deeper setup docs. New to Schematic? Start with the [Quickstart](/quickstart/overview) to set up your account and SDK first.
 
+## AI monetization
+
+Selling AI means protecting two things: your margins, and your customers' trust. These use cases cover both.
+
+- **[Show customers what an action will cost](/use-cases/pre-flight)** — pre-flight cost previews so customers know the price before they run an expensive action.
+- **[Warn customers before they hit a limit](/use-cases/surprise-throttle)** — transparent usage, soft warnings, and grace periods so a throttle is never a surprise.
+- **[Protect your margins](/use-cases/margin-protection)** — enforce the limits you priced for in real time, before heavy usage erodes a plan.
+- **[Meter on a real-time credit ledger](/use-cases/credit-ledger)** — drive enforcement and billing off an accurate ledger with holds, not a stale snapshot.
+
 ## Product-led growth
 
 - **[Convert and expand users self-serve](/use-cases/self-serve-checkout)** — let customers sign up, upgrade, and add capacity without talking to sales.
 - **[Give customers a self-service portal](/use-cases/customer-portal)** — one branded place to manage subscriptions, payment, invoices, and usage.
 - **[Run free trials](/use-cases/free-trials)** — grant time-limited access and convert trial users cleanly when the trial ends.
 - **[Price by usage](/use-cases/usage-based-pricing)** — meter consumption, enforce limits, and turn rising usage into expansion.
-- **[Bill for usage](/use-cases/usage-billing)** — turn metered usage into accurate Stripe invoices automatically.
+- **[Bill for usage](/use-cases/usage-billing)** — turn metered usage into accurate invoices automatically.
 - **[Run credit-based billing](/use-cases/credit-billing)** — sell a prepaid credit balance that burns down as customers use features.
+- **[Show customers what an action will cost](/use-cases/pre-flight)** — pre-flight cost previews that build buying confidence and surface upsells.
+- **[Meter on a real-time credit ledger](/use-cases/credit-ledger)** — the real-time ledger and holds underneath credit and usage pricing.
 
 ## Sales-led growth
 
@@ -28,9 +39,11 @@ These use cases cover the things teams most often want to do. Each one explains
 - **[Manage exceptions with overrides](/use-cases/overrides)** — adjust a single company's access for trials, goodwill, or in-flight deals.
 - **[Spot churn and expansion with usage signals](/use-cases/usage-signals)** — watch usage against entitlements to flag at-risk and upsell-ready accounts.
 - **[Stay ahead of renewals and expirations](/use-cases/renewals)** — catch trials, overrides, and contracts before they lapse and access changes.
+- **[Warn customers before they hit a limit](/use-cases/surprise-throttle)** — protect the customer relationship with soft warnings and grace periods.
 
 ## Operations
 
 - **[Reprice and repackage safely](/use-cases/plan-versioning)** — roll out new pricing and packaging and migrate customers on your terms.
-- **[Keep Stripe in sync](/use-cases/stripe-sync)** — keep entitlements and billing aligned through a bidirectional Stripe sync.
+- **[Keep your billing system in sync](/use-cases/stripe-sync)** — keep entitlements and billing aligned through a native, two-way sync with Stripe or Metronome.
 - **[Automate with webhooks and AI](/use-cases/automation)** — drive Slack, CRM, and AI-assisted workflows off Schematic events.
+- **[Protect your margins](/use-cases/margin-protection)** — enforce hard caps and overage limits so heavy usage can't run away with your costs.

fern/docs/pages/use-cases/pre-flight.mdx

@@ -0,0 +1,23 @@
+---
+title: Show customers what an action will cost
+slug: use-cases/pre-flight
+description: Give customers a cost estimate before they run an expensive AI action.
+---
+
+AI features carry variable, sometimes large per-action costs, and customers won't adopt what they can't predict. A research agent that might burn 15-20 credits is a gamble unless the customer can see the price before they commit to running it.
+
+## Common approaches
+
+Most products show the cost after the fact: a usage page that ticks up once the action finishes, or a monthly invoice that arrives weeks later. The customer learns what something cost only after they've already spent it, which is precisely the uncertainty that stalls adoption of the most valuable, most expensive features.
+
+That uncertainty has become a procurement issue, not just a UX one. When Microsoft burned through a year of AI credits in four months, every buyer started asking "do you have limit management?" before signing. Without a way to preview cost, customers either avoid your premium features or wrap them in their own guardrails, and "how much will this cost me?" turns into a recurring sales and support question.
+
+## How Schematic fits in
+
+Schematic exposes a pre-flight cost endpoint that returns a cost estimate, the customer's current balance, and their plan state for a given action. You can render "this will cost about 15-20 credits, you have 312 remaining" right in your product before the customer runs it, so they act with confidence instead of fear. The same check is a natural upsell moment: when a customer is short, you can offer credits or an upgrade in the flow rather than failing the action.
+
+## Learn more
+
+- [Credit Burndown Billing Model](/billing/credit-burndown) — the credit balance a pre-flight check reads against.
+- [Customer Portal and Checkout Flow](/components/customer-portal) — surface balance and add-credit paths in-product.
+- [Entitlement & Credit Trigger Webhooks](/integrations/webhooks/entitlement-triggers) — react as customers approach their balance.

fern/docs/pages/use-cases/stripe-sync.mdx

@@ -1,20 +1,20 @@
 ---
-title: Keep Stripe in sync
+title: Keep your billing system in sync
 slug: use-cases/stripe-sync
-description: Keep entitlements and billing aligned through a bidirectional Stripe sync.
+description: Keep entitlements and billing aligned through a native, two-way sync with Stripe or Metronome.
 ---
 
-Your product enforces access in real time, but billing lives in Stripe, and the two have to agree. When a subscription, plan, add-on, or quantity changes, both your app and Stripe need to reflect it, without anyone updating records by hand.
+Your product enforces access in real time, but billing lives in your billing system, Stripe or Metronome, and the two have to agree. When a subscription, plan, add-on, or quantity changes, both your app and your billing system need to reflect it, without anyone updating records by hand or migrating off the platform you already run on.
 
 ## Common approaches
 
-The do-it-yourself version is a two-way integration. In one direction you listen for Stripe webhooks, subscription created, updated, canceled, payment failed, and translate each into the right entitlement changes in your app. In the other, you push changes made in your product, an upgrade, an added seat, a cancellation, back to Stripe so billing reflects them.
+The do-it-yourself version is a two-way integration. In one direction you listen for billing webhooks, subscription created, updated, canceled, payment failed, and translate each into the right entitlement changes in your app. In the other, you push changes made in your product, an upgrade, an added seat, a cancellation, back to the billing system so invoicing reflects them.
 
 Getting that integration correct is a real project, and keeping it correct is the harder part. Every new plan, add-on, or usage-based product is another mapping to maintain, and subscription lifecycle states like past-due, paused, or incomplete each need a deliberate decision about whether access should continue. Miss one of those edge cases and the two systems quietly disagree, so a customer keeps access after canceling, or loses it after a payment that actually succeeded.
 
 ## How Schematic fits in
 
-Schematic runs a bidirectional sync with Stripe. Map plans and add-ons to Stripe products and usage features to metered products; changes made through Schematic checkout and the customer portal write straight to Stripe, while subscription changes in Stripe provision or revoke entitlements automatically. Subscription status drives access, so cancellations and failed payments move customers to the right state without custom code.
+Schematic runs a native, two-way sync with your billing system, so you keep Stripe or Metronome rather than migrating off it. Map plans and add-ons to billing products and usage features to metered products; changes made through Schematic checkout and the customer portal write straight to billing, while subscription changes in the billing system provision or revoke entitlements automatically. Subscription status drives access, so cancellations and failed payments move customers to the right state without custom code.
 
 ## Learn more
 

fern/docs/pages/use-cases/surprise-throttle.mdx

@@ -0,0 +1,23 @@
+---
+title: Warn customers before they hit a limit
+slug: use-cases/surprise-throttle
+description: Surface usage transparently with soft warnings and grace periods so a limit is never a surprise.
+---
+
+A throttle without warning is a churn event. When a customer's usage gets cut off at a limit they never saw coming, the support ticket follows, then the CSM escalation, then a renewal conversation that goes sideways. The policy may be correct, but to the customer it reads as the product breaking.
+
+## Common approaches
+
+Enforcement is often binary: access works right up until the moment the limit trips, and then it just stops. The customer's first signal that they were anywhere near a cap is the error message, with no chance to react before service degrades.
+
+Teams that try to soften the edge bolt on ad-hoc threshold emails or a usage dashboard, but alerts wired by hand are easy to get wrong and rarely consistent from one feature to the next. A cut-off with no lead time still lands as a surprise, and the work of building warnings, grace windows, and clear messaging for every metered feature is its own project that tends to get deprioritized.
+
+## How Schematic fits in
+
+Schematic surfaces usage transparently in your product and fires soft warnings as customers approach a cap, at 70, 80, and 90 percent, with grace periods so a brief overage doesn't immediately cut off service. The limit still does its job, but the customer sees it coming and has a clear path to add capacity or upgrade before anything stops, which turns a potential churn moment into an expansion one.
+
+## Learn more
+
+- [Entitlement & Credit Trigger Webhooks](/integrations/webhooks/entitlement-triggers) — fire as usage crosses warning thresholds.
+- [Customer Portal and Checkout Flow](/components/customer-portal) — show usage against limits and an upgrade path in-product.
+- [Usage Based Billing Models](/billing/usage-based-billing) — configure soft and hard limits and overage behavior.

fern/docs/pages/use-cases/usage-based-pricing.mdx

@@ -4,7 +4,7 @@ slug: use-cases/usage-based-pricing
 description: Meter consumption, enforce limits, and turn rising usage into expansion.
 ---
 
-Some products get more valuable the more they're used. Pricing that way means metering consumption accurately, enforcing limits as customers reach them, and turning that usage into upgrades and expansion revenue.
+Some products get more valuable the more they're used, and AI products especially, where a single agent run or batch of tokens carries real cost. Pricing that way means metering consumption accurately, enforcing limits as customers reach them, and turning that usage into upgrades and expansion revenue.
 
 ## Common approaches
 
@@ -14,7 +14,7 @@ It stops scaling as soon as the pricing gets real. Limits that vary by plan or b
 
 ## How Schematic fits in
 
-Define a metered feature (event-based for things like API calls, trait-based for things like seats), set entitlement limits per plan, and report usage. Schematic enforces access at runtime as customers approach their limits and supports a range of models, pay-as-you-go, pay-in-advance, fixed fee with overage, volume, and graduated pricing, so you can match how you want to charge without rebuilding metering each time.
+Define a metered feature (event-based for things like API calls, tokens, or agent runs, trait-based for things like seats), set entitlement limits per plan, and report usage. Schematic enforces access at runtime as customers approach their limits and supports a range of models, pay-as-you-go, pay-in-advance, fixed fee with overage, volume, and graduated pricing, so you can match how you want to charge without rebuilding metering each time.
 
 ## Learn more