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

# Trial conversion

> Count every free trial, including the ones your billing provider never sees, and how many turn into paying customers.

The **Trials** page shows how many free trials you start and how many convert: trial-to-paid rate, a funnel from trial to plan to payment, and each month's trials as a cohort.

Some apps run their trials in their billing provider. Stripe, Paddle or Lemon Squeezy then knows about every trial, and OneMRR reads them with no setup. Many apps run the trial themselves, often without asking for a card, and only tell the billing provider when someone picks a plan. Billing then only sees the trials that were already on their way to paying. A conversion rate built from it looks far better than it is. For those apps, your app sends each trial to OneMRR when it starts.

## 1. Choose where your trials start

Open **Settings → Trials**. For each billing source, choose where a free trial starts:

| Choice | Use it when | Trial started means |
| - | - | - |
| **In Stripe** (or Paddle, Lemon Squeezy) | The provider runs your trials, with or without a card | A subscription starts in a trial |
| **On the Shopify charge** | You set `trialDays` on the app subscription charge | The merchant approves the charge |
| **At install** | Your Shopify app's trial starts when it's installed | The app is installed; the trial lasts the **Trial length** |
| **In our app** | Your app starts the trial and sends it to OneMRR | A trial your app sends through the API |
| **No trials** | Customers pay from day one | Nothing; trials from the API still count |

