# GeckoStats documentation

Written from the code that does each thing. One page per thing a developer or an agent has to get right. The same pages are at https://geckostats.com/docs.

### Getting started
- Install the script (https://geckostats.com/docs/install): One script tag on every page. What it records on its own, the attributes it takes, and how to check it is working.
- Goals, and who the visitor is (https://geckostats.com/docs/goals): Mark a button as a goal with one attribute, fire goals from code, identify signed-in users, and tag newsletter links.

### Revenue
- How a payment finds its visit (https://geckostats.com/docs/attribution): The identity model behind revenue attribution: what the script holds, what a checkout must carry, and what happens when it does not.
- Stripe (https://geckostats.com/docs/stripe): Connect Stripe: the webhook, the metadata on a Checkout Session, payment links, and several sites on one Stripe account.
- Polar (https://geckostats.com/docs/polar): Connect Polar: the webhook with the payload set to raw, metadata on a checkout, and checkout links.
- Creem (https://geckostats.com/docs/creem): Connect Creem: the webhook, metadata on a checkout, the success URL, and what static payment links can and cannot carry.
- Dodo Payments (https://geckostats.com/docs/dodo-payments): Connect Dodo Payments: the webhook, payment links that are tagged on click, the return URL, and redirects from JavaScript.
- Webhooks, event by event (https://geckostats.com/docs/webhooks): Which provider events are read, how each is verified, what a refund or a repeated event does, and payments that arrive early.

### Agents and API
- Server-to-server API (https://geckostats.com/docs/api): Four endpoints and one key: payments from any provider, goals from your backend, release markers from CI, crawler hits from your server logs.
- MCP server (https://geckostats.com/docs/mcp): Give any MCP client, or any script, the website's numbers: 26 tools over JSON-RPC, authenticated with the site key.

### Search
- Search Console (https://geckostats.com/docs/search-console): Connect Google Search Console and see queries ranked by the revenue of the pages they land on, index status, Discover and CTR pressure.

### Operating
- Alerts (https://geckostats.com/docs/alerts): Six alerts, evaluated hourly, delivered by email or to a webhook; Slack and Discord are formatted automatically.
- Privacy and your data (https://geckostats.com/docs/privacy): How visitors are counted without cookies, what cookie mode changes, how to leave your own visits out, and how to export or delete everything.
- Troubleshooting (https://geckostats.com/docs/troubleshooting): No visits arriving, a payment that is not attributed, an empty search panel, numbers that differ from another tool: what to check, in order.
- Plans, billing and your account (https://geckostats.com/docs/account): What each plan carries at each size, the trial, changing plan, what happens when a plan ends, and deleting a website or the account.
- Sharing, seats and export (https://geckostats.com/docs/sharing-and-team): A read-only link for someone without an account, seats for colleagues, and taking your data out as CSV.

---

# Install the script

One tag, on every page. Pageviews, route changes, outbound clicks, scroll depth and Core Web Vitals are recorded without anything else.

_Updated 2026-11-15._

## The tag

Add this to the head of every page, including the signed-in part of your app. The website id is on the install step of each website in the dashboard.

HTML:
```
<script defer data-website-id="<website-id>" src="https://geckostats.com/js/script.js"></script>
```

Next.js, in app/layout.tsx:
```
import Script from 'next/script';

<Script defer data-website-id="<website-id>" src="https://geckostats.com/js/script.js" strategy="afterInteractive" />
```

Load it once. Every subdomain of the website is the same website, so app.example.com and example.com share one dashboard. Signed in, the Install tab of each website carries a brief for a coding agent with these values filled in, and the same snippets per platform.

The script is 17 kB, 6.5 kB gzipped, and has no dependencies. It is served from this host; if the site has a Content-Security-Policy, allow it in script-src and connect-src.

## Where the tag goes, by framework

The only rule is that it loads once on every page. These are the usual places.

Next.js, pages router:
```
// pages/_document.tsx
import { Html, Head, Main, NextScript } from 'next/document';

export default function Document() {
  return (
    <Html>
      <Head>
        <script defer data-website-id="<website-id>" src="https://geckostats.com/js/script.js" />
      </Head>
      <body><Main /><NextScript /></body>
    </Html>
  );
}
```

Nuxt:
```
// nuxt.config.ts
export default defineNuxtConfig({
  app: { head: { script: [{ src: 'https://geckostats.com/js/script.js', defer: true, 'data-website-id': '<website-id>' }] } },
});
```

SvelteKit:
```
<!-- src/app.html -->
<head>
  %sveltekit.head%
  <script defer data-website-id="<website-id>" src="https://geckostats.com/js/script.js"></script>
</head>
```

Astro:
```
---
// src/layouts/Layout.astro
---
<head>
  <script defer data-website-id="<website-id>" src="https://geckostats.com/js/script.js"></script>
</head>
```

Remix / React Router:
```
// app/root.tsx
<head>
  <Meta />
  <Links />
  <script defer data-website-id="<website-id>" src="https://geckostats.com/js/script.js" />
</head>
```

WordPress:
```
// functions.php
add_action('wp_head', function () {
  echo '<script defer data-website-id="<website-id>" src="https://geckostats.com/js/script.js"></script>';
});
```

Webflow, Framer, Squarespace, Shopify and the like: paste the tag into the site-wide head code setting. A page builder that only offers a body slot is fine too; defer means the tag runs after the page has parsed wherever it is.

## Serving the script from your own domain

Some content blockers refuse any analytics host. The script sends events to the origin it was loaded from, so the whole thing can live behind your own domain with two rewrites, and nothing else changes:

Next.js rewrites:
```
// next.config.ts
async rewrites() {
  return [
    { source: '/js/script.js', destination: 'https://geckostats.com/js/script.js' },
    { source: '/api/event', destination: 'https://geckostats.com/api/event' },
  ];
}
```

Then load it from your domain:
```
<script defer data-website-id="<website-id>" src="/js/script.js"></script>
```

Any proxy that forwards those two paths does the same. Payments are unaffected either way: they arrive by webhook from the provider, not from the browser.

## What it records on its own

- Pageviews, including route changes in a single-page app: pushState, replaceState and popstate are all pageviews. Do not add pageview calls.
- Outbound clicks: a link to another domain is recorded as the destination origin and path.
- Scroll depth: the deepest point reached on each page, only ever counted upwards.
- Core Web Vitals: LCP, CLS, INP and TTFB from the real visit, attached to the pageview.
- Engaged time, sent as a heartbeat while the tab is active.

Personal data in a URL, such as ?email= on a payment return page, is stripped before the address leaves the browser.

## Attributes

| Attribute | What it does |
| --- | --- |
| data-website-id | Required. Which website this is. |
| data-domain | The root domain when the script runs on a subdomain and you want the parent treated as the same place, such as data-domain="example.com" on app.example.com. Used for the cookie domain in cookie mode and to keep your own domains out of the referrers. |
| data-api | Send events somewhere other than this host. Rarely needed. |
| data-allow-localhost | Record visits from localhost. The script ignores them otherwise. For testing; remove it before committing. |

## Check it is working

Open the site with the browser's developer tools on the Network tab. A POST to https://geckostats.com/api/event answers 202, and the visit is on the dashboard within seconds, on the live globe first.

On localhost, nothing is sent unless the tag carries data-allow-localhost. The install step in the dashboard watches for the first event and says when it has arrived.

---

# How a payment finds its visit

Every payment is joined to the visit that produced it, which is how a sale ends up next to the tweet, the article or the search query that brought it. This page is what has to be true for that to work.

_Updated 2026-11-15._

## The identity

By default the script stores nothing on the visitor's device. The collector works out a visitor id from a daily-rotating salted hash, hands it back, and the script keeps it in memory for the page. It is exposed as:

JavaScript:
```
window.geckostats.attribution()
// { ml_visitor_id: "…", ml_session_id: "…" }
```

A payment that carries those two values as metadata is attributed to that visit the moment the provider's webhook arrives. Nothing else is needed.

## Getting it onto the checkout

Where the checkout is created on your server, the identity is not in the request: there is no cookie to read. The browser has to send it, and the server merges it into the metadata it already sets, keeping every existing key.

Server-side checkout:
```
// client
fetch('/api/checkout', {
  method: 'POST',
  body: JSON.stringify({ plan, attribution: window.geckostats?.attribution?.() }),
});

// server
const session = await stripe.checkout.sessions.create({
  // …
  metadata: { ...existingMetadata, ...body.attribution },
  success_url: 'https://<your-domain>/thanks?session_id={CHECKOUT_SESSION_ID}',
});
```

Where the checkout is created in the browser, spread the same object into its metadata.

A static payment link in an anchor needs nothing: the script tags it on click. Dodo Payments links get the two values as metadata_ query parameters, Stripe payment links get them in client_reference_id and Polar checkout links in reference_id, in the form ml_<visitor>__<session>. If your code already sets one of those, yours is kept.

A redirect to a payment link from JavaScript is the one case the click tagging cannot see. Append the values yourself, in the same form.

## The success page

Every checkout should return to a page on your site that loads the script. The provider appends its own id to that URL, and that id is how a payment whose metadata was lost is still recovered. Keep the query parameters on the page until it has loaded.

| Provider | Success URL on your site | What the provider appends |
| --- | --- | --- |
| Stripe | end it with ?session_id={CHECKOUT_SESSION_ID} | Stripe fills in the session id |
| Polar | end it with ?checkout_id={CHECKOUT_ID} | Polar fills in the checkout id |
| Creem | any page | ?checkout_id=…&order_id=… |
| Dodo Payments | return_url, or ?redirect_url=… on a payment link | ?payment_id=… or ?subscription_id=… |

## When the metadata is missing

The payment is not dropped. It is matched by the provider's own id from the success page, then by the customer's email against anyone the site has identified, and if nothing matches yet it is held and matched when the identity catches up. The settings of each website list every payment still waiting, which is the place to look when a sale seems to be missing.

Attribution is last touch by default, first touch if you prefer, per website. Neither is correct, so the choice is yours and the dashboard says which produced each figure. Traffic from your own other domains, such as docs or the app, is not counted as a referral once you list them in the website's settings.

---

# Stripe

One webhook endpoint per website, two metadata keys on each checkout, and every Stripe payment lands on the visit that caused it.

_Updated 2026-11-15._

## The webhook

In Stripe, add an endpoint for this URL, which is on the Connect payments step of the website in the dashboard with the id filled in:

Endpoint URL:
```
https://geckostats.com/api/webhooks/stripe/<website-id>
```

Send it checkout.session.completed, checkout.session.async_payment_succeeded, invoice.paid and charge.refunded. Paste the endpoint's signing secret into the same step; every event is verified against it. Subscription renewals arrive as invoice.paid and are counted as renewals; refunds subtract themselves, and a second partial refund replaces the first.

## Metadata on the checkout

Put ml_visitor_id and ml_session_id from window.geckostats.attribution() into the Checkout Session's metadata, and make success_url a page on your site ending in ?session_id={CHECKOUT_SESSION_ID}. The general shape is on the attribution page; the Stripe-specific part is only those two names.

Node:
```
await stripe.checkout.sessions.create({
  mode: 'subscription',
  line_items,
  metadata: { ...existingMetadata, ...attribution },
  success_url: 'https://<your-domain>/thanks?session_id={CHECKOUT_SESSION_ID}',
  cancel_url: 'https://<your-domain>/pricing',
});
```

Stripe Payment Links (buy.stripe.com) need no change: the script sets client_reference_id to ml_<visitor>__<session> when the link is clicked, unless your code already sets its own.

## Several websites on one Stripe account

Stripe sends every event to every endpoint it has, so two websites on one account each receive each payment. A payment is placed by, in order: an ml_site_id key in its metadata if you set one; the website the visitor was actually seen on; for a renewal, which carries no visitor, the website this Stripe customer paid before. A payment that none of those place on a website is not recorded there. A single website is unaffected.

## Test mode

A test-mode endpoint with a test-mode signing secret works the same way, and test payments arrive through the same handler, so the whole path can be checked before a real card is involved.

---

# Polar

One webhook, two metadata keys, and Polar orders and subscriptions are tied to the traffic that produced them.

_Updated 2026-11-15._

## The webhook

Endpoint URL:
```
https://geckostats.com/api/webhooks/polar/<website-id>
```

Add it in Polar with the payload format set to Raw, and paste the secret into the Connect payments step of the website. Events are verified with the Standard Webhooks signature.

## Metadata on the checkout

Node:
```
await polar.checkouts.create({
  products,
  metadata: { ...existingMetadata, ...attribution },
  successUrl: 'https://<your-domain>/thanks?checkout_id={CHECKOUT_ID}',
});
```

Polar Checkout Links (buy.polar.sh) need no change: the script sets reference_id to ml_<visitor>__<session> when the link is clicked, unless your code already sets its own.

---

# Creem

One webhook endpoint, two metadata keys on each checkout, and a success page on your site for the rest.

_Updated 2026-11-15._

## The webhook

Endpoint URL:
```
https://geckostats.com/api/webhooks/creem/<website-id>
```

Add it in Creem and paste the signing secret into the Connect payments step of the website. A creem_test_ key only ever talks to the sandbox, and test payments arrive through the same handler.

## Metadata and the success page

Node:
```
await creem.createCheckout({
  product_id,
  metadata: { ...existingMetadata, ...attribution },
  success_url: 'https://<your-domain>/thanks',
});
```

Creem appends ?checkout_id=… and ?order_id=… to the success URL itself; keep them on the page until the script has loaded. Creem's static payment links cannot carry metadata, so for those the success page on your site is the whole mechanism.

---

# Dodo Payments

Payment links need nothing at all: the script tags them on click. Everything else is a webhook and a return URL.

_Updated 2026-11-15._

## The webhook

Endpoint URL:
```
https://geckostats.com/api/webhooks/dodo/<website-id>
```

Add it in Dodo and paste the secret into the Connect payments step of the website. Events are verified with the Standard Webhooks signature.

## Payment links and checkouts

A payment link in an anchor (checkout.dodopayments.com/buy/…) is tagged when it is clicked: the script appends metadata_ml_visitor_id and metadata_ml_session_id. If your code redirects to a payment link from JavaScript, append those two parameters yourself from window.geckostats.attribution().

A checkout, payment or subscription created on the server takes the same two keys in its metadata, with return_url a page on your site. Dodo appends ?payment_id=… or ?subscription_id=… to it, which is how a payment is still recovered when the metadata was lost.

When one Dodo account sells products for several websites, list each website's product ids in its settings, and a payment for one of them is placed there even when the webhook reached another.

---

# Server-to-server API

Four endpoints, authenticated with the website's key as a bearer token. The key is on the API and MCP keys step of the website, and can be rotated there.

_Updated 2026-11-15._

## Authentication

Header:
```
Authorization: Bearer <site-key>
```

One key per website, scoped to that website alone. The same key is what the MCP server takes. Reading reports is done through the MCP server rather than through these endpoints; see the MCP page.

## POST /api/v1/payments

A payment from any provider that has no built-in integration. The amount is in major units, 29.99 rather than 2999; the currency defaults to the website's. Send visitor_id and session_id from window.geckostats.attribution() for a direct match; without them the payment is matched by email against identified visitors, and held if nothing matches yet.

curl:
```
curl -X POST https://geckostats.com/api/v1/payments \
  -H "Authorization: Bearer <site-key>" -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "ord_8x2k",
    "amount": 29.99,
    "currency": "USD",
    "visitor_id": "<ml_visitor_id>",
    "session_id": "<ml_session_id>",
    "email": "buyer@example.com",
    "renewal": false
  }'

{ "ok": true, "attributed": true, "visitor_id": "…" }
```

| Field | Meaning |
| --- | --- |
| transaction_id | Required. Your id for the payment; the same id again updates rather than duplicates. |
| amount | Required. A number in major units. Negative is not needed for a refund: send refunded: true instead. |
| currency | Three letters. Defaults to the website's currency. |
| visitor_id, session_id | From attribution(). The direct match. |
| customer_id, email, name | Who paid. Email is the fallback match against identified visitors. |
| timestamp | ISO 8601. Defaults to now. |
| renewal | true for a subscription renewal, which the MRR figures treat differently from a first payment. |
| refunded | true to record a refund of the same transaction_id. |

## POST /api/v1/goals

A goal reached on your server, such as a signup that completes in a backend job. It is attached to the visitor's latest session; a visitor the website has never seen answers 404.

Body:
```
{ "visitor_id": "<ml_visitor_id>", "name": "signup_completed", "props": { "plan": "pro" } }
```

## POST /api/v1/deploys

A release marker: a line on the chart with the release beside it, so a drop in revenue or Core Web Vitals can be read against what shipped. One curl at the end of your pipeline.

deploy.yml:
```
curl -X POST https://geckostats.com/api/v1/deploys \
  -H "Authorization: Bearer <site-key>" -H "Content-Type: application/json" \
  -d '{ "name": "v2.4.0", "sha": "'$GITHUB_SHA'", "url": "https://github.com/you/repo/releases/v2.4.0" }'
```

Fields: name or version, sha, url, and an ISO timestamp that defaults to now. The reply is { ok, id, ts }.

## POST /api/v1/crawls

Which AI crawlers read your pages, from your own server logs: GPTBot, ClaudeBot and the rest, classified by whether they came to train, to index, or to answer a question somebody was asking right then. One hit as { ua, path, ts, status }, or a batch as { hits: [ … ] } of up to 500. Unknown agents are counted as skipped rather than stored, and the reply says how many were recorded and how many skipped.

---

# Goals, and who the visitor is

A goal is a thing a visitor did that you care about. Identifying a visitor is what turns a trail of visits into a person, and what lets a payment be matched by email when nothing else carries the identity.

_Updated 2026-11-15._

## A button as a goal

HTML:
```
<button data-ml-goal="signup_click">Get started</button>
<a href="/checkout" data-ml-goal="checkout_click" data-ml-goal-plan="pro">Buy Pro</a>
```

No JavaScript needed. Use short snake_case names; every data-ml-goal-* attribute becomes a property of the goal, so plan="pro" above is recorded with it. Funnels are built from goals and pageviews in the dashboard, step by step.

## A goal from code

JavaScript:
```
window.geckostats?.('goal', 'signup_completed', { plan: 'pro' });
```

Call it with optional chaining so a page never breaks when the script is blocked. Calls made before the script has loaded are queued and sent once it has. A goal that completes on your server goes through POST /api/v1/goals instead.

## Identify a signed-in user

JavaScript:
```
window.geckostats?.('identify', { user_id: user.id, email: user.email, name: user.name });
```

After a login or signup, and on app load when a session already exists. Earlier anonymous visits by the same visitor join the person, their profile shows the whole trail, and a payment that arrives with only an email is matched to them.

## Newsletter links

Put ?ml_uid=<your subscriber id> on the links in a newsletter and the click is tied to that subscriber: the visit, what they read, and anything they buy afterwards. The id is yours and opaque here; never put an email address in it. The parameter is stripped from every address the script reports.

## TypeScript

geckostats.d.ts:
```
declare global {
  interface Window {
    geckostats?: ((cmd: 'goal' | 'identify' | 'pageview', a?: unknown, b?: unknown) => void) & {
      attribution?: () => { ml_visitor_id?: string; ml_session_id?: string };
    };
  }
}
export {};
```

---

# MCP server

The dashboard's own read path, exposed as 26 tools. Any client that speaks MCP gets the same figures the dashboard shows, and so does a curl, because the server is plain JSON-RPC over HTTP.

_Updated 2026-11-15._

## Connect a client

Claude Code:
```
claude mcp add --transport http geckostats https://geckostats.com/api/mcp \
  --header "Authorization: Bearer <site-key>"
```

Cursor, ChatGPT, Claude, Gemini CLI and anything else that speaks MCP: the server is at /api/mcp, the transport is HTTP, the auth is the website's key as a bearer token. The key is on the API and MCP keys step of the website, and is scoped to that website alone.

## The 26 tools

| Tool | What it answers |
| --- | --- |
| list_sites | The website this key can read, with its timezone and revenue currency. |
| site_overview | Headline numbers for a period and the period before it: visitors, sessions, pageviews, bounce rate, revenue, payments, customers. |
| top_pages | Most visited pages, with the revenue from people who saw each one. |
| top_sources | Where visitors came from, with visitors, revenue and paying customers each. |
| top_goals | Goals reached in the period, with the revenue of the visitors who reached them. |
| geography | Visitors and revenue by country, region or city. |
| devices | Visitors and revenue by device type, browser or operating system. |
| breakdown | Visitors and revenue by any dimension: campaigns, ref tags, channels, entry and exit pages, hostnames. |
| customers | Every payment in the period: amount, who paid, renewal or not, and the visit it is credited to. |
| visitors | Recent visitors, where they came from, what they spent, and anything identify() knows about them. |
| visitor_profile | One visitor end to end: visits, every event in order, payments. |
| realtime | Who is on the site now, which page, and the last events as they happened. |
| list_funnels | The funnels defined for this website, with their steps and ids. |
| funnel_stats | How many visitors reached each step of a funnel, and where they dropped out. |
| retention | Who came back, week by week, and what the returners were worth. |
| subscriptions | MRR now, how many subscriptions are running, trialing, past due or cancelling, churn and lifetime value by source. |
| deploys | Releases recorded in the period, newest first. |
| search_queries | What people searched on Google to reach the site: clicks, impressions, CTR, position, by query, page, country, device or Discover. |
| seo_opportunities | What is worth doing about search, ranked by money: striking-distance queries, pages losing clicks, and the rest. |
| index_status | What Google's index says about the pages that earn. |
| ai_vs_search | Google against the AI assistants, day by day: Search Console clicks next to visits from ChatGPT, Claude, Perplexity and the rest. |
| ctr_pressure | Queries losing clicks while holding their position, the shape an answer above the results leaves. |
| vitals | 75th-percentile LCP, INP, CLS and TTFB from real visits. |
| site_install | The snippets for this website: the tag, a goal, an identify call. |
| create_funnel | Writes. Defines a funnel of 2 to 10 steps, each a page path (wildcards allowed) or a goal name. |
| rematch_payments | Writes. Tries again to link payments that have no visitor yet, and reports why each could or could not be matched. Safe to re-run. |

Twenty-four tools only read, and say so in their annotations. Every tool runs the dashboard's own queries against your data and returns that figure or an error; nothing is reasoned about on the server, so a tool cannot make a number up. Periods are the dashboard's: today, yesterday, 24h, 48h, 7d, 30d, 90d, 12m, all, or custom with from and to.

## From a script

curl:
```
curl -s https://geckostats.com/api/mcp \
  -H "Authorization: Bearer <site-key>" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"top_sources","arguments":{"period":"30d","limit":5}}}'
```

The result is standard MCP: result.content[0].text holds the tool's JSON. tools/list returns every tool with its input schema.

---

# Search Console

Google never tells a website which search brought someone, but it tells Search Console. Connected, every query appears next to the revenue of the page it landed on.

_Updated 2026-11-15._

## Connecting

On the Search Console step of the website, sign in with Google and pick the property. The one permission asked for is webmasters.readonly, and the refresh token is stored encrypted. A domain property (sc-domain:example.com) covers every subdomain and protocol; a URL-prefix property covers exactly that prefix.

The first sync runs the moment the property is chosen. After that the sync is hourly, a few days at a time: ninety days of history fill in backwards while new days arrive at the front.

## Freshness

> Search Console publishes about three days late. Today and yesterday are never there, and every view that shows search data says how far it has actually got.

## What you get

- Queries, pages, countries, devices and Discover, with clicks, impressions, CTR, impression-weighted position, and the estimated revenue of the page each query lands on.
- Opportunities ranked by money rather than volume: what an extra click is worth on this page, times the clicks a better position would bring.
- CTR pressure: queries losing clicks at an unchanged position, which is the shape an AI answer above the results leaves behind. Inferred, and labelled as such.
- Index status for the pages that earn, through the URL Inspection API; no crawler and no sitemap parsing.
- Alerts for organic clicks down, a page deindexed, a query dropped five places, and clicks lost at the same position.

---

# Alerts

Six things worth being told about, checked every hour, sent where you read: email, Slack, Discord or any URL.

_Updated 2026-11-15._

## The six

| Alert | Fires when |
| --- | --- |
| tracking_stopped | No events for a day on a website that had traffic. |
| revenue_drop | This week against last, past the threshold you set. |
| organic_drop | Search Console clicks, this week against last. |
| deindexed | A page that earns is missing from Google's index. |
| position_drop | A query fell five places or more. |
| ctr_collapse | Clicks lost at the same position. |

## Delivery

Turn each alert on in the website's Alerts step and give it an email address, a webhook URL, or both. A Slack or Discord webhook URL is recognised and gets that platform's own message format. Any other URL receives JSON:

POST body:
```
{
  "site": { "id": "<website-id>", "domain": "example.com", "name": "Example" },
  "ts": 1763222400000,
  "alerts": [
    { "kind": "revenue_drop", "message": "Revenue is down 41% on last week: $412 against $688.", "payload": { … } }
  ]
}
```

---

# Privacy and your data

A visitor is a salted hash that rotates every day and the IP address is never stored. There is no cookie, so there is nothing to consent to, and the banner can go.

_Updated 2026-11-15._

## Counting without cookies

The visitor id is a daily-rotating salted hash of IP address, user agent and website. Nobody can be followed across days or across websites, and the inputs are not kept. Returning visitors within a day are recognised; across days they are new, which is the trade the privacy property costs, and the retention figures are built with that in mind.

## Cookie mode

When identity across days matters more than the privacy property, a website can turn cookieless off in its settings. The script then sets a first-party cookie, ml_vid, and a session cookie, ml_sid, on your domain only; data-domain on the tag decides the cookie's domain when the script runs on a subdomain. That is a cookie in the legal sense, and your consent obligations are yours.

## Leaving your own visits out

Turn on owner exclusion in the website's settings and your own devices are recognised by the same daily hash, recorded when you open the dashboard, and kept out of the numbers. List your other domains, docs or the app, and traffic from them stops being a referral.

## Export and deletion

Your data step in the account settings exports one CSV per table, newest first. It still works after a plan has ended, which is when you are most likely to want it. Deleting a website removes everything it recorded; deleting the account removes every website. After a plan ends nothing is deleted before the date shown on the billing page, and that page says what the date is.

---

# Webhooks, event by event

Payments arrive by webhook from the provider, never from the browser. This is exactly which events are read and what each one does.

_Updated 2026-11-15._

## Events read, per provider

| Provider | Endpoint | Events | Verified with |
| --- | --- | --- | --- |
| Stripe | /api/webhooks/stripe/<website-id> | checkout.session.completed, checkout.session.async_payment_succeeded, invoice.paid (subscription invoices only), charge.refunded | The endpoint signing secret, per website |
| Polar | /api/webhooks/polar/<website-id> | order.paid, refund.created, refund.updated | Standard Webhooks signature; payload format Raw |
| Creem | /api/webhooks/creem/<website-id> | checkout.completed, subscription.paid, refund.created | Creem's signature header |
| Dodo Payments | /api/webhooks/dodo/<website-id> | payment.succeeded, refund.succeeded | Standard Webhooks signature |

Any other event answers ok and is ignored, so subscribing an endpoint to everything is harmless. Every endpoint is per website, and the secret is pasted into that website's Connect payments step; an event that fails verification answers 401 and nothing is written.

## Repeats, renewals and refunds

- The same event twice writes the same row twice, which is one row: payments are keyed by the provider's own id, so retries are safe.
- A subscription's first invoice can arrive both as a checkout and as an invoice; the shared id makes them one payment.
- A renewal is recorded as a renewal, which the MRR figures treat differently from a first payment.
- A refund is a negative row against the original payment and inherits its visit, so refunded revenue leaves the same source it arrived from. A second partial refund replaces the first rather than adding to it.

## A payment before its visit

A webhook can arrive before the pageview that produced the sale, or carry an identity the website has not seen. The payment is held rather than dropped, matched when the identity catches up, and listed in the website's Connect payments step while it waits. The rematch_payments MCP tool does the same by hand and says, per payment, why it could or could not be matched.

## One account, several websites

Stripe sends every event to every endpoint, so two websites on one Stripe account each receive each payment. A payment is placed by an ml_site_id key in its metadata if you set one, else by the website the visitor was seen on, else, for a renewal, by where that customer paid before; one that none of those place on a website is not recorded there. Dodo Payments places by product: list each website's product ids in its settings.

---

# Troubleshooting

The four things people write in about, each with the places to look, in the order that finds the cause fastest.

_Updated 2026-11-15._

## No visits are arriving

- You are on localhost. The script ignores it unless the tag carries data-allow-localhost.
- The tag is not on this page, or loads twice. View the page source and search for data-website-id; it should appear once, with this website's id.
- A Content-Security-Policy blocks it. The console says so; allow https://geckostats.com in script-src and connect-src, or serve the script from your own domain.
- A content blocker drops the request. Serving the script from your own domain (see Install) gets past most of them.
- The request is sent but refused. In the Network tab, the POST to https://geckostats.com/api/event should answer 202; a 4xx means a wrong website id or a domain that does not match the website's.

The install step of each website watches for the first event and says when it has arrived, so leave it open while you check.

## A payment is missing or not attributed

- Is it held? The Connect payments step lists payments waiting for a visit. If the sale is there, the webhook worked and the identity did not arrive with it: check the metadata and the success page on the attribution page.
- Did the webhook arrive at all? The endpoint URL must carry this website's id, the secret must be the one pasted into the step, and the provider must be sending the events listed on the webhooks page. Test mode and live mode are separate endpoints with separate secrets.
- Is it on another website? Two websites on one Stripe account each receive every payment; the placement rules on the Stripe page decide which records it.
- Is it an amount problem? The server-to-server API takes major units, 29.99 not 2999.

## The search panel is empty

- Search Console publishes about three days late. Today and yesterday are never there; widen the period.
- The first sync runs when the property is chosen; after that it is hourly, a few days at a time, ninety days of history filling in backwards. The Search Console step says how far it has got.
- The property has to be the one that holds this website's data. A domain property covers every subdomain and protocol; a URL-prefix property covers exactly that prefix.

## The numbers differ from another tool

- Visitors are counted without cookies, from a hash that rotates daily, so a person who returns tomorrow is a new visitor here and a returning one in a tool that sets a cookie. Turn cookie mode on in the website's settings if identity across days matters more to you than the privacy property.
- Your own visits are left out once owner exclusion is on, and traffic from your other domains stops being a referral once they are listed.
- Crawler hits are counted separately and never as visitors.
- Times are in the website's timezone and money in its currency, both set in its General settings; a tool on a different clock splits days differently.

---

# Plans, billing and your account

Two plans on one ladder of sizes, priced by events a month. Every feature is on both; websites and seats are the whole difference. Every plan starts with 14 days free and no card.

_Updated 2026-11-15._

## What each plan carries

| Events a month | Starter, a month | Starter websites | Growth, a month | Growth websites |
| --- | --- | --- | --- | --- |
| 25K | $9 | Up to 5 | $15 | Up to 100 |
| 100K | $19 | Up to 10 | $29 | Up to 100 |
| 250K | $29 | Up to 15 | $45 | Up to 100 |
| 500K | $49 | Up to 20 | $75 | Up to 100 |
| 1M | $69 | Up to 30 | $105 | Up to 200 |
| 2M | $99 | Up to 40 | $149 | Up to 200 |
| 5M | $149 | Up to 50 | $219 | Up to 200 |
| 10M | $199 | Up to 50 | $299 | Up to 200 |

Seats are the plan's rather than the size's: 3 on Starter, 30 on Growth. An event is a pageview, a goal or a payment; crawler hits are counted separately and do not use the allowance. Yearly billing is twelve months for the price of ten.

Going over the allowance loses nothing: the dashboard keeps counting and says so. Collection stops only at twice the allowance, and two months over in a row is when you are asked to move up a size.

## The trial

14 days, no card, and the trial gets what Growth gets, so a trial that refuses the second website is not a trial of the bigger plan. It starts the moment the account is created and the charge happens only when a plan is picked.

## Changing plan or size

Settings, Plan and billing, Change plan or size. The change takes effect the moment you confirm it, with the difference for the rest of the period charged today, pro rata. A website limit that has been reached says the same thing in the add-website form, with the plan that has more.

## When a plan ends

The dashboard is locked, and the websites keep collecting for the same week the data is kept: every visitor, payment and funnel from before and after the plan ended is there until the date shown on the billing page, and the paywall says how much arrived while it was locked. Picking a plan before then opens all of it again with nothing to install. The export in Your data keeps working throughout.

## Deleting

Deleting a website, from its Danger zone, removes everything it recorded: events, sessions, visitors, payments, funnels, search data, alerts and keys. Deleting the account, from the account's Danger zone, removes every website the same way and cancels the subscription.

---

# Sharing, seats and export

Three ways to let somebody else at the numbers, each giving exactly as much as it says.

_Updated 2026-11-15._

## A shared link

Share a link, in the website's settings, makes a read-only dashboard at its own address for someone who will never have an account: a client, an investor, a co-founder. It can be revoked there in a second.

The numbers travel; the people behind them do not. A shared link can read the overview, sources and pages, funnels, retention, subscription totals, Core Web Vitals, releases, crawlers and the whole search panel. It cannot read individual visitors or customers, the live view, the settings or any key, and the Worker refuses those requests whatever the page asks for.

## Seats

Invite a colleague by email from the account's Team settings. A seat reads every website on the account and changes nothing: no settings, no keys, no billing, no invitations of its own. Starter seats 3 people including you, Growth 30. A second invitation to the same address replaces the first, which expires the earlier link at the same moment.

## Export

Your data, in the account settings, exports one CSV per table, newest first: sessions, events, payments and visitors, up to 50,000 rows each. It still works after a plan has ended, which is when you are most likely to want it.
