See the story behind every dollar.

Connect visits to verified payments. Follow the path from the first page to the moment someone becomes a customer.

This is an illustrative journey, not customer data. TideStat preserves the live map, anonymous visitor characters, Website Footprints and event stream, then adds the payment evidence that makes those visits meaningful.

Your first complete story

1. Sign in and add your website. TideStat creates its website ID and registers its origin.
2. Copy the Agent task or add the hosted tracker to your website. Honor the visitor’s consent choice.
3. Observe page views, then instrument checkout and any signup step your website uses.
4. Pass the SDK attribution context to your payment creation flow.
5. Send a signed test payment and inspect its Revenue Story.

A successful setup shows both the observed visit timeline and the verified payment. Missing identifiers should produce an unattributed payment, never an invented journey.

TideStat · Revenue Story documentation · Schema v1

NPM SDK / Package

Typeable, explicit event tracking for JavaScript sites. Use the same canonical schema as Shopify.

Install

npm install @waterme7on/tidestat-browser-sdk

Run this in your website project. For websites without a package build, use the hosted Browser SDK; no npm installation is needed.

Initialize once in the browser

import { createTideStat } from '@waterme7on/tidestat-browser-sdk';

const tide = createTideStat({
  siteId: 'my-site',
  endpoint: 'https://tidestat.yololab.cc/api/collect',
  consent: false,
  autoPageview: true,
  trackClicks: false
});

// Call after your consent flow permits analytics.
tide.setConsent(true);
// Call when your application confirms the signup.
tide.track('signup', { plan: 'pro' });

Create a single instance on the client; do not initialize during server rendering or on every component render. Use destroy() when removing an integration. Do not combine the browser module, npm instance and legacy tracker on the same page.

Track the meaningful steps

tide.track('checkout', { plan: 'pro' });
tide.track('custom', { name: 'comparison_opened' });
const attribution = tide.attribution();

Automatic page views include pathname navigation; query strings and fragments are excluded. Sessions expire after 30 minutes of inactivity. After consent, outbound-link tracking is enabled by default; set trackOutbound: false to disable it. Outbound URLs and referrers retain only origin and pathname. Custom properties accepted by the collector are string values for name, label, target, product_id, plan and order_id. Forward attribution to your server when creating a checkout. The returned keys are tidestat_site_id, tidestat_visitor_id and tidestat_session_id. Never send payment credentials or dashboard tokens to this SDK.

Verification

Check the collection request succeeds and that the visitor appears for the same site in the dashboard. A browser purchase event is behavior evidence; only the verified payment connector contributes money.

Continue with script / browser module setup or Stripe payment linking.

TideStat · Revenue Story documentation · Schema v1

Browser SDK

Use a browser module when your website does not have a package build step.

<script type="module">
  import { createTideStat } from
    'https://tidestat.yololab.cc/sdk/index.js';

  const tide = createTideStat({
    siteId: 'my-site',
    endpoint: 'https://tidestat.yololab.cc/api/collect',
    consent: false
  });
  // Connect this to your real consent manager, not a timer.
  window.enableTideStat = () => tide.setConsent(true);
</script>

Alternatively, insert this wrapper only after analytics consent is granted:

<script type="module"
  src="https://tidestat.yololab.cc/t.js"
  data-site="my-site"
  data-consent="true"></script>

It exposes window.tidestat. The module option is required; an old classic script tag will not work. The canonical /t.js module flow has been verified in a cross-origin browser test; merchant payment setup still requires your own end-to-end verification. Use the hosted TideStat asset URL shown above. Events are sent to TideStat for storage and visualization; you only publish the tracker changes to your own website.

Existing websites

The /t.js endpoint redirects to the browser module wrapper. Use a module script and explicit site configuration when migrating an old tag. Migrating to the canonical SDK adds session context and business events. Remove the old script after enabling the new integration to avoid duplicate page views. Historical legacy events are not retroactively linked to payments.

