Stripe

Learn How to Track Sale Conversion Events with Stripe and Linkkit

Linkkit’s advanced Stripe integration monitors payment events from Stripe and automatically records them as sales within Linkkit. This allows you to accurately track revenue and attribute purchases to the correct referral links.

Stripe Integration Events

Linkkit’s Stripe integration listens for the following payment-related events:

• Recurring subscriptions
• One-time payments
• Free trials
• Refunds (used to reverse partner commissions)
• Cancellations and churn events
• Usage expansions

This guide will walk you through the process of installing and configuring the Linkkit Stripe Integration to track sale conversion events.

Installing the Linkkit Stripe Integration

1. Find Linkkit on the Stripe App Marketplace

Navigate to the Linkkit Stripe Integration page in the Stripe App Marketplace to begin the installation process.

2. Install the Stripe App

In the top-right corner of the Stripe App Marketplace page, click Install App to add the Linkkit Stripe App to your Stripe account.

Once installed, Linkkit will be able to connect with your Stripe account and automatically track relevant payment events for sale conversion tracking.

Once the app is installed, click on Continue to app settings to finish the installation.

3. Connect Stripe to Your Linkkit Workspace

On the app settings page, click Connect Workspace to link your Stripe account with your Linkkit workspace.

Once connected, Linkkit can receive Stripe payment events and automatically track them as sale conversion events within your workspace.

This will redirect you to the Linkkit OAuth authorization flow, where you can choose the Linkkit workspace that you want to connect to your Stripe account.

After authorization is complete, your selected workspace will be linked to Stripe, allowing Linkkit to automatically track and attribute payment events.

Once you click Authorize, you'll be redirected back to the Linkkit app settings page in Stripe, where you should see that the integration has been successfully installed and connected.

At this point, Linkkit will be ready to receive and process Stripe payment events for conversion and revenue tracking.

Stripe Events Tracked by Linkkit

Once the integration is installed, Linkkit will automatically listen for the following Stripe events and record them as sales-related events within your workspace:

• customer.created – Triggered when a new customer is created.
• customer.updated – Triggered when customer information is updated.
• checkout.session.completed – Triggered when a customer successfully completes a Stripe Checkout session.
• invoice.paid – Triggered when an invoice is paid, commonly used for tracking recurring subscriptions.
• charge.refunded – Triggered when a charge is refunded, allowing Linkkit to reverse or void associated partner commissions when applicable.

Tracking Sales with the Linkkit Stripe Integration

Depending on your implementation, there are several ways to track sales using the Linkkit Stripe integration:

Option 1: Using Stripe Payment Links

Track conversions generated through Stripe Payment Links, allowing Linkkit to attribute completed purchases to the appropriate referral source.

Option 2: Using Stripe Checkout (Recommended)

Track sales through Stripe Checkout, providing a seamless and reliable way to attribute purchases and recurring payments within Linkkit.

Option 3: Using Stripe Customers

Track sales by associating Stripe customer records with Linkkit customer identities, enabling conversion attribution across multiple purchases and subscription events.

Once the integration is installed, Linkkit will automatically listen for the following Stripe events and record them as sales-related events within your workspace:

• customer.created – Triggered when a new customer is created.
• customer.updated – Triggered when customer information is updated.
• checkout.session.completed – Triggered when a customer successfully completes a Stripe Checkout session.
• invoice.paid – Triggered when an invoice is paid, commonly used for tracking recurring subscriptions.
• charge.refunded – Triggered when a charge is refunded, allowing Linkkit to reverse or void associated partner commissions when applicable.

Tracking Sales with the Linkkit Stripe Integration

Depending on your implementation, there are several ways to track sales using the Linkkit Stripe integration:

Option 1: Using Stripe Payment Links

Track conversions generated through Stripe Payment Links, allowing Linkkit to attribute completed purchases to the appropriate referral source.

Option 2: Using Stripe Checkout (Recommended)

Track sales through Stripe Checkout, providing a seamless and reliable way to attribute purchases and recurring payments within Linkkit.

Option 3: Using Stripe Customers

Track sales by associating Stripe customer records with Linkkit customer identities, enabling conversion attribution across multiple purchases and subscription events.

Option 1: Using Stripe Payment Links

If you're using Stripe Payment Links, Linkkit can automatically attribute completed purchases when customers reach Stripe through a tracked Linkkit link and complete their payment.

If you're using Stripe Payment Links, simply add the ?linkkit_client_reference_id=1 query parameter to your Stripe Payment Link before shortening it with Linkkit.

When a user clicks the shortened Linkkit URL, Linkkit will automatically replace this value and append the unique click identifier as the client_reference_id query parameter on the Stripe Payment Link.

This allows Linkkit to associate completed payments with the original referral click, enabling accurate conversion attribution and revenue tracking.

