Grosslytics

Docs

Set up Grosslytics.

One script tag for visits, one webhook for sales. Then every payment is credited to the channel that brought the buyer.

Install the tracker

Sign in at /app and add your site. You get a site ID such as gl_8b5e717a83ac. Paste this into the <head> of every page:

<script defer src="https://grosslytics.com/g.js" data-site-id="YOUR_SITE_ID"></script>

Self-hosting? Use your own domain in src. The tracker sends events to the same domain it was loaded from, at /api/event. To send them somewhere else, add data-api="https://your-api/api/event".

Events are only accepted from the site’s own domain, its subdomains, and localhost. The tracker records a pageview when the page loads, plus reading time and scroll depth when the visitor leaves.

Site sends a Content-Security-Policy header? Then the browser blocks the tracker until you allow your analytics domain in two places, and the only sign is an error in the browser console. Add it to script-src (to load g.js) and connect-src (to send events):

Content-Security-Policy: script-src 'self' https://grosslytics.com; connect-src 'self' https://grosslytics.com

Keep your other entries; only add the domain. If you set data-api to another host, add that host to connect-src too.

Single-page apps: client-side route changes (React Router, Next.js links, the back button) are recorded as page views automatically, each with its own reading time. Only the path counts; changing just the query string or #hash is not a new page.

Track goals

Add an attribute to any button or link. A click records the goal:

<button data-gl-goal="signup">Create account</button>

data-fast-goal and data-goal work too, so buttons already tagged for DataFast keep working. From JavaScript:

window.grosslytics('signup', { plan: 'pro' });

window.datafast, window.databull, window.plausible and umami.track point to the same function, so existing calls keep working after you swap the script. Umami’s data-umami-event and Plausible’s class="plausible-event-name=Signup" are read too.

Connect payments

In your payment provider, add a webhook pointing at the URL below. Then, in /app → Payments, paste the webhook’s signing secret. Unsigned webhooks, or ones with the wrong signature, are rejected.

https://grosslytics.com/api/webhooks/{provider}?siteId=YOUR_SITE_ID

To credit a sale to a channel, the payment has to carry the buyer’s visitor ID. On checkout links in your page, the tracker adds it for you. Anywhere else, read it in the browser and pass it to your checkout:

const visitorId = localStorage.getItem('gl_vid');

If there is no visitor ID, a returning buyer is still matched by email when they paid before, and otherwise the sale is counted as unattributed.

Stripe /stripe

Events: checkout.session.completed, invoice.paid, invoice_payment.paid, charge.refunded

Visitor ID: Payment Links and Checkout links on your page are tagged automatically (client_reference_id). With the Checkout API, pass client_reference_id or metadata.visitor_id (metadata.datafast_visitor_id also works). For renewals, put visitor_id in the subscription’s metadata.

Polar /polar

Events: order.paid

Visitor ID: Checkout links on your page are tagged automatically (reference_id). Or pass metadata.visitor_id.

Dodo Payments /dodo

Events: payment.succeeded, refund.succeeded

Visitor ID: Checkout links on your page are tagged automatically (metadata_visitor_id). With the API, pass metadata: { visitor_id } when you create the payment or subscription. The signing secret is the endpoint’s whsec_… secret. Full refunds remove the sale; partial refunds keep it.

Lemon Squeezy /lemonsqueezy

Events: order_created, subscription_payment_success

Visitor ID: Checkout links on your page are tagged automatically (checkout[custom][visitor_id]).

Paddle /paddle

Events: transaction.completed, adjustment.created, adjustment.updated

Visitor ID: Pass customData: { visitor_id } when you open Paddle Checkout. Approved full refunds remove the sale; partial refunds need separate reconciliation.

Razorpay /razorpay

Events: payment.captured

Visitor ID: Pass notes: { visitor_id } when you create the order or payment.

Cashfree /cashfree

Events: PAYMENT_SUCCESS_WEBHOOK

Visitor ID: Pass order_tags: { visitor_id } when you create the order. The signing secret is your Cashfree client secret.

Gumroad /gumroad

Events: Ping (sales) and refunds

Visitor ID: Product links on your page are tagged automatically (?visitor_id=, delivered as url_params). Gumroad pings are unsigned, so choose a long random key and add &key=YOUR_KEY to the ping URL.

PayPal /paypal

Events: PAYMENT.CAPTURE.COMPLETED

Visitor ID: Set purchase_units[].custom_id to the visitor ID when you create the order. The secret is client_id:client_secret:webhook_id (add :sandbox for a sandbox app); each webhook is checked with PayPal’s verification API. PayPal’s real fee is used, not an estimate.

RevenueCat /revenuecat

Events: INITIAL_PURCHASE, RENEWAL, NON_RENEWING_PURCHASE

Visitor ID: In your app, set the subscriber attribute visitor_id to the ID from the web visit (for example, passed through your web-to-app link). The secret is the Authorization header value you set on the webhook. Store commission and tax come from each event.

