How to track sale conversions with Stripe and CodeQR

Conversion tracking require a Business plan subscription or higher.

When it comes to conversion tracking, a sale event happens when a user purchases your product or service. Examples include:

Subscribing to a paid plan
Usage expansion (upgrading from one plan to another)
Purchasing a product via Stripe Payment Links

A diagram showing how lead events are tracked in the conversion funnel

In this guide, we will be focusing on tracking sale events with Stripe as the payment processor by leveraging CodeQR’s Stripe integration.

Installing the CodeQR Stripe integration

CodeQR comes with a powerful Stripe integration that automatically listens to payment events on Stripe and track them as sales on CodeQR. Here’s how you can install the CodeQR Stripe integration:

Find CodeQR on the Stripe App Marketplace

Navigate to the CodeQR Stripe Integration on the Stripe App Marketplace.

The CodeQR: Conversions Analytics page on the Stripe App Marketplace

Install the Stripe app

On the top right, click on Install app to install the CodeQR Conversions app on your Stripe account.

The Stripe integration installation flow

Alternatively, you can also install the Stripe app in test mode first to test your end-to-end flow without involving real money.

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

Connect Stripe to your CodeQR workspace

In the app settings page, click on Connect workspace to connect your Stripe account with your CodeQR workspace.

This will redirect you to the CodeQR OAuth flow, where you can select the CodeQR workspace you want to connect to your Stripe account.

Once you click on Authorize, you will be redirected back to the CodeQR app settings page on Stripe, where you should see that the integration is now installed.

Once the integration is installed, CodeQR will automatically listen to the following events on Stripe and track them as sales on CodeQR:

customer.created: When a new customer is created
customer.updated: When a customer is updated
checkout.session.completed: When a customer completes a checkout session
invoice.paid: When an invoice is paid (for tracking recurring subscriptions)
charge.refunded: When a charge is refunded (for tracking refunds and updating payout commissions for CodeQR Partners)

Tracking sales with the CodeQR Stripe integration

Depending on your setup, there are a few ways you can track sales with the CodeQR Stripe integration.

Option 1: Using Stripe Payment Links
Option 2: Using Stripe Checkout (recommended)
Option 3: Using Stripe Customers

Option 1: Using Stripe Payment Links

For this option to work, you need to install the CodeQR Stripe integration and enable conversion tracking for your links first.

If you’re using Stripe Payment Links, simply add a ?codeqr_client_reference_id=1 query parameter to your Stripe Payment Link when shortening it on CodeQR. Then, when a user clicks on the shortened link, CodeQR will automatically append the unique click ID as the client_reference_id query parameter to the payment link.

Stripe payment link with CodeQR click ID

Finally, when the user completes the checkout flow, CodeQR will automatically track the sale event and update the customer’s externalId with their Stripe customer ID for future reference. Alternatively, if you have a marketing site that you’re redirecting your users to first, you can do this instead:

Install the @codeqr/analytics client-side SDK, which automatically detects the cq_id in the URL and stores it as a first-party cookie on your site.
Then, retrieve and append the cq_id value as the client_reference_id parameter to the payment links on your pricing page / CTA button (prefixed with codeqr_id_).
```
https://buy.stripe.com/xxxxxx?client_reference_id=codeqr_id_xxxxxxxxxxxxxx
```

What if I'm using Stripe Pricing Tables?

If you’re using Stripe Pricing Tables – you’d want to pass the CodeQR click ID as a client-reference-id attribute instead:

<body>
  <h1>We offer plans that help any business!</h1>
  <!-- Paste your embed code script here. -->
  <script async src="https://js.stripe.com/v3/pricing-table.js"></script>
  <stripe-pricing-table
    pricing-table-id="{{PRICING_TABLE_ID}}"
    publishable-key="pk_test_51ODHJvFacAXKeDpJsgWLQJSzBIDtCUFN6MoB4IIXKJDfWdFmiEO4JuvAU1A0Y2Ri4m4q1egIfwYy3s72cUBRCwXC00GQhEZuXa"
    client-reference-id="codeqr_id_xxxxxxxxxxxxxx"
  >
  </stripe-pricing-table>
</body>

What if I'm using Stripe's Checkout Sessions API?

If you’re using Stripe’s Checkout Sessions API for a recurring subscription service, you might want to check out our Stripe Checkout option instead.If your setup doesn’t involve a lead event and goes straight to the Stripe checkout flow (e.g. for one-time purchases), you can simply pass the CodeQR click ID (prefixed with codeqr_id_) as the client_reference_id parameter to enable conversion tracking with CodeQR.

const session = await stripe.checkout.sessions.create({
  success_url: "https://example.com/success",
  line_items: [
    {
      price: "price_xxxxxxxxxxxxxxxx",
      quantity: 2,
    },
  ],
  mode: "payment",
  client_reference_id: "codeqr_id_xxxxxxxxxxxxxx",
});

