TrackFox logoTrackFoxDocs
Dashboard
Docs/REVENUE/Connect Stripe (Automatic)

Connect Stripe (Automatic)

Connect a Stripe restricted API key once, and TrackFox will automatically ingest charges, refunds, and subscription renewals as revenue — no trackfox("payment", ...) calls or /api/v1/attribute-payment requests required.

Not Stripe Connect/OAuth. You create a restricted, read-only API key yourself in your own Stripe Dashboard, so you control exactly what TrackFox can see, and you can revoke it at any time from Stripe with no involvement from TrackFox.

How It Works

  1. You create a restricted Stripe API key with read access to Charges, Subscriptions, Customers, Payment Intents, Checkout Sessions, Invoices, and Products, plus write access to Webhooks, and paste it into TrackFox.
  2. TrackFox verifies the key, then uses that same webhook write permission to create the webhook endpoint on your Stripe account itself — listening for charge.succeeded, charge.refunded, and invoice.paid — and captures the signing secret Stripe hands back at creation time. You're done; no copy-pasting a URL or secret required.

The Webhooks write permission is required — without it, TrackFox can't finish connecting and tells you to grant it. There's no manual fallback: use the "Create restricted key on Stripe" button in Settings → Revenue, which pre-fills a key with the right permissions from the start.

Once connected, TrackFox listens for those events and matches each one to a visitor using an exact match on either:

  • client_reference_id — the value you set on the Stripe Checkout Session, read from the visitor's trackfox_visitor_id cookie
  • Email — matched against an email you've sent TrackFox via trackfox("identify", { email })

There's no fuzzy, IP-based, or time-proximity matching. A charge that matches neither signal is a documented limitation, not silent wrong data: it still won't appear on your dashboard at all, since TrackFox has no way to tie it to a visitor. Give it one of the two signals above to get full attribution.

Step 1: Create a Restricted API Key

The fastest way: on the Settings → Revenue tab, click Create restricted key on Stripe — it opens Stripe's key-creation form with the right permissions already selected, including Webhooks write access. Review them and click Create key on Stripe's side.

To do it manually instead:

  1. In your Stripe Dashboard, go to Developers → API keys → Create restricted key
  2. Name it something like "TrackFox"
  3. Grant Read access to:
    • Charges
    • Subscriptions
    • Customers
    • Payment Intents
    • Checkout Sessions
    • Invoices
    • Products
  4. Grant Write access to:
    • Webhooks
  5. Copy the key (starts with rk_test_ or rk_live_)

If you're editing permissions on an existing restricted key instead of creating a new one, Stripe lets you add Webhooks write access to it without regenerating the key.

Step 2: Connect the Key in TrackFox

  1. Go to your website's Settings → Revenue tab in TrackFox
  2. Paste the restricted key and click Verify & Connect
  3. TrackFox verifies the key, creates the webhook endpoint on your Stripe account, and shows "Connected" — nothing else to do

If the key is missing Webhooks write access, TrackFox tells you so and connection doesn't complete. Add the permission in Stripe (or create a new key using the button above) and try again.

Step 3 (Optional but Recommended): Set client_reference_id

For the most reliable attribution, read the visitor's cookie and pass it when creating your Stripe Checkout Session:

// Frontend: read the TrackFox visitor cookie
function getTrackFoxVisitorId() {
  const match = document.cookie.match(/(?:^|; )trackfox_visitor_id=([^;]+)/);
  return match ? match[1] : null;
}

// Send it to your backend along with the rest of your checkout request
const visitorId = getTrackFoxVisitorId();

// Backend: pass it through as client_reference_id
const session = await stripe.checkout.sessions.create({
  mode: "subscription", // or "payment"
  line_items: [{ price: "price_...", quantity: 1 }],
  client_reference_id: visitorId,
  success_url: "https://yoursite.com/success",
  cancel_url: "https://yoursite.com/cancel",
});

This works for both one-time payments and subscriptions — for subscriptions, TrackFox reuses the same match for every renewal, so you only need to set it once at signup.

Step 4 (Fallback): Identify by Email

If you're not using Stripe Checkout, or want a fallback for charges created directly via the Payment Intents API, call identify() with the customer's email before they pay (e.g. at signup or login):

window.trackfox("identify", { email: "customer@example.com" });

TrackFox will match incoming Stripe charges to this visitor by email if no client_reference_id is found.

Refunds

Refunds (including partial refunds) are automatically reversed: TrackFox records a negative-amount adjustment that nets out against the original charge in your revenue totals and every breakdown (source, location, device, etc.) — no action needed on your part.

Subscription Renewals

Renewal invoices (invoice.paid with billing_reason: subscription_cycle) are tracked automatically once the subscription's first charge has been matched — TrackFox remembers the match for that Stripe customer and reuses it for every future renewal, so you don't need to set client_reference_id again after the initial checkout.

Disconnecting

Disconnecting in TrackFox removes your key and deletes the webhook endpoint from your Stripe account — no manual cleanup needed. Past revenue already recorded is not affected, and reconnecting later goes through setup again (a new webhook endpoint is created each time).

What's Not Included

This is intentionally a lightweight, exact-match integration:

  • No Stripe Connect/OAuth — you manage the key yourself
  • No currency conversion — revenue is stored and totaled in whatever currency Stripe reports
  • No backfill — only events delivered after you connect are ingested; charges from before you connected won't appear retroactively
  • No dispute/chargeback handling
  • No fuzzy/IP/time-proximity matching — only exact client_reference_id or email matches

Troubleshooting

Revenue not appearing?

  • Confirm the webhook endpoint in Stripe shows successful deliveries (Stripe Dashboard → Developers → Webhooks → your endpoint TrackFox created)
  • Confirm you're setting client_reference_id or calling identify() before the charge happens — TrackFox can't attribute a charge it can't match to a visitor
  • Check the Revenue tab in Settings for a "last event received" timestamp and any error message

Still stuck?

Contact us at support@trackfox.app

Next Steps

Need help? Contact us for assistance.

Suggest features? We'd love your feedback