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

# Revenue integrations

> Connect a payment provider like Polar, Shopify, or RevenueCat to attribute real revenue, orders, and conversion rate to your analytics.

## Overview

Revenue integrations let you attach the money side of your business to your analytics. Once a provider is connected, OpenRevenue shows revenue, orders, and conversion rate across your dashboard, including per country, page, referrer, and visitor.

You connect a provider per project under `Settings`, in the `Revenue API` section. This is separate from the tracker's [`transaction()`](https://docs.openrevenue.com/advanced/transactions) call, which only records that a conversion happened without an amount.

## Supported providers

Pick one provider per project. Most connect with an API key. Shopify connects with app credentials, and RevenueCat connects with a webhook.

> [card] Polar
>
> API key Paste an Organization Access Token (polar\_oat\_…). Adds Average Order Value and MRR.

> [card] Stripe
>
> API key Paste a restricted, read-only secret key.

> [card] Lemon Squeezy
>
> API key Paste an API key from your store settings.

> [card] Paddle
>
> API key Paste an API key from your Paddle dashboard.

> [card] Dodo Payments
>
> API key Paste an API key from your Dodo dashboard.

> [card] Shopify
>
> App credentials Enter your store domain plus the Client ID and Client secret of an app with read access to orders.

> [card] RevenueCat
>
> Webhook Connect a webhook instead of a key. Best for mobile app revenue.

## Connect with an API key

For Polar, Stripe, Lemon Squeezy, Paddle, and Dodo:

1. Open `Settings` for your project and find the `Revenue API` section.
2. Choose your provider from the `Pick your payment provider` menu.
3. Paste your provider API key into the field and click `Connect`.

Your key is encrypted at rest. A read-only key is enough. To switch providers, disconnect the current one first.

> [!TIP]
>
> Use a restricted or read-only key wherever your provider supports it. OpenRevenue only needs to read orders and subscriptions.

## Connect Shopify

Shopify needs your store domain and the credentials of an app installed on that store. OpenRevenue reads orders and refunds through the Admin API and never writes to your store.