![Settings, Trials, Where trials start: a notice that Stripe trials vary in length (1), the choices for Stripe (2) and what the chosen one means (3)](https://mintcdn.com/one-mrr/aio8gk4E-p1ouYbA/images/analytics/trials-settings.png?fit=max\&auto=format\&n=aio8gk4E-p1ouYbA\&q=85\&s=a5e2da4d6e586193130d63ed4d09020d)

1. OneMRR suggests a choice from your data. When a source's trials all have different lengths, your app is probably starting the trial and passing the days left at checkout, so it suggests **In our app**.
2. The choices this source can use.
3. What the choice means for the numbers. With **In our app**, a provider's trialing subscription counts as the **Chose a plan** step, not as a new trial. Shopify installs are used to check that your app sent every trial.

Nothing counts until you save. You can change these at any time: the Trials page works its numbers out again each time you open it.

### Counting rules

![Settings, Trials, Counting rules: conversion window, trial length, restarted trials and leave out](https://mintcdn.com/one-mrr/aio8gk4E-p1ouYbA/images/analytics/trials-rules.png?fit=max\&auto=format\&n=aio8gk4E-p1ouYbA\&q=85\&s=c983b84df930ca3f8af5824029cdb0e6)

* **Conversion window:** how long after a trial ends a first payment still counts as converted. Payments after that show as **paid later**. Default 30 days.
* **Trial length:** for trials that arrive without an end date: installs, and trials sent through the API without `ends_at`.
* **Restarted trials:** when a customer gets another trial before paying, such as a win-back offer. **Count the first only** (the default) keeps campaigns from inflating trials started; the restart still shows in the list.
* **Leave out:** trials with an attribute you name, such as `plan = free`, are left out of every number.

## 2. Read the Trials page

![The Trials page: trial-to-paid rate (1), the funnel for one month (2), billing alone against every trial counted (3), and what trials count by (4)](https://mintcdn.com/one-mrr/4vaN7hBFVIO9uhKR/images/analytics/trials-overview.png?fit=max\&auto=format\&n=4vaN7hBFVIO9uhKR\&q=85\&s=ffaa162530db89f8bcae9467a9ba2510)

1. **Trial → paid:** trials that converted ÷ trials started, over the latest months (up to three) whose trials are all past their conversion window. Beside it: trials started in the last 30 days, trials running now, and the median time from trial start to first payment.
2. **The funnel** for one month's trials: started, chose a plan, paid. Pick the month in the menu, or select a row in the month table. It opens on the latest month whose trials have all ended.
3. **Billing alone against every trial counted.** Paid ÷ chose a plan is what you'd get from your billing provider when your app runs the trial. Paid ÷ started is the real rate.
4. **What trials count by.** If you [count shops, stores or seats](https://docs.onemrr.dev/analytics/count-by.md), trials count per shop by default: each shop is its own trial and converts on its own first payment, even when one billing customer pays for several. Switch to **Customers** to count per billing customer instead. A customer already paying for one shop then isn't a new trial when they add the next. OneMRR remembers each person's choice, as on every other page.

### Months, splits and every trial

![Trials by month started, with October settling](https://mintcdn.com/one-mrr/aio8gk4E-p1ouYbA/images/analytics/trials-months.png?fit=max\&auto=format\&n=aio8gk4E-p1ouYbA\&q=85\&s=6c2b4b56b1996508ac5d0df4cc2a66c4)

Each month's trials are a cohort. A month's rate shows once all its trials have ended (**Settling**) and stops changing once every conversion window has closed (**Final**). **Paid later** counts trials that paid after their window.

![One month's trials split by how the customer signed up](https://mintcdn.com/one-mrr/aio8gk4E-p1ouYbA/images/analytics/trials-split.png?fit=max\&auto=format\&n=aio8gk4E-p1ouYbA\&q=85\&s=8fb62f8f33614c3213a62ff59bb17c26)

Trials split by any attribute your trials carry, such as the channel or how the customer signed up. The split comes from each trial's own attributes, so trials that never paid are split too.

![The list of converted trials, with the filter (1)](https://mintcdn.com/one-mrr/aio8gk4E-p1ouYbA/images/analytics/trials-list.png?fit=max\&auto=format\&n=aio8gk4E-p1ouYbA\&q=85\&s=72072951854eb103fe0fab26edfc219c)

The list at the bottom shows every trial, newest first, with when it chose a plan and paid. Filter it to running, converted, didn't convert, or **Not counted** (restarts, trials left out, and trials for customers who were already paying). Select one to open its customer; the customer's history shows its trials too.

![A customer's history with its trial: started, chose a plan, first payment](https://mintcdn.com/one-mrr/aio8gk4E-p1ouYbA/images/analytics/trials-drawer.png?fit=max\&auto=format\&n=aio8gk4E-p1ouYbA\&q=85\&s=13f17e7e8f4cfa290b52be3a0cbafb15)

## 3. Send trials from your app

Skip this if your billing provider runs your trials. Otherwise send each trial to OneMRR when it starts. You need a full secret key from [Settings → API](https://docs.onemrr.dev/workspace/settings.md#api) (one limited to tracking can't send trials); keep it on your server.

```bash theme={null}
curl https://app.onemrr.dev/api/v1/trials \
  -H "Authorization: Bearer $ONEMRR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "shop_48213:2026-11-02",
    "unit_key": "48213",
    "name": "Maple & Thread",
    "started_at": "2026-11-02T14:05:00Z",
    "ends_at": "2026-11-09T14:05:00Z",
    "links": { "shopify_domain": "maple-thread.myshopify.com" },
    "attributes": { "channel": "etsy", "source": "web_connect_shop" }
  }'
```

| Field | |
| - | - |
| `external_id` | Your ID for this trial. Sending it again updates the trial, to extend it say. A restarted trial gets a new one. |
| `unit_key` | What the trial belongs to. With [Count by](https://docs.onemrr.dev/analytics/count-by.md), the same value as the subscription metadata key you count by (a shop ID). Without it, the billing customer's ID. |
| `links` | Optional. The billing customer, when billing doesn't carry your unit key: `shopify_domain` for shops billed through your Shopify app, `stripe_customer`, or `customer_external_id`. |
| `started_at`, `ends_at` | When the trial starts and ends. Without `ends_at` it lasts the **Trial length** setting. |
| `name` | Optional. What to call it until billing knows the customer. |
| `attributes` | Optional. Up to 50 strings to split and leave out trials by, such as `channel`. |

The response says whether OneMRR already knows the customer (`matched`). A trial that never matches still counts, as one that didn't convert. That's how trials that never reach billing are counted.

### From your code

In Node.js, [`@onemrr/node`](https://www.npmjs.com/package/@onemrr/node) (0.2.0 or later) sends trials for you. Any other language can call the API as above.

```bash theme={null}
npm install @onemrr/node
```

Send the trial right where your app starts it, after the trial is saved. `trial()` never throws, so a problem reaching OneMRR can't stop a sign-up:

```javascript theme={null}
import { OneMRR } from "@onemrr/node";

const onemrr = new OneMRR({ apiKey: process.env.ONEMRR_SECRET_KEY });

// When a shop connects and its free trial starts.
await onemrr.trial({
  externalId: `shop_${shop.id}:${startedAt.toISOString()}`,
  unitKey: String(shop.id),
  name: shop.name,
  startedAt,
  endsAt,
  links: shop.shopifyDomain ? { shopifyDomain: shop.shopifyDomain } : undefined,
  attributes: { channel: shop.channel },
});
```

* **Every path that starts a trial** sends it: each place a customer can connect or sign up.
* **A restarted trial** (a win-back offer that resets the clock) is sent again with a new `externalId`, built from the new start date.
* **An extended trial** is sent again with the same `externalId` and the new `endsAt`.
* Problems go to the client's `onError` (by default a console warning), and `trial()` resolves `null`.

### Backfill past trials

Send the trials you already have, so the Trials page has history from the start. `trialMany()` sends them 500 a request (`/api/v1/trials/batch` in the API). If you only stored when each trial ends, its start is the end minus your trial length.

```javascript theme={null}
const result = await onemrr.trialMany(
  pastTrials.map((t) => ({
    externalId: `shop_${t.shopId}:${t.startedAt.toISOString()}`,
    unitKey: String(t.shopId),
    name: t.shopName,
    startedAt: t.startedAt,
    endsAt: t.endsAt,
    links: t.shopifyDomain ? { shopifyDomain: t.shopifyDomain } : undefined,
    attributes: { channel: t.channel },
  })),
);
console.log(result?.counts); // { created, updated, unchanged, failed }
```

Use the same `externalId` as your live code, so a trial sent by both counts once. Sending the backfill again is safe.

### Check that every install arrives

For a Shopify app whose trials start **In our app**, the Trials page compares the last 30 days of installs with the trials your app sent. An install with no trial within 48 hours usually means a code path that doesn't send it.

![Installs and trials sent in the last 30 days, with the installs that had no trial outlined](https://mintcdn.com/one-mrr/aio8gk4E-p1ouYbA/images/analytics/trials-install-check.png?fit=max\&auto=format\&n=aio8gk4E-p1ouYbA\&q=85\&s=0e4e96d0408537614d573239d879d073)

> [!NOTE]
>
> OneMRR reads installs from your Shopify app's history at each sync. If you connected Shopify before trials were available, installs appear after the next full sync, which runs at least once a day.

## How a trial is counted

* **Converted:** the customer's first payment arrives between the trial's start and its end plus the conversion window. It's the same moment OneMRR counts as **New** MRR, so the two always agree.
* **Chose a plan:** a billing trial or Shopify charge started during the trial, or the first payment itself.
* **Already paying:** a trial for a customer who is paying at the time isn't counted. One who paid before and cancelled gets a win-back trial, which converts on their reactivation.
* **The same trial from two places:** reports of one customer's trial within 48 hours of each other are one trial. A trial from your app wins over an install, and an install over a billing trial.
* **No MRR:** trials never add to MRR. A trial's MRR in the list is what the customer paid once it converted.


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