Automatic versus intentional tracking

Automatic page views describe navigation. Add signup and checkout events only when your application reaches that state. Prefer selected, non-sensitive click labels over recording all text on the page.

TideStat · Revenue Story documentation · Schema v1

Shopify

Connect storefront visits to paid orders using explicit attribution attributes.

1. Configure the website

Set the storefront origin, Shopify webhook secret and exact shopDomain in the website’s server-side configuration. Use the same site ID across the storefront, pixel and webhook URL. If the Shopify pixel sends a null Origin from its sandbox, explicitly add the string "null" to this site’s allowedOrigins array. This opts in untrusted client collection; it does not authorize payments or dashboard reads.

2. Install storefront tracking

Initialize the browser SDK in your storefront theme with autoPageview: false when the pixel handles page views. Before checkout, persist the attribution context as cart attributes using the Shopify Ajax Cart API:

const context = tide.attribution();
const cartRoot = window.Shopify?.routes?.root || '/';
await fetch(cartRoot + 'cart/update.js', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ attributes: context })
});

Use the provided attachTideStatCart helper from cart-attribution.mjs in production. Await the attempt before checkout, but do not block purchases if analytics fails. On withdrawal, call tide.setConsent(false) and clearTideStatCart(). Implement this in your actual checkout flow; simply adding a click listener can race the checkout navigation. Storefront IDs and pixel sandbox IDs are not automatically interchangeable.

3. Add customer events

Use the customer-pixel adapter and its installation notes. The adapter translates Shopify customer events into the same canonical event schema. Checkout-completed browser events remain unverified behavior.

4. Register the paid-order webhook

https://tidestat.yololab.cc/api/webhooks/shopify?site=my-site

Subscribe to orders/paid and refunds/create. TideStat verifies the raw-body HMAC and configured shop domain, then accepts orders with financial_status: paid. Order IDs make repeated deliveries idempotent. Refunds sum successful refund transactions and link to the original order; linked refunds inherit its attribution.

5. Verify the entire path

Place a test order through your storefront. Confirm that the order carries the three tidestat_* note attributes, the webhook succeeds, and the Revenue Story contains the matching visit. An order without known matching context stays unattributed. Accelerated checkout flows that skip your cart-linking step need separate testing.

TideStat · Revenue Story documentation · Schema v1

Canonical event schema

One event language for websites, the npm package and Shopify.

{
  "schema_version": 1,
  "event_id": "a-unique-event-id",
  "site_id": "my-site",
  "visitor_id": "anonymous-site-local-id",
  "session_id": "session-id",
  "type": "signup",
  "path": "/pricing",
  "referrer": "https://www.google.com/",
  "occurred_at": 1788652800000,
  "properties": { "plan": "pro" },
  "acquisition": {
    "source": "google", "medium": "organic", "campaign": ""
  }
}

Send to POST /api/collect. Use Unix milliseconds for occurred_at and a stable unique event ID for retries. Website configuration controls allowed collection origins. The SDK generates identity and event IDs for you.

Data relationships

A site owns visitors, sessions, events and payments. A visitor may have multiple sessions. A session has ordered events. Verified payments hold explicit visitor and session links when those links can be validated. A Revenue Story assembles the observed history with its payment evidence.

Read APIs

GET /api/revenue?site=my-site&days=30
GET /api/stories?site=my-site&visitor=visitor-id
GET /api/live?site=my-site
Authorization: Bearer YOUR_SITE_READ_TOKEN

The stories endpoint supports exact visitor, source and currency filters, plus offset and limit (at most 100). Read total and nextOffset for pagination. The revenue summary includes at most 100 stories and exposes storyCount/nextOffset. Individual timelines are capped at 200 events with timelineTruncated when incomplete. Dashboard reads require your signed-in account. The site ID in a public tracker is not a credential.

TideStat · Revenue Story documentation · Schema v1

