Stripe

The Taapit Stripe integration automatically tracks all your Stripe payments as sales conversions. Just install the SDK, connect the app, and pass the tracking ID to Stripe.

How it works

Prerequisites

Important: For conversion tracking to work, users must arrive on your website via a Taapit deeplink. This is how the tracking ID (ta_tid) is generated and passed to your site.

Before you start:

Create a Taapit deeplink pointing to your website or landing page
Enable conversion tracking on your link:
- Go to your link settings in the Taapit dashboard
- Enable Conversion Tracking
Configure Stripe integration in Settings → Conversion and select Stripe Integration

Installation

Install the Taapit SDK on your website

First, add the Taapit SDK to your website to capture the ta_tid tracking ID:

NPM Package (React/Next.js)
Script Tag (No Build Step)

npm install taapit-sdk

Then add the Analytics component to your root layout:

app/layout.tsx

import { Analytics } from 'taapit-sdk/react';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Analytics />
      </body>
    </html>
  );
}

Add this script to your HTML <head> or before </body>:

<script src="https://taap.it/api/sdk"></script>

This step is required. Without the SDK, the ta_tid won’t be captured and conversions can’t be tracked.

Install the Stripe App

Go to the Stripe App Marketplace
Search for “Taapit Conversion”
Click Install

Or install directly from your Taapit dashboard:

Go to Settings → Integrations → Stripe
Click Install Stripe Integration

Connect your Taapit workspace

After installing the app in Stripe:1. Open the Taapit app in your Stripe dashboard and click “Connect workspace”

Taapit Stripe App - Connect workspace button

2. Authorize the connection to your Taapit workspaceYou will be redirected to the Taapit consent page. Select the workspace you want to connect and click Authorize.

3. Verify the workspace is connectedOnce authorized, you will see your workspace connected in the Stripe app.

Pass the tracking ID to Stripe

Pass the ta_tid to Stripe when creating customers, checkout sessions, or payment intents.

1. Frontend: Get the tracking ID

First, retrieve the tracking ID from your frontend to pass it to your API:

With Taapit SDK
With React Hook
From Cookie directly

// Using the taapit global object (script tag)
const trackingId = taapit.getTrackingId();

import { useTaapitAnalytics } from 'taapit-sdk/react';

function CheckoutButton() {
  const { trackingId } = useTaapitAnalytics();

  const handleCheckout = async () => {
    const response = await fetch('/api/create-checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        priceId: 'price_xxx',
        trackingId,
      }),
    });
    const { url } = await response.json();
    window.location.href = url;
  };

  return <button onClick={handleCheckout}>Subscribe</button>;
}

The tracking ID can be retrieved from:

Taapit SDK - taapit.getTrackingId() or useTaapitAnalytics() hook
Cookie (ta_tid) - automatically set by the SDK

The backend should check both the request body and cookies for maximum compatibility.

2. Track Sales: Create a Checkout Session

When a user makes a purchase, pass the tracking ID in the checkout session metadata.

When is taapitTrackingId required for Checkout Sessions?

If the customer was already tracked via a lead event (using taapitCustomerExternalId), the taapitTrackingId is optional - you only need to pass taapitCustomerExternalId to link the sale.
If this is a new customer (no prior lead), taapitTrackingId is required to attribute the sale.

app/api/create-checkout/route.ts

import { NextRequest } from 'next/server';
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function POST(request: NextRequest) {
  const body = await request.json();
  const { priceId, customerExternalId } = body;

  // Get tracking ID from cookie OR from request body
  // Optional if customer already tracked via lead
  const trackingId =
    request.cookies.get('ta_tid')?.value ||
    body.trackingId ||
    '';

  const session = await stripe.checkout.sessions.create({
    mode: 'subscription',
    line_items: [{ price: priceId, quantity: 1 }],
    success_url: 'https://yoursite.com/success',
    cancel_url: 'https://yoursite.com/cancel',
    // Pass tracking ID and customer ID in metadata
    metadata: {
      taapitTrackingId: trackingId, // Optional if customer exists
      taapitCustomerExternalId: customerExternalId, // Required
    },
    // Also in subscription_data for subscriptions
    subscription_data: {
      metadata: {
        taapitTrackingId: trackingId,
        taapitCustomerExternalId: customerExternalId,
      },
    },
  });

  return Response.json({ url: session.url });
}

3. (Optional) Track Leads: Create a Stripe Customer

If you want to track leads separately from sales, create a Stripe customer with the tracking ID when a user signs up. Taapit listens to the customer.created webhook.

app/api/stripe/create-customer/route.ts

