Payment

Learn how to track payments, subscriptions, and revenue in Vision Analytics using automated payment webhooks, or with client-side checkout event tracking as a fallback.

Vision allows you to track revenue, customer spending, and subscription lifecycle events automatically from your payment providers or manually via client-side tracking.


Automated Payment Provider Tracking

Vision can automatically track payments and subscription lifecycle events from your payment provider via webhooks — no manual tracking code required on checkout completion. When a customer completes checkout, Vision receives the event from the provider, attributes it to the original visitor, and records it to your project's revenue metrics.

Supported Providers

  • Stripe
  • Paddle
  • Polar
  • LemonSqueezy

How Attribution Works

When a customer begins checkout, pass attribution metadata to the checkout session. Vision reads this metadata back from the incoming webhook to match the payment to the correct visitor session.

Metadata KeyDescriptionRequired
projectIdYour Vision project ID✅ Yes
visitorIdThe Vision visitor ID (from window.vision?.visitorId)Recommended
deviceIdA fallback device ID if visitor ID is unavailableOptional

Understanding visitorId vs deviceId

  • window.vision?.visitorId: Derived automatically by the Vision backend using a privacy-preserving cryptographic hash (or an identified user ID) and populated onto window.vision after the first pageview or event. It is a string (or null before the first event completes).
  • window.vision?.deviceId: Initialized to null on the tracker (or a string if configured via data-device-id). It serves as an optional fallback identifier for external environments (such as native mobile apps, desktop apps, or custom client environments) where visitorId is not present. It is always string | null and never undefined.

Reading Identifiers on the Client

Before initiating checkout, read the identifiers from window.vision and forward them to your backend:

// Client-side: Read identifiers from the Vision tracker
const visionVisitorId = window.vision?.visitorId; // string | null
const visionDeviceId = window.vision?.deviceId;   // string | null

// Forward to your backend endpoint that creates the checkout session
const response = await fetch('/api/create-checkout', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    visitorId: visionVisitorId,
    deviceId: visionDeviceId,
  }),
});

1. Stripe

Passing Metadata at Checkout

Pass the attribution keys in the metadata field of your Checkout Session or Payment Intent:

// Node.js server-side example
const session = await stripe.checkout.sessions.create({
  line_items: [{ price: 'price_xxx', quantity: 1 }],
  mode: 'payment',
  success_url: 'https://yourapp.com/success',
  cancel_url: 'https://yourapp.com/cancel',
  metadata: {
    projectId: 'your-vision-project-id',   // required
    visitorId: visionVisitorId,             // from window.vision?.visitorId
    deviceId: visionDeviceId,               // optional fallback (string or null)
  },
});

Tracked Stripe Events

Stripe EventVision Event Type
payment_intent.succeededpayment.succeeded
payment_intent.payment_failedpayment.failed
checkout.session.completedpayment.succeeded
charge.refundedpayment.refunded
customer.subscription.createdsubscription.created
customer.subscription.updatedsubscription.updated
customer.subscription.deletedsubscription.cancelled
invoice.paidpayment.succeeded
invoice.payment_failedpayment.failed

Variables Captured per Event

FieldSource in Stripe Payload
amountdata.object.amount / amount_total / amount_paid (in cents)
currencydata.object.currency (ISO 4217, lowercased)
statusdata.object.status
eventTypeMapped from Stripe event type
projectIddata.object.metadata.projectId
visitorIddata.object.metadata.visitorId
deviceIddata.object.metadata.deviceId

2. Paddle

Passing Metadata at Checkout

Pass attribution data using Paddle's custom_data field:

// Node.js (Paddle Billing)
const transaction = await paddle.transactions.create({
  items: [{ price_id: 'pri_xxx', quantity: 1 }],
  custom_data: {
    projectId: 'your-vision-project-id',  // required
    visitorId: visionVisitorId,            // recommended
    deviceId: visionDeviceId,              // optional fallback
  },
});

Or with Paddle.js inline checkout:

Paddle.Checkout.open({
  items: [{ priceId: 'pri_xxx', quantity: 1 }],
  customData: {
    projectId: 'your-vision-project-id',
    visitorId: visionVisitorId,
    deviceId: visionDeviceId,
  },
});