Stripe payment linking

Attach the visit context when your server creates Checkout. Confirm the money through a signed webhook.

1. Forward attribution to your server

const context = tide.attribution();
// Include context in your application's checkout creation request.

Validate the incoming context in your application. Copy those three keys into Checkout Session metadata when your server creates the Stripe session:

metadata: {
  tidestat_site_id: context.tidestat_site_id,
  tidestat_visitor_id: context.tidestat_visitor_id,
  tidestat_session_id: context.tidestat_session_id
}

2. Configure the webhook

https://tidestat.yololab.cc/api/webhooks/stripe?site=my-site

Subscribe to checkout.session.completed, checkout.session.async_payment_succeeded, invoice.paid, refund.created, refund.updated and charge.refunded. For subscriptions, also pass the attribution keys into subscription_data.metadata so renewal invoices can preserve the link. Have the TideStat operator activate the connector and securely configure its signing secret; self-service connector activation is not yet available. TideStat checks the signature against the raw request body and enforces a five-minute timestamp tolerance.

3. Verify the result

Only sessions with payment_status: paid become payments. Checkout confirmations deduplicate on Checkout Session ID. Invoice and payment-intent aliases prevent double-counting an initial invoice also seen through Checkout. Paid invoices use amount_paid; refunds are dated by their own creation time and count only when status: succeeded. The connector deduplicates individual refund IDs. charge.refunded also expands its refund list, but that list can be partial: subscribe to the independent refund events too.

The site, visitor and session metadata must all match a known session for this site. A payment received before its matching session remains unattributed until later event ingestion can reconcile its explicit context. TideStat does not guess by email address, name or IP.

TideStat · Revenue Story documentation · Schema v1

Google Search Console

Add organic search context at the aggregate level, with a clear boundary around individual journeys.

Import shape

POST /api/search-console?site=my-site
Authorization: Bearer YOUR_SITE_READ_TOKEN
Content-Type: application/json

{
  "rows": [{
    "date": "2026-09-01", "page": "https://example.com/guide",
    "query": "example search", "clicks": 12, "impressions": 320,
    "ctr": 0.0375, "position": 8.4
  }]
}

Read imported data with GET /api/search-console?site=my-site using the same authorization. Query, page, date and the metrics belong to a site-level search dataset.

What you can say

“This page received 12 Google Search clicks for this query on this date.” You may place that aggregate context alongside the page’s recorded revenue performance.

What you cannot say

“Visitor 123 searched this keyword.” Search Console does not supply this individual link. Google Search clicks and tracked visitors also differ in measurement scope, consent, time zones and processing delay; they are not interchangeable.

TideStat · Revenue Story documentation · Schema v1

Attribution & evidence

Explain the revenue path without claiming to know more than your data shows.

What the story means

The timeline is the observed sequence of visits and events before payment. It can show the landing page, acquisition context, returning sessions, conversion steps and verified payment. The sequence is evidence of what happened; it does not prove which individual action caused the purchase.

First observed touch

Source and landing-page attribution use the visitor’s first observed touch in retained data. This is not necessarily their first-ever visit. A cleared browser, declined consent, another device or uninstrumented page can break the journey. There is no cross-device identity inference.

Returning visitors

Returning contribution depends on multiple recorded sessions for the same site-local visitor ID. It is not the same as “all repeat customers”: a customer may return from another browser or device.

Coverage matters

Payments with a valid explicit session link are attributed. Payments without one remain unattributed. Review that coverage before comparing revenue sources. Queries are bounded (including 20,000 events and 5,000 payments) and flag truncation; a truncated result is not a complete historical census.

Money stays in its currency

Revenue is net observed receipts: supported paid events minus observed refunds, in provider minor units and their original currency. Gross amounts can include taxes and shipping; fees and disputes are excluded. There is no FX conversion or accounting reconciliation. Compare like currencies; never sum USD and EUR into one dollar total.