1. In the [Shopify Dev Dashboard](https://dev.shopify.com/dashboard/), create an app in the same organization as your store.
2. Create a version of the app with the `read_orders` access scope. Add `read_all_orders` too if you want orders older than 60 days. If Shopify asks about protected customer data, allow access to orders. Name, email, phone, and street address are not needed.
3. Install the app on your store.
4. Open the app's `Settings` and copy the `Client ID` and `Client secret`.
5. In OpenRevenue, open `Settings` for your project, find the `Revenue API` section, and choose Shopify.
6. Enter your store domain (for example `your-store.myshopify.com`, not a custom domain), the Client ID, and the Client secret, then click `Connect`.

Your credentials are encrypted at rest. OpenRevenue exchanges them for a short-lived Admin API token each time it syncs, so there is nothing to renew.

> [!NOTE]
>
> Already have a custom app that was created in the Shopify admin before 2026? Leave the Client ID empty and paste that app's Admin API access token (`shpat_…`) into the Client secret field instead. Shopify no longer lets you create this kind of app, so new setups use the steps above.

What gets counted:

* **Revenue** is the amount received on each order, in your store currency, dated by when the order was created. Unpaid, voided, and test orders are left out.
* **Refunds** are counted on the day they were issued.
* **Country** comes from the order's billing address, so point of sale orders without one are not shown per country.

> [!WARNING]
>
> Revenue is read from Shopify when you open a report. For a selected date range OpenRevenue reads the 2,000 most recent orders, so very high-volume stores should use shorter ranges for exact totals.

## Connect RevenueCat

RevenueCat sends purchases to OpenRevenue over a webhook:

1. In the `Revenue API` section, choose RevenueCat and click `Generate webhook`.
2. Copy the `Webhook URL` and the `Authorization header` value shown.
3. In the RevenueCat dashboard, go to Project Settings, Integrations, Webhooks, and add a new webhook.
4. Paste the URL and set the Authorization header to the value you copied.

The webhook URL has this shape:

```bash Webhook URL theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
https://your-openrevenue-domain.com/api/webhooks/revenuecat/<project-id>
```

To attribute a purchase to a specific visitor, set the `openrevenue_visitor_id` subscriber attribute in your app to the visitor ID OpenRevenue assigns. Without it, revenue is still recorded and grouped by country and time.

> [!NOTE]
>
> OpenRevenue ingests purchase events (initial purchases, renewals, and one-time purchases). Cancellations, expirations, and billing issues are ignored.

## Display currency

Choose a display currency in the same Settings section. Amounts are shown in that currency across your reports. The default is USD.

## Attribute revenue to a visitor

Once a provider is connected, **all revenue, orders, and country totals show automatically** — you don't have to do anything. The step below is only needed to also break revenue down by the **traffic source, page, and visitor** that drove each sale.

Attribution works by attaching the OpenRevenue visitor id to the order as `openrevenue_visitor_id`. The tracker exposes it on the page as `window.openrevenue.visitorId`.

By default the tracker stores nothing in the browser, so the visitor id is the visitor's ID for the current day. It is set a moment after the page loads, when the first pageview is answered; the tracker then fires an `openrevenue:visitor` event on `window`. A sale is attributed when the checkout starts on the same day as the visit. To attribute sales to visits on earlier days, [store a visitor ID with consent](https://docs.openrevenue.com/advanced/cookies-and-consent.md#with-consent).

### Automatic — Polar & Lemon Squeezy

Their checkout is a hosted link, so the tracker tags it for you. **No code needed** — just link to your Polar or Lemon Squeezy checkout normally.

### One line — Stripe, Paddle & Dodo

These create checkout on your server, so pass the visitor id as metadata when you start checkout.

Stripe Checkout (one-time payments):

```ts server.ts theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
// Read window.openrevenue.visitorId on the client and send it to your server, then:
const session = await stripe.checkout.sessions.create({
  mode: "payment",
  line_items: [/* … */],
  // Lands on the PaymentIntent → Charge, where OpenRevenue reads it.
  payment_intent_data: { metadata: { openrevenue_visitor_id: visitorId } },
})

// For subscriptions, attach it to the subscription instead:
// subscription_data: { metadata: { openrevenue_visitor_id: visitorId } }
```

Paddle (Paddle.js overlay):

```ts checkout.ts theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
Paddle.Checkout.open({
  items: [/* … */],
  customData: { openrevenue_visitor_id: window.openrevenue?.visitorId },
})
```

Dodo Payments — set it on the payment/subscription you create:

```ts server.ts theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
metadata: { openrevenue_visitor_id: visitorId }
```

### One snippet — Shopify

Shopify copies cart attributes onto the order, so save the visitor id on the cart. Add this to your theme (for example at the end of `theme.liquid`, after the OpenRevenue tracker):

```html theme.liquid theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
<script>
  function saveOpenRevenueVisitor(visitorId) {
    if (!visitorId) return
    var root = (window.Shopify && Shopify.routes && Shopify.routes.root) || "/"
    fetch(root + "cart/update.js", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ attributes: { openrevenue_visitor_id: visitorId } }),
    })
  }
  window.addEventListener("openrevenue:visitor", function (event) {
    saveOpenRevenueVisitor(event.detail.visitorId)
  })
  window.addEventListener("load", function () {
    saveOpenRevenueVisitor(window.openrevenue && window.openrevenue.visitorId)
  })
</script>
```

If your theme prints cart attributes on the cart page or in order emails, use `__openrevenue_visitor_id` (two leading underscores) as the attribute name instead. Shopify hides attributes named that way from the storefront and checkout, and OpenRevenue reads both. Orders that skip the cart, such as point of sale and draft orders, are not attributed.

RevenueCat uses a subscriber attribute instead — see [Connect RevenueCat](#connect-revenuecat).

> [!NOTE]
>
> Without the visitor id, a sale still counts toward your revenue, order, and country totals — it just won't be attributed to a specific source or page.

## What you see

After connecting, revenue appears throughout the dashboard:

* Totals for **revenue**, **orders**, and **conversion rate** above the chart, plus **AOV** and **MRR** when Polar is connected.
* A revenue overlay on the main chart, and a Revenue metric you can switch the report tables to.
* Revenue, orders, and revenue per visitor broken down by country, page, referrer, device, browser, and OS.
* A revenue column on the Visitors list.

> [!WARNING]
>
> If your project has [public stats](https://docs.openrevenue.com/advanced/public-stats.md) enabled, revenue figures are visible on the public share page too. Keep that in mind before sharing.


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