---
title: "Documentation"
url: "https://trialvalid.com/docs.md"
canonical_url: "https://trialvalid.com/docs"
last_updated: "2026-10-19"
type: "reference"
summary: "Guides for TrialValid: getting started, the trial lifecycle, plans, webhooks, errors and the API overview."
related: ["https://trialvalid.com/docs/getting-started.md", "https://trialvalid.com/docs/trial-lifecycle.md", "https://trialvalid.com/docs/plans-and-mrr.md", "https://trialvalid.com/docs/webhooks.md", "https://trialvalid.com/docs/errors.md", "https://trialvalid.com/docs/api.md"]
---

# Documentation

> **For AI agents:** the complete index of TrialValid pages is [llms.txt](https://trialvalid.com/llms.txt). Every page is also served as markdown at its URL plus .md.

Guides for TrialValid: getting started, the trial lifecycle, plans, webhooks, errors and the API overview.

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

> Every state, job, webhook and error in the trial engine is documented here. [See the API overview](https://trialvalid.com/docs/api.md).

[Read getting started](https://trialvalid.com/docs/getting-started.md)

### Start

- [Getting started](https://trialvalid.com/docs/getting-started.md)
- [Plans and MRR](https://trialvalid.com/docs/plans-and-mrr.md)

### Concepts

- [Trial lifecycle](https://trialvalid.com/docs/trial-lifecycle.md)
- [Webhooks](https://trialvalid.com/docs/webhooks.md)

### Reference

- [Errors](https://trialvalid.com/docs/errors.md)
- [API overview](https://trialvalid.com/docs/api.md)

## Trial states

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

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

## Related

- [Getting started](https://trialvalid.com/docs/getting-started.md)
- [Trial lifecycle](https://trialvalid.com/docs/trial-lifecycle.md)
- [Plans and MRR](https://trialvalid.com/docs/plans-and-mrr.md)
- [Webhooks](https://trialvalid.com/docs/webhooks.md)
- [Errors](https://trialvalid.com/docs/errors.md)
- [API overview](https://trialvalid.com/docs/api.md)