TideStat · Revenue Story documentation · Schema v1

Journeys, sources & leaks

Use the live map as the beginning of the investigation, then follow the revenue evidence.

Revenue Stories

Start with a payment or visitor. Inspect the ordered visits, key behavior, conversion steps and payment link. Use site and date controls to narrow your investigation, then examine a returning visitor’s sessions.

Revenue Journeys & Sources

Compare observed paths and first-touch sources by verified revenue, visitors and revenue per visitor. Page revenue describes payments associated with the reported attribution model; it does not mean the page alone caused the payment. Journeys shows two ordered funnels: the commerce funnel (page_view → checkout → payment) includes guest checkout, while the separate signup funnel (page_view → signup → checkout → payment) measures paths that require registration.

Read the dimensions correctly

Channels, referrers, campaigns, explicit UTM keywords, geography, browsers, operating systems and devices attribute revenue to the first captured visitor context. Missing historical context stays Unknown. Browser and OS labels come from the user agent, not fingerprinting. Keyword reports contain explicit utm_term only; organic search queries remain separate aggregate Search Console data.

Pages and outbound links are observed prepayment assisted touchpoints. Their revenue can overlap, so do not add their rows into a total or infer causation. Entry and exit pages are the payment session’s first and last observed pages; an exit does not prove the browser closed. Daily and weekday/hour reports use UTC. Time-to-revenue and visits-to-revenue distributions use the first known positive payment and exclude renewals.

Revenue Leaks

Find observed conversion-step drop-off, such as visitors who started checkout without a linked payment in the reporting window. These are candidates for investigation, not proof of permanently lost sales. Delayed webhooks, unlinked payments and purchases outside the window can inflate apparent drop-off.

Keep the website alive

The real-time visitor count, map and Website Footprints remain ways to see people moving through your website. The live event stream includes signup, checkout and unverified browser purchase signals alongside explicitly labeled verified payments and refunds. Open the same visitor’s Revenue Story from the stream to connect those signals with the observed path. A live signal is not a revenue signal until there is payment evidence.

TideStat · Revenue Story documentation · Schema v1

Multiple websites

Keep traffic, sessions, payments and analytics reads scoped to the right website.

Sign in and own your websites

Open your account and sign in with Google. Websites created there belong to the signed-in account. The account’s plan controls website count and monthly event allowance; every plan includes the same analytics, Revenue Story and live features.

Free includes 1 website and 10,000 monthly events. Starter is USD 9/month or USD 90/year, with 3 websites and 100,000 monthly events. Growth is USD 29/month or USD 290/year, with 10 websites and 1,000,000 monthly events. Yearly prices are the full annual charge. See pricing for the current catalog.

Paid entitlements are granted only after the server verifies the current Stripe subscription. Returning from checkout or changing a URL does not activate a paid plan. The account page reports whether Google sign-in and paid billing are configured; displaying a plan is not evidence that live billing is activated.

Event allowances reset by calendar month in UTC and are shared across the account’s websites. Accepted canonical behavior events count once after deduplication; activity heartbeats support live presence without consuming the allowance. New events over the allowance are rejected with HTTP 429. Downgrading retains existing websites and readable history, blocks creation beyond the new website limit, and applies the new shared event allowance.

The public GET /api/plans endpoint supplies the plan catalog and a billingAvailable configuration flag. That flag describes deployment readiness, not the signed-in account’s paid entitlement. Static pricing previews use the same listed fallback amounts when this API is unavailable.

Connect each website

Select a website in your account and open Website setup. Copy the Agent task or install the hosted tracker manually with that website’s ID. Your account session authorizes dashboard access; no read token or service deployment is needed.

Keep websites separate

Use the matching website ID and registered origin in every tracker. TideStat checks account ownership before showing analytics. A public website ID does not grant access to private data. Select the intended website before verifying a new visit.