import { NextRequest } from 'next/server';
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function POST(request: NextRequest) {
  const body = await request.json();
  const { email, name, externalId } = body;

  // Get tracking ID from cookie OR from request body
  const trackingId =
    request.cookies.get('ta_tid')?.value ||
    body.trackingId ||
    '';

  // Create Stripe customer with Taapit metadata
  const customer = await stripe.customers.create({
    email,
    name,
    metadata: {
      taapitTrackingId: trackingId,
      taapitCustomerExternalId: externalId, // Your internal user ID
    },
  });

  return Response.json({ customerId: customer.id });
}

This step is optional. Use it if you want to track user signups as leads before they make a purchase.

4. (Alternative) Using Stripe Payment Links

If you’re using Stripe Payment Links, you can track sales automatically without writing any backend code.

With Payment Links, only sale events are tracked. Lead webhooks are not created.

How to set it up:

Get your Stripe Payment Link URL (e.g., https://buy.stripe.com/xxx)

Add ?taapit_client_reference_id=1 to the URL:

https://buy.stripe.com/xxx?taapit_client_reference_id=1

Shorten this URL with Taapit

How it works:When a user clicks on your Taapit deeplink, Taapit automatically:

Replaces taapit_client_reference_id=1 with client_reference_id=taapit_tid_{trackingId}
Stripe receives the tracking ID as client_reference_id
When checkout completes, Taapit attributes the sale to the original click

Verify the connection

Go to Settings → Integrations → Stripe in Taapit
You should see Connected status
Make a test payment
Check the Analytics tab for the conversion

Tracked Events

The Stripe integration automatically tracks these events:

Stripe Event	Taapit Event	Description
`customer.created`	Lead	Customer created with tracking metadata
`checkout.session.completed`	Sale	Checkout session completed
`invoice.paid`	Sale	Subscription invoice paid

Metadata Fields

The integration looks for these metadata fields on Stripe objects:

Field	Required	Description
`taapitTrackingId`	See below	The tracking ID (`ta_tid` from the cookie)
`taapitCustomerExternalId`	Yes	Your internal user ID

Use taapitTrackingId (not ta_tid) in Stripe metadata. The ta_tid is the cookie name, while taapitTrackingId is the metadata field name.

When is taapitTrackingId required? - Lead events (customer.created): taapitTrackingId is always required - Sale events (checkout.session.completed, invoice.paid): - If the customer was already tracked via a lead event (using taapitCustomerExternalId), the taapitTrackingId is optional - you only need the taapitCustomerExternalId - If this is a new customer (no prior lead), taapitTrackingId is required to attribute the sale

Troubleshooting

Conversions not appearing

Check metadata: Ensure taapitTrackingId is in your Stripe metadata
Verify webhook delivery: In Stripe → Developers → Webhooks 3. Check connection: Settings → Integrations → Stripe should show “Connected”

Tracking ID missing

If the tracking ID is empty, the user either: - Didn’t come from a Taapit link - Has cookies blocked - Cookie wasn’t passed to checkout This is normal for organic/direct traffic.

Security

Permission	Purpose
`customer_read`	Read customer information
`subscription_read`	Read subscription data
`invoice_read`	Read invoice amounts
`checkout_session_read`	Read checkout session metadata
`webhook_read`	Receive payment events

FAQ

Do I need to install the SDK?

Yes, you need the Taapit SDK on your website to capture the ta_tid cookie. The Stripe app only handles payment tracking.

How are subscription renewals handled?

Each invoice.paid event triggers a sale. The tracking ID from the original checkout is used for attribution.

What about refunds?

Currently, refunds are not automatically tracked. We’re working on this feature.

Getting started

Conversions

API Reference

How it works

Prerequisites

Installation

1. Frontend: Get the tracking ID

2. Track Sales: Create a Checkout Session

3. (Optional) Track Leads: Create a Stripe Customer

4. (Alternative) Using Stripe Payment Links

Tracked Events

Metadata Fields

Troubleshooting

Security

FAQ

Next Steps

Shopify Integration

Manual Integration

Getting started

Conversions

API Reference

​How it works

​Prerequisites

​Installation

​1. Frontend: Get the tracking ID

​2. Track Sales: Create a Checkout Session

​3. (Optional) Track Leads: Create a Stripe Customer

​4. (Alternative) Using Stripe Payment Links

​Tracked Events

​Metadata Fields

​Troubleshooting

​Security

​FAQ

​Next Steps

Shopify Integration

Manual Integration

How it works

Prerequisites

Installation

1. Frontend: Get the tracking ID

2. Track Sales: Create a Checkout Session

3. (Optional) Track Leads: Create a Stripe Customer

4. (Alternative) Using Stripe Payment Links

Tracked Events

Metadata Fields

Troubleshooting

Security

FAQ

Next Steps