> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trevosdk.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Paywall and pricing experiments

> Test paywalls, plans and prices with the billing tool you already use, and judge them by revenue.

Trevo never draws your paywall and never charges anyone. Your billing tool keeps doing both.
Trevo tells your app which version of the paywall to show, and counts what each version earns.

## How it works

1. **One pull request, one release.** Trevo's pull request changes two places in your app:
   * the paywall reads what to show from [parameters](https://docs.trevosdk.com/concepts/parameters.md), such as
     `paywall.offering` or `paywall.headline`;
   * the code where a purchase succeeds reports it with its amount.
2. **After that, a paywall test is values only.** You approve and start it from the dashboard,
   with no pull request and no release.
3. **Your app hands Trevo's value to your billing tool,** which shows the paywall and takes the
   payment as it does today.
4. **Results compare revenue per user** for each version, beside the conversion rate.

## Report each purchase

Send a `purchase` event once the purchase has completed, not when it starts, with the amount paid:

```ts theme={null}
trevo.track('purchase', {
  value: 49.99, // the price paid in major units, read from your billing SDK
  currency: 'USD', // ISO code; leave it out to use your workspace's currency
  product: 'pro_annual',
});
```

| Property | Meaning |
| - | - |
| `value` | The amount paid, as a number in major units such as `49.99`: convert amounts in cents or micros, as Stripe and Google Play give them. A numeric string such as `"49.99"` also counts. |
| `currency` | The ISO 4217 code. Trevo converts every amount into your workspace's reporting currency. |
| `product` | Optional. The product, package or price identifier. |
| `kind` | Optional. `trial` for a free trial start (counts as a conversion worth nothing), `refund` to subtract an amount. Anything else counts as a purchase. |
| `trial_days` | On a trial start: how many days the trial lasts. Trevo uses it to count every person over the same number of days. |

## Report from your server too

Your app sees a purchase while it is open. A trial that turns paid, a renewal or a refund happens
later, and only your billing tool and your server learn about it. Report those from the server,
where it already receives your billing tool's events or runs its own billing, with a server key:

```ts theme={null}
trevo.track(
  'purchase',
  { anonymousId: customer.metadata.trevo_id }, // or { userId } for a signed-in user
  { value: toMajorUnits(amount, currency), currency, product: plan.id }, // whole units, not cents
  { insertId: event.id }, // the billing event's own id, so a repeated delivery counts once
);
```

* **Name the person who saw the paywall.** Save the user's Trevo id on your billing customer as
  `trevo_id` (in its metadata or attributes) where you create the checkout or set up the billing
  SDK, and report with it. Never use the billing tool's own customer id.
* **The server's word wins.** For anyone your server reported, Trevo counts the server's amounts
  and ignores the app's copy of the same purchase. Keep the app's report for everyone else.
* **Send test-mode and sandbox events only with a development key,** never the production one.
* **No Trevo server SDK?** Send the same event with one HTTPS request to
  `https://ingest.trevosdk.com/v1/events` and your secret key. See [REST](https://docs.trevosdk.com/install/rest.md).

Trevo's pull request adds both, where it finds the code that learns about payments.

Trevo reads amounts on an experiment's primary event when that event is `purchase`, or when the
experiment is decided by revenue per user. An event without `value` still counts as a conversion
and adds nothing to revenue.

## Hand the value to your billing tool

Trevo works with any billing tool, and with billing you built yourself: it reads what your code
does, not a list of providers. For example:

| Billing | What your app does with Trevo's value |
| - | - |
| RevenueCat | Fetches the offering with that name |
| Superwall | Sets it as a user attribute, or picks the placement to register. A rule in Superwall maps it to a paywall. |
| Stripe | Uses it as the Price ID when it creates the checkout |
| Your own billing | Reads it wherever it decides the plan, price or copy |

When a tool draws the paywall from its own dashboard, you design it in that tool's editor and
Trevo only tests it. The parameter that picks which paywall shows ends in the name your code passes
the paywall's id under, such as `paywall.offering` for code that passes `offering`, or
`paywall.choice` when the code passes the id without a name. Trevo's pull request passes every
other parameter to the paywall as a variable before it opens, through whatever the tool offers,
such as custom variables or user attributes. The pull request lists the variables to add; add them
in the tool's editor, then publish.

### A new design in your paywall tool

To test a new layout of a paywall your tool draws, Trevo writes a **brief**: the layout, every line
of copy, the products it offers and the values it shows. Your team builds that paywall in the
tool's editor, then enters its id on the experiment's **Edit** page as the value of the parameter
that picks the paywall. Trevo never creates or edits anything in your tool's account, and it won't
start the experiment until the id is in, since both versions would otherwise show today's paywall.

### When your tool picks the paywall

If your code shows whichever paywall the tool picks (its current offering, or the paywall a
campaign rule matches), the tool may be running its own test there. The idea, the experiment page
and the pull request say so. Pause the tool's test while Trevo's runs, or each result includes the
other's change. It is a caution, never a block.

## Real plans and prices

Trevo proposes only plans and prices you sell. It reads the plan, offering, product and price ids
your code uses, and what people really paid per `product` in the last 90 days from your `purchase`
events, with no billing tool's API and no key to paste. A paywall idea that names an id found in
neither place is sent back, unless your team fills it in from a brief.

## How a change goes live

Every idea, every experiment page and every pull request says how the change reaches users:

| Route | When | You |
| - | - | - |
| Values only | Your app already reads every value the test changes | Start the experiment. No pull request, no release. |
| Merge and deploy | Code in a web app or a server | Merge the pull request: the experiment starts when it merges. |
| Over the air | Code in a mobile app that downloads updates itself (such as EAS Update or Shorebird) | Merge, and push an over-the-air update. No store review. |
| Built in your paywall tool | A new design of a paywall your tool draws | Build it from the brief, enter its id, start the experiment. |
| App release | Code in a mobile app | Merge and ship a release. The test measures people on builds with it. |

## Lists, orderings and translated text

* **JSON in a text parameter.** A text value may hold JSON of up to 4,000 characters: a list of
  plans, feature bullets or an ordering. Every version must have the shape your app reads today,
  the same keys and the same kinds of values, or Trevo refuses it, since your app would fall back
  to its default and that version would equal control. Your app parses the value and keeps its
  default when parsing fails.
* **Text per language.** In an app that translates its text, a headline or other copy can carry one
  text per language your app ships. Trevo reads your languages from your translation files, and the
  idea writes the new text in each for your team to check. The SDK shows the text for the app's
  language and falls back to your app's own translation for any other. Call `setLocale` where your
  app picks or changes its language, so the SDK matches what users see; Trevo's pull request adds
  it. Text per language needs @trevosdk/browser 0.3.8, @trevosdk/react-native 0.1.6,
  @trevosdk/node 0.1.4, or 0.1.1 of the iOS, Android and Flutter SDKs. An older build shows your
  own text to everyone, and still counts in the results.

## How revenue is judged

* **Revenue per user** is each arm's revenue divided by everyone in that arm, buyers or not. It
  is tested with the same always-valid sequential method as conversion rates, so you can check
  whenever you like.
* **One big spender can't decide a test.** A revenue result needs at least 10 buyers in each arm
  before it can be called, and one large purchase can't make it significant on its own. Each
  person's revenue also counts only up to the 99th percentile of buyers, which starts trimming the
  largest purchases once a test has more than about 100 buyers.
* **Refunds subtract,** and a person's revenue never goes below zero.
* **Trials are counted fairly.** Once people in a test start trials, revenue counts every person
  over the same number of days (how long the trials last, plus 3), and only people who entered at
  least that long ago, so a version that charges at once can't win just because the other's trials
  haven't ended. While trials have started and no payment reported by your server has followed
  any, revenue decides nothing and the results say so.
* **Which measure decides** is set per experiment: conversion rate or revenue per user. Paywall
  ideas from Trevo are decided by revenue per user when a server reports your payments, and by how
  many people buy otherwise, with revenue shown beside it. In an experiment decided by conversion rate, any
  version that earns significantly less per user than the original is treated like a harmed
  guardrail: the experiment isn't shipped on its own.
* **Currency.** Choose the reporting currency in **Settings → General**. Amounts are converted
  with the European Central Bank's latest daily reference rates; an amount in a currency the ECB
  doesn't publish is left out and counted in the results' notes.

## Limits

* A new paywall layout drawn in your app's native code needs a release, unless your app ships over
  the air or a tool draws it from its own dashboard.
* Without a server report, Trevo sees only what happens while your app is open: a purchase or a
  trial start, not a trial turning paid, a renewal or a refund made later. Trevo then doesn't
  propose a test that changes the trial itself.
* Amounts are what the buyer paid, before store commission and tax. They are right for comparing
  versions, not for accounting.
* Prices must already exist in your billing tool or store. A price test chooses among products you
  already sell.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.