Documentation

For AI agents: the docs index is at /llms.txt, and every page is also served as markdown at its URL plus .md.

How TrialValid holds, starts, captures and refunds a card-backed free trial.

Read getting started See the API overview

Start

Getting started Plans and MRR

Concepts

Trial lifecycle Webhooks

Reference

Errors API overview

View as Markdown llms.txt for agents Full docs as text Docs sitemap

Trial states

Every trial is in exactly one state. This is the whole state machine the engine enforces.

awaiting_cardThe buyer is on the trial page
heldThe plan price is held on the card
convertedThe hold was captured
refundedA converted trial was refunded

trial statesstate machine

transitions { 3 states }

awaiting_card -> held | abandoned | canceled
held          -> converted | canceled | capture_failed | hold_lost
converted     -> refunded
(every other state is terminal)

Browse by topic

Start

Getting startedWhat you need to run card-backed trials with TrialValid, the steps a seller follows, and what the platform handles for you.Plans and MRRHow a seller's plan is chosen from connected-account MRR, with the bands, the counting rules and the prices.

Concepts

Trial lifecycleThe states a trial moves through, the jobs that drive it, and how cancel and failure paths resolve.WebhooksThe Stripe events TrialValid handles, how each event is claimed once, and why invoice events are not subscribed.

Reference

ErrorsThe error envelope the service uses, its fields, and the codes a seller can see.API overviewThe TrialValid HTTP API: seller routes for pages, variants, trials, domains and alerts, public routes for the hosted trial page, and an OpenAPI document.