Currencies, tax and refunds

Each site reports in one currency: USD, EUR, GBP or INR, chosen when you add the site. A payment in another currency is refused (HTTP 422), never converted or mixed in. Full Stripe and Dodo refunds, approved full Paddle refunds, and Gumroad refunds remove the sale from revenue. Partial refunds and other providers’ refunds need separate reconciliation.

Sales tax or VAT that the provider reports (Stripe, Paddle, Polar, Lemon Squeezy, Dodo Payments, RevenueCat) is taken out of revenue, because it is not yours to keep. Net revenue then subtracts the payment fee: PayPal’s and RevenueCat’s real fee from the event, and each other provider’s standard published fee, which is an estimate.

Switch from DataFast, DataBull, Plausible or Umami

Replace the old script tag with the Grosslytics one. Your existing goal attributes and JavaScript calls keep working (see Track goals), and Stripe metadata named datafast_visitor_id or databull_visitor_id is read like visitor_id.

One change: those tools keep the visitor ID in a cookie, and Grosslytics sets no cookies. If your server reads the datafast_visitor_id cookie to fill Stripe metadata, send localStorage.getItem('gl_vid') from the browser instead.

Bring your history: in /app → Import past Stripe payments, paste a restricted key with read access to Checkout Sessions and Invoices. Past sales arrive with their real dates. They show as Unattributed, because no visits were recorded for them.

Read the dashboard

Attribution: first touch credits the source that first brought the buyer, last touch the one right before they paid, and linear splits each sale 50/50 between the two.

Revenue: gross is what the buyer paid, net subtracts payment fees, and profit also subtracts the ad spend you enter for each source and day.

Sources: visits that other tools call “Direct” are named where possible: in-app browsers (Instagram, Facebook, LinkedIn, TikTok, Telegram, X), AI search, links with ?utm_source=, ?ref= or ?via=, and shared links versus typed addresses.

Ad spend: add one day at a time, or import a CSV of date,source,amount exported from Meta, Google, X or LinkedIn Ads. The overview shows MER: revenue divided by ad spend.

Also on the dashboard: live visitors and sales, each buyer’s journey, lifetime value by first source, sales by day and hour in your site’s timezone, chart annotations, and an optional public revenue page at /share/your-domain that never shows customer emails or journeys.

Data retention: visit data is kept forever unless you choose 90 days to 2 years under Settings. Older page views, clicks and goals are then deleted every night; sales, revenue and each visitor’s first and last source stay.

AI crawlers

GPTBot, ClaudeBot, PerplexityBot and other AI crawlers fetch your pages without running JavaScript, so no tracking script can see them. To count them, your server tells Grosslytics when one asks for a page. Only requests from known AI crawlers are counted, and they never count as visitors. Generate a site-specific crawler key in Settings → API tokens, then keep it in your server environment. Every report must include it as an Authorization bearer token.

Next.js (middleware.ts):

import { NextResponse, type NextRequest } from 'next/server';

const AI = /GPTBot|OAI-SearchBot|ChatGPT-User|ClaudeBot|PerplexityBot|anthropic-ai|Google-Extended|Bytespider|Applebot-Extended|meta-externalagent|CCBot/;

export function middleware(req: NextRequest) {
  const ua = req.headers.get('user-agent') || '';
  if (AI.test(ua)) {
    fetch('https://grosslytics.com/api/crawl', {
      method: 'POST',
      headers: { 'content-type': 'application/json', authorization: 'Bearer ' + process.env.GROSSLYTICS_CRAWL_KEY },
      body: JSON.stringify({ sid: 'YOUR_SITE_ID', path: req.nextUrl.pathname, ua }),
    }).catch(() => {});
  }
  return NextResponse.next();
}

Cloudflare Worker in front of your site:

export default {
  async fetch(req, env, ctx) {
    const ua = req.headers.get('user-agent') || '';
    if (/GPTBot|ClaudeBot|PerplexityBot|OAI-SearchBot|ChatGPT-User|Google-Extended/.test(ua)) {
      ctx.waitUntil(fetch('https://grosslytics.com/api/crawl', {
        method: 'POST',
        headers: { 'content-type': 'application/json', authorization: 'Bearer ' + env.GROSSLYTICS_CRAWL_KEY },
        body: JSON.stringify({ sid: 'YOUR_SITE_ID', path: new URL(req.url).pathname, ua }),
      }));
    }
    return fetch(req);
  },
};

Any other server works the same way: one POST of { sid, path, ua } to /api/crawl with Authorization: Bearer <crawler key>. Visitors who arrive from ChatGPT, Perplexity, Claude, Gemini or Copilot answers are tracked separately, as the “AI Search” source, with their revenue.

To check the full path from an AI referral to a payment, follow the ChatGPT revenue attribution guide.

Click map