Additional origins and payment connectors currently require TideStat operator assistance; they are not a self-service server deployment task. Browser pageviews can be verified independently.

TideStat · Revenue Story documentation · Schema v1

Connect your website

TideStat stores your events and turns them into visual analytics. Add the tracker to your website; we run the analytics service.

1. Add your website

Sign in to TideStat and add your website URL. Select the website to open its setup guide. Your website ID and registered origin are supplied for you.

2. Install the tracker

Recommended: copy the Agent task from Website setup into your website project. It reads the TideStat Skill, adds the hosted tracker and connects your existing consent flow. You can also download the Skill or follow the manual browser guide. No npm package, TideStat repository or server deployment is required for the hosted tracker.

3. Verify and explore

Publish the changes to your own website, check its connection in TideStat, then open the website and allow analytics through its consent flow. Visit a page and check for a new pageview. Once verified, explore your dashboard, live visitors and site journeys.

Who does what?

You add the tracker and control visitor consent on your website. TideStat receives and stores the events, isolates your websites, and provides visual reports. Never place private credentials in the tracker.

Optional payment data

Pageviews do not require a payment integration. Verified revenue requires a separately configured Stripe or Shopify connector. Connector activation currently needs TideStat operator assistance; a self-service credential form is not yet available. Do not deploy your own analytics service or send signing secrets in an Agent task.

Privacy & data boundaries

Collect only the context needed to explain the journey.

The SDK uses anonymous, site-local identifiers. Anonymous does not mean there are no privacy obligations: session paths and payment metadata can still be sensitive.

Consent and minimization

Initialize with consent: false where consent is required, then enable collection through your consent manager. Do not send email addresses, names, payment details, tokens, form text or sensitive URL parameters in custom properties. Revocation stops tracking and clears SDK identity, but does not erase already collected server data. Blocked storage falls back to memory. Test revocation and storage behavior in your integration.

Geography and identity

Cloudflare supplies approximate geographic context for the real-time map. The collector does not need to store raw IP addresses. Map positions are approximate, and missing geography should remain unknown. A cartoon avatar is an anonymous visualization, not a personal identity.

Retention

Revenue history is stored separately from the legacy short-lived realtime event table. Do not apply the old “24 hours” claim to revenue data. TideStat operates data storage. A self-service deletion portal is not yet available; contact the TideStat operator for retention or deletion requests.

Trusted versus untrusted events

Browser analytics can be blocked or forged. Origin checks and schema validation are not proof of payment. Only signed provider payment events populate monetary results. Payment links still require the matching site, visitor and session context.

TideStat · Revenue Story documentation · Schema v1

Troubleshooting

Work from collection to identity to payment, then inspect the story.

No visitor or events

• Confirm consent is enabled and the tracker is initialized in the browser.
• Check the exact site ID and allowed website origin.
• Inspect the collection response and browser network restrictions.
• Make sure you are viewing your own website in TideStat, not the demo.

Unauthorized dashboard request

Sign in again and select a website owned by your account. The tracker uses a public website ID; your account session protects dashboard reads.

Payment appears without a journey

Inspect the provider metadata or Shopify order note attributes. All three context keys must be present and reference a known same-site session. Check whether checkout started before the session event reached the collector or whether a cart update was skipped.

Payment is missing

Check webhook delivery status, configured site, signature secret and supported event type. For Stripe, confirm payment_status: paid. For Shopify, confirm the configured shop domain and financial_status: paid. Client-side purchase events alone do not add revenue.

Revenue does not match the payment dashboard

Check reporting period, currencies, duplicate checkout IDs, missing webhooks and unsupported payment types, missing renewal metadata or refund events. TideStat reports supported receipts less observed refunds; it is not a full ledger.

The example looks complete but live data is empty

Demo data illustrates the interface. It does not confirm your tracker or connector setup. Run a test visit and test payment on your own configured website.

TideStat · Revenue Story documentation · Schema v1