> ## Documentation Index
> Fetch the complete documentation index at: https://docs.staging.metronome.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Free trials
> Choose a free-trial model for a usage-based product, implement it on Metronome contracts, and measure conversion and attrition.
Step-by-step API calls: custom fields, trial contract, alerts, webhooks, conversion, early end, recurring free tier, prepaid landing.
Metric definitions, Data Export SQL, and in-app reports for trial starts, conversion, attrition, and retention.
## Why offer a trial
Two reasons come up most often with usage-based products:
* **Adoption.** A trial lowers the barrier to a first integration, which matters most when you are launching a usage-based product for the first time or moving customers over from a subscription.
* **Pricing insight.** You cannot price usage well until you know what usage looks like. A trial produces real consumption data — which metrics move, how quickly, and how much they vary between customers — early enough to shape your rate card. Metering trial usage exactly as you meter paid usage is what makes that data worth having.
## Choosing a trial model
Trials are bounded in two ways: by **spend**, using an allowance the customer draws down, and by **time**, using a window that closes. Almost nobody picks only one. Setting both is the market norm and the safer default, because each bound covers the case the other misses: a spend cap alone leaves a customer sitting on an allowance indefinitely, and a time cap alone leaves your costs open-ended.
The interesting decision is which way you skew. A large allowance over a short window suits a fast, intensive evaluation. A smaller allowance over a long window suits products where adoption ramps slowly and the customer needs weeks to integrate.
In Metronome, a credit with an access schedule bounds both at once, because the schedule carries an amount and an `ending_before`. A zero-price override bounds time alone. This page covers how to choose between them, and how to set up your account so a trial can be converted and measured cleanly.
### Common trial patterns
Looking at a survey of the market, a handful of patterns appear. Only a few examples actually mean "free trial"; the others are worth knowing because your customers will ask for them and each maps to a different Metronome construct. The `trial_model` column is the value to record on the credit, per [tagging and conventions](#tagging-and-conventions); it is `n/a` for the patterns with no trial credit to tag.
| Pattern | What the customer gets | Metronome construct | `trial_model` |
| - | - | - | - |
| **Expiring credit** (amount **and** time) | e.g. \$400 for 30 days, whichever ends first | Credit with one access-schedule segment (capped trial) | `expiring_credit` |
| **Time-boxed, uncapped** | Unlimited usage for N days | Price override `multiplier: 0`, time-bounded (uncapped trial) | `time_only` |
| **Amount-only free credit** (no meaningful expiry) | \$X, use it whenever | Credit with a long-dated segment (every credit segment requires `ending_before`) | `amount_only` |
| **Reverse trial** | Generous trial, then fall back to a small free tier | Trial credit + recurring credit, or trial contract → free-tier contract | `reverse` |
| **Recurring free tier** | N units or \$X **per month**, forever | `recurring_credits[]` on a perpetual contract | n/a |
| **No trial, prepaid minimum** | Buy \$5 of credit before the first call | [Prepaid commit with a payment gate](/guides/pricing-packaging/apply-credits-and-commits/manual-payment-gated-commits), optionally with [auto-recharge](/guides/customers-billing/optimize-customer-experience/prepaid-balance-thresholds) | n/a |
### Choosing between them
These are the drivers worth weighing:
| Driver | Pushes toward | Why |
| - | - | - |
| **Cost to serve a free user** (GPU inference, compute, egress) | Amount cap; smaller grants | Time alone doesn't bound cost, and unmetered free access has generally proven expensive to sustain |
| **Fraud exposure** (freejacking, denial-of-wallet, spam) | Amount cap + product-side identity controls; card-on-file for high-COGS products | An amount cap bounds the worst case; identity controls and prepayment reduce how often it happens |
| **Time-to-value** | Fast TTV → small expiring credit; slow TTV (migrations, integrations) → longer window or reverse trial | The customer must reach the "aha" before the cap |
| **Sales motion** | Sales-assisted → longer/larger, with alerts routed to reps; self-serve → tight, automated | Trial signals become lead-qualification signals |
| **What you can measure** | Patterns with a clean end state (expiring credit; conversion to a paid contract) | Attrition and conversion reporting needs unambiguous events — see the [data reference](/guides/pricing-packaging/billing-model-guides/free-trials/trial-data-reference) |
### Recommendation
* **Default: expiring credit** (amount + time), converted to a paid contract. It bounds cost, produces clean end states, and is what customers already understand.
* **A deliberately oversized credit** when you want the trial to feel unlimited. Grant far more than a trial customer could plausibly consume, keep the window short, and the customer never meets the cap while you still get balance tracking, alerts, and a full drawdown record. This is a common choice when you are new to usage-based pricing and want to watch real consumption before committing to a rate card.
* **Time-only override** when per-unit COGS are low or adoption of a platform takes serious ramping and you want the customer to experience the whole product. This model produces no balance signals, so the schedule end is your only trial-end event. Prefer the oversized credit above if you want that same experience with visibility into spend.
* **Recurring free tier** for a permanent low-cost tier or as the landing state of a reverse trial. Note that its alerts mean something different, since a drained balance signals a throttled month rather than the end of a trial (see [recurring free tier](/guides/pricing-packaging/billing-model-guides/free-trials/implement-a-trial#recurring-free-tier)).
* **Prepaid minimum** as the *conversion landing state*, not as the trial.
## Reference architecture
### Trial contract → paid contract
Model the trial as **its own contract** and convert by creating the paid contract with `transition: { type: "RENEWAL", from_contract_id }` (see [contract lifecycle transitions](/guides/customers-billing/manage-customers/manage-customer-lifecycle)). This is preferred over a single perpetual contract because:
* The trial package and the paid package evolve independently (different rate cards, credits, commits, subscriptions).
* Conversion is a first-class row in `contracts_transitions` (Data Export) and `transitioned_from/to_contract_id` (in-app report), so conversion and attrition reporting is a join, not an inference.
* The transition end-dates the trial contract at the paid contract's `starting_at`, truncates the trial credit to that instant, and expires any unused balance — no rollover, no dangling credit.
```
customer ──► trial contract (contract_type=trial)
└─ credit "Trial credit" {trial=true, trial_model=expiring_credit}, priority 1
│
├─ credit.segment.end ─────────────► your app: trial ended (expiry | conversion | archive)
├─ % remaining alert / days-left alert ► nudges
└─ $0 balance alert ──────────────────► backstop only
│
POST /v1/contracts/create {transition: RENEWAL}
▼
paid contract (contract_type=paid): PAYG, or prepaid commit + payment gate, or recurring free tier
```
### Tagging and conventions
Every business models trials a little differently, so there is no single trial report that fits all of them. The queries and reports in the [data reference](/guides/pricing-packaging/billing-model-guides/free-trials/trial-data-reference) assume the names and custom fields below. Adopt them and those queries work unchanged; use your own instead and you will need to adjust each query to match.
| Object | Field | Value |
| - | - | - |
| Customer | `custom_fields.trial_started_at`, `custom_fields.trial_source` | ISO timestamp; `self_serve` / `sales` / … |
| Trial contract | `name`; `custom_fields.contract_type` | `Trial`; `trial` |
| Paid contract | `custom_fields.contract_type` | `paid` |
| Trial credit | `name`; `custom_fields.trial`, `custom_fields.trial_model` | `Trial credit`; `"true"`, and the `trial_model` value for your pattern from [common trial patterns](#common-trial-patterns) |
| Contract create | `uniqueness_key` | `trial-{customer_id}` — guarantees one trial per customer (409 on retry) |
| Conversion | `transition.type` | `RENEWAL` |
Tagging earns its keep beyond reporting. Because `trial` and `trial_model` sit on the credit itself, you can point [alert specifiers](/guides/customers-billing/set-up-notifications/create-alert-specifiers) at those fields and alert on trial balances separately from every other credit and commit a customer holds. If you run more than one trial model, that also lets you give each model its own thresholds rather than sharing a single alert.
**Recurring credits cannot carry `custom_fields`.** Identify a recurring free tier by `recurring_credit_id` (API) / `parent_recurring_credit_id` (webhooks), the contract's `contract_type`, the credit `name`, or `applicable_product_tags`.
### Prerequisites and constraints
1. **[Register custom-field keys](/api-reference/custom-fields) first.** Any request that sets an unregistered key fails with `Invalid custom field keys: …`. Entities: `customer`, `contract`, `contract_credit`.
2. **Timestamps are hour-aligned.** Contract `starting_at` and credit `ending_before` must be on an hour boundary (`… is required to be on an hour boundary (e.g. 1:00, not 1:30)`). UTC midnight is *not* required.
3. **Enable the system notifications you need.** Turn on `credit.segment.start`, `credit.segment.end`, `credit.archive`, and `contract.end` from the UI or the API — see [system notifications](/guides/customers-billing/set-up-notifications/system-notifications).
## Next steps