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

# Revenue

> Record revenue from custom events, or connect Stripe or Paddle to import invoices, refunds and subscriptions and link them to your users.

There are two ways to measure revenue.

| Method | Best for | Where it shows |
| - | - | - |
| A `revenue` property on a custom event | One-time purchases tracked in your app | The **Revenue** metric on [Overview](https://docs.manalens.dev/features/overview.md) and dashboards |
| A Stripe or Paddle connection | Invoices, refunds and subscriptions from your billing provider | User profiles, the Explorer and [attribution](https://docs.manalens.dev/attribution/models.md) |
| An [itch.io](https://docs.manalens.dev/integrations/itch.md) connection | Purchases of your game on itch.io, matched to users by email | The same places as Stripe and Paddle revenue |

## Revenue from custom events

Add a numeric `revenue` property to the event that marks a purchase:

```ts theme={null}
analytics.track('purchase', { revenue: 49, currency: 'USD', plan: 'pro' });
```

The **Revenue** metric sums this property over the date range. You can also send the event from your backend with [server events](https://docs.manalens.dev/sdks/server.md).

## Provider payments as events

A payment from Stripe or Paddle becomes a `purchase` event, and a refund becomes a `refund` event. These are the names that Google Analytics and game analytics tools use.

| Field | Value |
| - | - |
| Event | `purchase` or `refund` |
| Channel | `stripe` or `paddle`. A website or a game cannot send these channels, so a record with one of them is a verified payment |
| `revenue` | The amount. A refund is negative |
| `currency` | The currency of the payment |
| `provider`, `record_id`, `customer_id`, `subscription_id` | The provider and its IDs |

You see these records in three places:

* **Overview.** The Revenue metric adds provider payments to the revenue of your own events, net of refunds.
* **Activity.** Each payment and refund is a row, for example "Paid \$15.00 (Stripe)".
* **Attribution.** Choose the goal `purchase`.

### One sale is counted once

Many studios also send their own `purchase` event with a `revenue` property. To count such a sale once, the provider record wins: when a user has a payment record from a provider, the `revenue` of that user's own events is left out of the Overview metric, and that user's own `purchase` events are left out of the `purchase` goal in Attribution. A user with no provider record keeps the revenue of the own events. The rule also covers an own event that the browser sent before `identify`, when its anonymous ID links to that one user.

Provider payments have no page, source or device of their own. In the Overview cards and the chart split with the Revenue metric, a payment takes the source, country and device of the buyer's first website page view in the 90 days before the payment. A payment with no known buyer shows as Direct or Unknown. When you add a filter, the Overview and Activity show your own events only.

With the Revenue metric, a legend under the Overview chart shows where the revenue comes from: your own events, Stripe, Paddle, itch.io and Steam. The legend shows only when a source other than your own events has an amount.

### Steam net sales

With a [Steam](https://docs.manalens.dev/features/steam.md) connection, the Revenue metric of the Overview includes the Steam net sales of each day. In the chart split, Steam is one group named "Steam".

* The amount is sales less returns and taxes, before the Steam revenue share. It is not your payout.
* The day is the Pacific Time day of Steam.
* Steam amounts are in USD. In a report with another currency, they are converted with the exchange rate of the day.
* With a filter on the Overview, Steam is left out.
* Steam gives totals with no buyer, so Steam sales are not in the cards, the user profiles or the Activity feed.

The activity list on a user's profile shows the payments and refunds of that user, for example "Paid \$15.00 (Stripe)".

## Connect Stripe or Paddle

You need the owner or admin role and a verified [MFA](https://docs.manalens.dev/security/mfa.md) session.

**1. Create the webhook endpoint**

Open **Settings**, then **Integrations**. In the **Stripe** or the **Paddle** section, click **Create webhook endpoint**.

**2. Register it with your provider**

Copy the endpoint URL into your provider's webhook settings.

**3. Save the signing secret**

Copy the provider's webhook signing secret, paste it into **Webhook signing secret** and click **Save signing secret**. Revenue ingestion starts.

**4. Import history (optional)**

Enter a restricted **Read API key** with read access to invoices or transactions, refunds or adjustments, and subscriptions. For Stripe, also give read access to Checkout Sessions to import one-time Checkout payments. A key without it imports the rest and skips them. Then import historical revenue. Imports resume automatically, and completed imports are reconciled daily.

Secrets and read keys are encrypted and never returned to the browser.

### Supported provider events

| Provider | Events |
| - | - |
| Stripe | `invoice.paid`, `checkout.session.completed`, `checkout.session.async_payment_succeeded`, `charge.refunded`, `customer.subscription.*` |
| Paddle | `transaction.completed`, approved refund `adjustment.created` and `adjustment.updated`, `subscription.*` |

Every webhook is verified against its signature. Other event types are acknowledged and ignored.

### One-time Stripe Checkout payments

A one-time Checkout Session (mode `payment`, also from a Payment Link) has no invoice unless you turn on invoice creation. ManaLens records it from `checkout.session.completed` when the session is paid. A delayed payment method (for example a bank debit) is recorded from `checkout.session.async_payment_succeeded`. The record ID is the payment intent (`pi_…`), so a refund of the payment links to it.

A sale is counted once. A session with an invoice is counted by `invoice.paid`, and a subscription session is counted by its invoices, so these sessions are skipped.

## Link revenue to users

ManaLens links a billing record to a user in one of two ways:

1. A `user_id` in the provider's metadata (Stripe) or `custom_data` (Paddle). For a Stripe Checkout Session, the session `metadata.user_id`, else its `client_reference_id`.
2. An identify trait `stripe_customer_id` or `paddle_customer_id`:

```ts theme={null}
await analytics.identify('user_123', { stripe_customer_id: 'cus_123' });
```

An invoice that arrives before the identify call links when the trait arrives. If a customer ID matches more than one user, the record stays unassigned. Email similarity is never used to guess a match.

## Currency

Amounts keep their original currency. Each report shows one **report currency**: the project's **Reporting currency** (Project settings, USD by default). Add `currency=EUR` to a report URL to see another one. The setting needs an owner or admin with MFA. By default every amount is **converted** to the report currency with the European Central Bank reference rate of the event day (the last known rate on weekends and holidays). A currency that the ECB does not publish is left out. An event without a `currency` counts in the report currency, so send `currency` when you sell in more than one currency. The `currency` property is not case-sensitive. Add `currency_mode=only` to count only revenue in the report currency, without conversion. Converted totals use reference rates, not the rate that your payment provider used.


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