Finally, when the user completes the checkout process, Linkkit will automatically record the sale event and associate the customer's customerExternalId with their Stripe Customer ID for future attribution and tracking.

Alternatively, if users first land on your marketing website before being redirected to Stripe, you can use the following approach:

• Install the Linkkit Analytics script on your website. The script automatically detects the linkkit_id parameter in the URL and stores it as a first-party cookie.
• Retrieve the linkkit_id value from the cookie and append it to your Stripe Payment Links as the client_reference_id parameter, prefixed with linkkit_id_.

This ensures that Linkkit can correctly attribute completed purchases back to the original referral click, even when users pass through your website before reaching Stripe Checkout.

Option 2: Using Stripe Checkout (Recommended)

If you have a custom checkout flow that uses Stripe’s checkout.sessions.create API, you should associate the Stripe customer object with the user's unique identifier in your database (the same identifier captured during the lead conversion tracking step).

Doing so allows Linkkit to automatically listen for purchase events from Stripe and associate them with the original referral click, and ultimately with the Linkkit link that brought the user to your site.

This approach provides reliable conversion attribution by connecting customer records, lead events, and purchase events throughout the entire user journey.

Before getting started, make sure you have completed the following setup steps:

• Install the Linkkit Stripe Integration
• Install the Linkkit Analytics script
• Install the Linkkit Server-Side SDK

Once these prerequisites are in place, you can create your Stripe Checkout session.

import { stripe } from "@/lib/stripe";

const user = {
  id: "user_123",
  email: "user@example.com",
  teamId: "team_xxxxxxxxx",
};

const priceId = "price_xxxxxxxxx";

const stripeSession = await stripe.checkout.sessions.create({
  customer_email: user.email,
  success_url: "https://app.domain.com/success",
  line_items: [{ price: priceId, quantity: 1 }],
  mode: "subscription",
  client_reference_id: user.teamId,
  metadata: {
    linkkitCustomerExternalId: user.id, // the unique user ID of the customer in your database
  },
});

When creating the checkout session, pass your customer's unique user ID from your database as the linkkitCustomerExternalIdvalue within the metadata field.

This allows Linkkit to associate Stripe purchase events with the correct customer record and accurately attribute sales to the original referral link.

This ensures that when the customer completes their checkout session, Linkkit can automatically associate the checkout details—such as the invoice amount, currency, subscription information, and other purchase data—with the correct customer record.

Because that customer is already linked to the original referral click, Linkkit can accurately attribute the sale back to the original click event and the Linkkit link that drove the conversion.

Option 3: Using Stripe Customers

If you're not using Stripe's Checkout Session creation flow, you can still track conversions by passing both the user's unique ID and the click ID (linkkit_id) during the Stripe customer creation process.

Prerequisites

Before implementing this approach, make sure you have completed the following:

• Install the Linkkit Stripe Integration
• Enable conversion tracking for your Linkkit links
• Install the Linkkit Analytics script

Configure the Stripe Customer

When creating a Stripe customer, include the user's unique identifier from your database as the linkkitCustomerExternalId value within the customer metadata field.

import { stripe } from "@/lib/stripe";

const user = {
  id: "user_123",
  email: "user@example.com",
  teamId: "team_xxxxxxxxx",
};

const linkkit_id = req.headers.get("linkkit_id");

await stripe.customers.create({
  email: user.email,
  name: user.name,
  metadata: {
    linkkitCustomerExternalId: user.id,
    linkkitClickId: linkkit_id,
  },
});

This allows Linkkit to associate the Stripe customer with the corresponding user in your system, enabling accurate attribution of future purchases and subscription events to the original referral link.

Alternatively, you can provide the linkkitCustomerExternalId and linkkitClickId values in the metadata field when updating an existing Stripe customer.

import { stripe } from "@/lib/stripe";

const user = {
  id: "user_123",
  email: "user@example.com",
  teamId: "team_xxxxxxxxx",
};

const linkkit_id = req.headers.get("linkkit_id");

await stripe.customers.update(user.id, {
  metadata: {
    linkkitCustomerExternalId: user.id,
    linkkitClickId: linkkit_id,
  },
});

This way, when the customer completes a purchase, Linkkit can automatically associate the transaction details—such as the invoice amount, currency, subscription information, and other payment data—with the original referral click.

As a result, the purchase is accurately attributed to the corresponding Linkkit link, providing complete visibility into the customer journey and revenue generated from your referral traffic.

Tracking Free Trials

Linkkit supports tracking subscription free-trial activations as lead events. This is especially useful for products that offer free trials, as it allows you to include trial signups in your attribution and conversion tracking workflow.

To enable free-trial tracking, navigate to your Stripe Integration Settings and turn on the Track Free Trials option.

Once enabled, Linkkit will automatically record eligible free-trial activations as lead events, helping you measure trial conversions and understand which links, campaigns, or partners are driving trial signups.