Tracked Paddle Events

Paddle EventVision Event Type
transaction.completedpayment.succeeded
transaction.payment_failedpayment.failed
transaction.refundedpayment.refunded
subscription.createdsubscription.created
subscription.updatedsubscription.updated
subscription.cancelledsubscription.cancelled
subscription.pausedsubscription.updated

Variables Captured per Event

FieldSource in Paddle Payload
amountdata.details.totals.grand_total (smallest unit)
currencydata.currency_code (lowercased)
statusdata.status
projectIddata.custom_data.projectId
visitorIddata.custom_data.visitorId
deviceIddata.custom_data.deviceId

3. Polar

Passing Metadata at Checkout

// Node.js
const checkout = await polar.checkouts.create({
  productPriceId: 'price_xxx',
  metadata: {
    projectId: 'your-vision-project-id',
    visitorId: visionVisitorId,
    deviceId: visionDeviceId,
  },
});

Tracked Polar Events

Polar EventVision Event Type
order.createdpayment.succeeded
subscription.createdsubscription.created
subscription.updatedsubscription.updated
subscription.cancelledsubscription.cancelled
subscription.revokedsubscription.cancelled

Variables Captured per Event

FieldSource in Polar Payload
amountdata.amount (in cents)
currencydata.currency (lowercased)
statusdata.status
projectIddata.metadata.projectId
visitorIddata.metadata.visitorId
deviceIddata.metadata.deviceId

4. LemonSqueezy

Passing Metadata at Checkout

// Node.js
const checkout = await lemonsqueezy.createCheckout({
  storeId: 'your-store-id',
  variantId: 'variant-id',
  checkoutData: {
    custom: {
      projectId: 'your-vision-project-id',  // required
      visitorId: visionVisitorId,            // recommended
      deviceId: visionDeviceId,              // optional fallback
    },
  },
});

Tracked LemonSqueezy Events

LemonSqueezy EventVision Event Type
order_createdpayment.succeeded
subscription_createdsubscription.created
subscription_updatedsubscription.updated
subscription_cancelledsubscription.cancelled
subscription_expiredsubscription.cancelled
subscription_payment_successpayment.succeeded
subscription_payment_failedpayment.failed
subscription_payment_refundedpayment.refunded

Variables Captured per Event

FieldSource in LemonSqueezy Payload
amountdata.attributes.total or subtotal
currencydata.attributes.currency (lowercased)
statusdata.attributes.status
projectIddata.attributes.meta.custom_data.projectId
visitorIddata.attributes.meta.custom_data.visitorId
deviceIddata.attributes.meta.custom_data.deviceId

Fallback: Client-Side Revenue Tracking

If you do not use one of the supported payment gateways above, or wish to track one-off in-app purchases, digital carts, or custom checkout flows directly in the browser, you can use client-side event tracking as a fallback.

HTML Data Attributes Fallback

You can track revenue directly from any clickable HTML element using data attributes:

<button
  id="checkout-button"
  data-vision-event="checkout-cart"
  data-vision-event-revenue="19.99"
  data-vision-event-currency="USD"
>
  Checkout
</button>

The data-vision-event-{key} pattern maps any attribute key directly into the event data object:

AttributeMaps toDescription
data-vision-eventEvent NameName of the checkout event (e.g. checkout-cart)
data-vision-event-revenuedata.revenueAmount as a numeric string (e.g. "19.99")
data-vision-event-currencydata.currencyISO 4217 3-letter currency code (defaults to USD if omitted)
data-vision-event-plandata.planOptional custom property (e.g. "pro")

JavaScript Tracker Function Fallback

You can also trigger revenue tracking programmatically using vision.track:

// Standard syntax
vision.track("checkout-cart", { revenue: 19.99, currency: "USD" });

Or using the functional form to include existing page properties:

vision.track((props) => ({
  ...props,
  name: "checkout-cart",
  data: {
    revenue: 19.99,
    currency: "USD",
  },
}));

Viewing Revenue in Vision

The Revenue insight aggregates all tracked payment and revenue events across your specified time period.

  1. Navigate to your project in the Vision dashboard.
  2. Open the Revenue tab.
  3. Select your desired currency filter to inspect total revenue, average order value, and conversion sources.