# Tera

> Stripe-parity pricing simulator. Send a catalog (prices, coupons, tax rates) and a customer timeline; get every invoice to the cent, exactly as Stripe would bill it, in classic and flexible billing mode. 127 of 127 golden timeline scenarios are verified against real Stripe test clocks (Stripe API 2026-09-30.endive). Tera never moves money; its Stripe features use a test-mode key only.

Amounts are integers in the currency's minor unit (cents; yen for JPY). Dates are ISO-8601 UTC. 130 golden scenarios cite 22 billing rules (R1, R2, R3, R4, R5, R6, R7, R8, R9, R10, R12, R13, R14, R15, R16, R17, R18, R19, R20, R21, R22, R23), defined in the PRD.

## App

- [Simulator](https://tera-orpin-three.vercel.app/simulator): `?s=S05` opens a golden scenario; `create_share_link` (MCP) builds a `?t=` link to any timeline
- [Pricing builder](https://tera-orpin-three.vercel.app/builder), [Migration planner](https://tera-orpin-three.vercel.app/migrate)

## API

- [OpenAPI document](https://tera-orpin-three.vercel.app/api/openapi.json): every endpoint and schema
- [Interactive reference](https://tera-orpin-three.vercel.app/reference)
- POST /api/simulate: Run a customer timeline and return every invoice
- POST /api/migrate: Preview the MRR impact of a price change
- GET /api/parity: Recorded Stripe test-clock evidence for every golden scenario
- POST /api/parity: Replay a golden scenario, or your own timeline and catalog, live in a Stripe test clock and diff it against Tera
- POST /api/stripe/push: Create or reuse a catalog's prices, coupons and tax rates in Stripe test mode
- GET /api/migrate/stripe: Import a migration's customer base from Stripe (test mode)
- GET /api/stripe/catalog: Import the connected Stripe account's catalog (test mode)
- GET /api/scenarios: List golden scenarios
- GET /api/scenarios/{id}: Get a golden scenario (timeline + hand-derived expected invoices + catalog)

## MCP

- [Setup](https://tera-orpin-three.vercel.app/mcp-setup): `claude mcp add --transport http tera https://tera-orpin-three.vercel.app/api/mcp`
- Tool `simulate_timeline`: Run a customer timeline (subscribe, trials, upgrades, coupons, tax, usage, cancellation) through Tera's Stripe-parity billing engine and return every invoice to the cent, plus the webhook events Stripe sends for it (per timeline event, to test a webhook handler).
- Tool `verify_timeline_in_stripe`: Replay a customer timeline (max 15 events, 2 years) in a fresh Stripe test-mode test clock and compare Stripe's invoices with Tera's to the cent.
- Tool `plan_price_migration`: Given the current and new unit price per seat (minor units of `currency`), the billing interval, a grandfathering flag and seats per customer (a number or { name, seats }), return affected customers and MRR before/after/delta, per customer and in total.
- Tool `plan_stripe_price_migration`: Read the live subscriptions on a per-seat price in the connected Stripe test-mode account (one customer per subscription, its quantity as seats) and return the MRR impact of moving them to new_unit_amount.
- Tool `import_stripe_catalog`: Read the active per-seat prices, valid coupons and active tax rates of the connected Stripe test-mode account as a Tera catalog.
- Tool `list_golden_scenarios`: The reference scenarios (with expected invoices derived by hand from Stripe's rules) that Tera is tested against, optionally only those citing a rule or with words in the title.
- Tool `get_golden_scenario`: Timeline, expected invoices and the hand math for a golden scenario id such as S05.
- Tool `get_parity_evidence`: The stored result of replaying golden scenarios in Stripe test clocks: match flag, diffs, test clock id, API version and, for one id, Stripe's own invoice ids and lines.
- Tool `create_share_link`: Validate a timeline (and optional custom catalog) and return a link that opens it in Tera's web simulator with the same invoices, for a human to inspect or share.
- Tool `push_catalog_to_stripe`: Create (or reuse, keyed by a hash of each definition) the catalog's products, prices, coupons, tax rates and usage meter in Tera's Stripe TEST-mode account and return the Stripe ids.
- Resource `tera://catalog`: Prices, coupons and tax rates the golden scenarios (and tools without a catalog) use
- Resource `tera://openapi.json`: Tera REST API (OpenAPI 3.1)
- Resource `tera://parity`: Match flag, diffs and test clock per replayed golden scenario
- Resource `tera://scenarios/{id}`: Timeline, hand-derived expected invoices and the math
- Prompt `explain_invoice`: Walk through every line of a golden scenario's invoices and the Stripe rule behind it
- Prompt `audit_price_change`: Model a price change for existing customers, check the proration a mid-cycle switch causes, and verify it in Stripe

## Docs

- [PRD and billing rules](https://github.com/PugarHuda/tera/blob/main/docs/PRD.md)
- [Golden scenarios](https://github.com/PugarHuda/tera/blob/main/golden/scenarios.json)
- [Stripe parity evidence](https://tera-orpin-three.vercel.app/parity)