Option 2: Using Stripe Checkout (recommended)

If you have a custom checkout flow that uses Stripe’s checkout.sessions.create API, you’d want to associate the Stripe customer object with the user’s unique ID in your database (which we tracked in the lead conversion tracking step). This will allow CodeQR to automatically listen for purchase events from Stripe and associate them with the original click event (and by extension, the link that the user came from).

How does this work?

Remember in the lead conversion tracking guide, we passed the user’s unique user ID along with the click event ID in the codeqr.track.lead call?

Node.js

await codeqr.track.lead({
  clickId,
  eventName: "Sign Up",
  externalId: user.id, // the unique user ID of the customer in your database
  customerName: user.name,
  customerEmail: user.email,
  customerAvatar: user.image,
});

Under the hood, CodeQR records the user as a customer and associates them with the click event that they came from.Then, when the user makes a purchase, CodeQR will automatically associate the checkout session details (invoice amount, currency, etc.) with the customer – and by extension, the original click event.

First, you’ll need to complete the following prerequisites:

Then, when you create a checkout session, pass your customer’s unique user ID in your database as the codeqrCustomerId value in the metadata field.

Node.js

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: {
    codeqrCustomerId: user.id, // the unique user ID of the customer in your database
  },
});

This way, when the customer completes their checkout session, CodeQR will automatically associate the checkout session details (invoice amount, currency, etc.) with the customer – and by extension, the original click event.

Option 3: Using Stripe Customers

Alternatively, if you don’t use Stripe’s checkout session creation flow, you can also pass the user ID and the click event ID (cq_id) in the Stripe customer creation flow. First, you’ll need to complete the following prerequisites:

Then, when you create a Stripe customer, pass the user’s unique user ID in your database as the codeqrCustomerId value in the metadata field.

Node.js

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

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

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

await stripe.customers.create({
  email: user.email,
  name: user.name,
  metadata: {
    codeqrCustomerId: user.id,
    codeqrClickId: cq_id,
  },
});

Alternatively, you can also pass the codeqrCustomerId and codeqrClickId values in the metadata field of the Stripe customer update flow:

Node.js

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

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

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

await stripe.customers.update(user.id, {
  metadata: {
    codeqrCustomerId: user.id,
    codeqrClickId: cq_id,
  },
});

This way, when the customer makes a purchase, CodeQR will automatically associate the purchase details (invoice amount, currency, etc.) with the original click event.

Currency conversion support

If you’re using Stripe’s Adaptive Pricing feature, CodeQR will record the sale amount using the currency of your Stripe account:

checkout.session.completed

// 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 CodeQR will record
        "source_currency": "usd", // the currency of your Stripe account
        "fx_rate": "1.37"
      }
    }
  }
}

If you’re not using Stripe Adaptive Pricing, CodeQR will record the sale amount in the default currency of your CodeQR workspace. This means that if you pass a different currency, it will be automatically converted to USD for reporting consistency – using the latest foreign exchange rates.

checkout.session.completed

// 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
    }
  }
}

The default currency for all CodeQR workspaces is currently set to USD. We will add the ability to customize that in the future.

View conversion results

And that’s it – you’re all set! You can now sit back, relax, and watch your conversion revenue grow. We provide 3 different views to help you understand your conversions:

Time-series: A time-series view of the number clicks, leads and sales.

Funnel chart: A funnel chart view visualizing the conversion & dropoff rates across the different steps in the conversion funnel (clicks → leads → sales).

Funnel chart view showing the conversion & dropoff rates from clicks → leads → sales

Real-time events stream: A real-time events stream of every single conversion event that occurs across all your links in your workspace.

Example Apps

CodeQR + Stripe Demo App

See the full example on GitHub.

Getting Started

Links

QR Codes

Integrations

Stripe

Installing the CodeQR Stripe integration

Tracking sales with the CodeQR Stripe integration

Option 1: Using Stripe Payment Links

Option 2: Using Stripe Checkout (recommended)

Option 3: Using Stripe Customers

Currency conversion support

View conversion results

Example Apps

CodeQR + Stripe Demo App

Getting Started

Links

QR Codes

Integrations

​Installing the CodeQR Stripe integration

​Tracking sales with the CodeQR Stripe integration

​Option 1: Using Stripe Payment Links

​Option 2: Using Stripe Checkout (recommended)

​Option 3: Using Stripe Customers

​Currency conversion support

​View conversion results

​Example Apps

CodeQR + Stripe Demo App

Installing the CodeQR Stripe integration

Tracking sales with the CodeQR Stripe integration

Option 1: Using Stripe Payment Links

Option 2: Using Stripe Checkout (recommended)

Option 3: Using Stripe Customers

Currency conversion support

View conversion results

Example Apps