Optionally, you can configure the integration to track the provisioned quantity of a subscription as separate lead events.

This is particularly useful for partner or affiliate programs that offer lead-based rewards, allowing you to reward partners based on the number of units, seats, or licenses purchased by their referred customers.

For example, if your partner program pays $50 per qualified lead or provisioned seat, Linkkit can track each provisioned unit as an individual lead event, enabling more accurate attribution and commission calculations.

Tax Handling

When tracking sale conversions from Stripe, Linkkit automatically excludes taxes from the final sale amount to ensure accurate revenue attribution and reporting.

For Checkout Sessions, Linkkit calculates the sale amount by subtracting the tax amount from the total transaction value:

// Sale amount calculation for checkout sessions
saleAmount = amount_total - total_details.amount_tax;

For Invoices, Linkkit uses the total_excluding_tax value when available:

// Sale amount calculation for invoices
saleAmount = total_excluding_tax ?? amount_paid;

By excluding taxes from recorded sales, Linkkit ensures that conversion data reflects the actual revenue generated before tax charges.

This provides more accurate data for:

• Revenue tracking and reporting
• Partner and affiliate commission calculations
• Conversion analytics and performance metrics
• Attribution reporting and ROI measurement

Currency Conversion Support

If you're using Stripe's Adaptive Pricing feature, Linkkit will record the sale amount using your Stripe account's default currency.

// Stripe checkout.session.completed event payload
{
  "id": "{{EVENT_ID}}",
  "object": "event",
  "type": "checkout.session.completed",
  "data": {
    "object": {
      "id": "{{SESSION_ID}}",
      "object": "checkout.session",
      "currency": "cad",
      "amount_subtotal": 2055,
      "amount_total": 2055,
      "currency_conversion": {
        "amount_subtotal": 1500,
        "amount_total": 1500, // this is the amount that Linkkit will record
        "source_currency": "usd", // the currency of your Stripe account
        "fx_rate": "1.37"
      }
    }
  }
}

If you're not using Stripe Adaptive Pricing, Linkkit will record sale amounts using the default currency configured for your Linkkit workspace.

If a sale is received in a different currency, Linkkit will automatically convert the amount to your workspace's reporting currency (for example, USD) using the latest available foreign exchange rates.

This ensures consistent reporting across all transactions and provides accurate data for:

• Revenue tracking and reporting
• Conversion analytics
• Partner and affiliate commission calculations
• Performance and attribution metrics

By automatically normalizing currencies, Linkkit makes it easier to analyze revenue and conversion performance across multiple regions and currencies.

// Stripe checkout.session.completed event payload
{
  "id": "{{EVENT_ID}}",
  "object": "event",
  "type": "checkout.session.completed",
  "data": {
    "object": {
      "id": "{{SESSION_ID}}",
      "object": "checkout.session",
      "currency": "cad",
      "amount_subtotal": 2055,
      "amount_total": 2055 // this will be converted from CAD to USD
    }
  }
}

Multiple Line Items Per Invoice

When a Stripe invoice or checkout session contains multiple line items—such as a base subscription with add-ons or multiple products purchased in a single transaction—Linkkit processes each line item separately to ensure commissions are calculated accurately.

For each line item, Linkkit:

• Identifies the associated Stripe product ID.
• Checks for any product-specific reward modifiers configured for the partner’s group.
• Calculates the commission for that line item using the applicable reward rate.
• Falls back to the default reward rate if no product-specific modifier is found.

The total commission recorded for the invoice is then calculated by summing the commissions from all individual line items.

This approach ensures accurate commission tracking and attribution, even for invoices containing multiple products, plans, or add-on purchases.

The total saleAmount recorded in Linkkit will still represent the complete invoice value after tax exclusions and any applicable currency conversions. This ensures that your revenue reporting and analytics remain accurate and consistent.

View Conversion Results

That's it — your setup is complete. Once conversion tracking is active, all conversion data will be available within your analytics dashboard.

Linkkit provides three different views to help you analyze conversion performance:

Time-Series View

A time-series visualization showing the number of clicks, leads, and sales over time.

This view helps you monitor trends, measure campaign performance, and understand how conversions evolve across different time periods.

Funnel View

A funnel chart that visualizes the conversion rates and drop-off rates at each stage of the conversion journey, from Clicks → Leads → Sales.

This view helps you understand how users progress through the funnel, identify where potential customers drop off, and uncover opportunities to improve conversion performance and overall revenue generation.

Real-Time Events Stream

A real-time activity stream that displays every conversion event as it happens across all tracked links in your workspace.

This view provides instant visibility into user activity, allowing you to monitor:

• New clicks
• Lead conversions
• Sales and purchases
• Trial activations
• Subscription events
• Other tracked conversion activities

The real-time events stream helps you track performance as it happens and quickly verify that your attribution and conversion tracking setup is working correctly.

Example Apps