An optional second script shows what people click on the pages you choose, such as pricing and checkout: which plan or FAQ, which clicks hit something that does nothing (dead clicks), and three fast clicks on the same thing (rage clicks). It also shows how many of the people who clicked each thing later paid. Add it after the main script, only on those pages:

<script defer src="https://grosslytics.com/c.js" data-site-id="YOUR_SITE_ID"></script>

It records the clicked element’s label (its text, aria-label or field name), never what someone typed. It is kept separate so the main script stays small. Each click is one event, which counts toward Hosted Cloud’s monthly limit.

API

Create a read-only token in /app → API tokens. Each token reads one site and is shown once. Send it as a bearer token:

curl -H "Authorization: Bearer gl_pat_…" \
  "https://grosslytics.com/api/stats/dashboard?siteId=YOUR_SITE_ID&range=30d"

Read-only tokens can only make GET requests for their own site. The writes below need the owner’s API_TOKEN (self-hosting) or a signed-in dashboard session.

MethodPathReturns
GET/api/stats/sitesYour sites (owner only, not read-only tokens)
GET/api/stats/dashboard?siteId=…&range=30d&model=first&mode=netEvery dashboard number in one response. range: 24h, 7d, 30d, 90d, 12m (weekly), or custom with from and to (YYYY-MM-DD, up to 366 days). model: first, last, linear. mode: gross, net, profit. Filters: source, page, country, device.
GET/api/stats?siteId=…&range=30d&model=firstVisitors, sales and revenue per channel
GET/api/stats/journey/{visitorId}?siteId=…One visitor’s pages, goals and payments in order
POST/api/stats/ad-spend{ siteId, source, date: "YYYY-MM-DD", amountCents } sets one day’s spend for a source
POST/api/stats/ad-spend/bulk{ siteId, rows: [{ source, date, amountCents }] } up to 2,000 days at once (the dashboard’s CSV import)
POST/api/stats/sites/{siteId}/import/stripe{ key, kind?, after? } imports one page of past Stripe payments; call again with the returned next until it is null. The key is not stored.
GET/api/stats/ai-crawls?siteId=…&range=30dAI crawler requests by bot and by page
GET/api/stats/clicks?siteId=…&range=30dClicks per page and element from the click map, with buyers, dead and rage clicks
POST/api/crawl{ sid, path, ua } from your server with Authorization: Bearer <crawler key>
POST/api/stats/annotations{ siteId, at: unix seconds, label } adds a marker to the chart

AI agents (MCP)

Grosslytics includes an MCP server, so Claude Code, Cursor or Windsurf can answer questions like “which channel earned the most per visitor this month?” Use a read-only API token. In Claude Code:

claude mcp add --transport http grosslytics \
  "https://grosslytics.com/api/mcp?site=YOUR_SITE_ID" \
  --header "Authorization: Bearer gl_pat_…"

Other clients take the same URL and header in their MCP settings (Streamable HTTP). Tools:

  • query_channel_roas Revenue, ad spend and return per channel
  • inspect_unmasked_direct What “Direct” traffic really was: in-app browsers, shared links, typed visits
  • get_ai_search_citations Visits and revenue from ChatGPT, Perplexity, Claude, Gemini and Copilot
  • get_buyer_journeys Recent buyers and the pages they saw before paying
  • compare_buyer_reading_time Reading time and scroll depth of buyers vs everyone else

Self-hosting

Grosslytics runs entirely in your own Cloudflare account: Workers, D1, Queues and a Durable Object. The free Workers plan is enough for most sites.

The Cloudflare D1 deployment guide covers free-plan limits and how to verify that browser events reach the database.

Install the prebuilt release with Node.js 22.23.4 or newer and a domain on Cloudflare. The installer deploys Grosslytics to an analytics hostname such as analytics.example.com and sets your dashboard password.

npx grosslytics@latest install --free

In the dashboard, register the website you want to track, such as example.com. Add <a href="https://grosslytics.com" rel="sponsored">Powered by Grosslytics</a> inside the footer in the HTML served by that website’s homepage. You can also use rel="nofollow". Click Verify to open the dashboard. Grosslytics rechecks on access after 24 hours. Visits and sales are recorded while dashboard access is locked.

From the same folder, run npx grosslytics@latest update to update the dashboard and tracker. The tracker keeps its existing URL. If your old snippet loads the script from grosslytics.com, switch its script URL to your analytics hostname once to follow your own updates.

Use npx grosslytics@latest install --lifetime with a Lifetime license. For custom builds, follow the source installation instructions.

Privacy and bots

The tracker sets no cookies. It keeps a random visitor ID in the browser’s local storage and a session ID in session storage. Buyer emails are never stored in full: only a hash (to recognize repeat buyers) and a masked form such as j***@gmail.com for the dashboard.

Known bots, headless browsers and traffic from cloud data centers are dropped before they are counted. AI crawlers, such as GPTBot, are counted separately as crawls (see AI crawlers), never as visitors.

For AI assistants, a plain-text summary of this product is at /llms.txt.