Stripe revenue attribution for SaaS

Stripe revenue attribution connects Stripe's payment lifecycle to the visits and campaigns that happened before the customer paid.

Stripe is the source for the money event. AttribIQ is the source for the browser and campaign context. The integration works when your app carries AttribIQ identifiers into Stripe metadata before checkout starts.

Stripe documents Checkout Sessions, metadata, and subscription webhooks in its official docs: Checkout Sessions, metadata, and subscription webhooks.

The objects that matter

For a subscription SaaS product, these Stripe objects usually matter:

• Checkout Session for the initial checkout attempt.
• Customer for the paying account in Stripe.
• Subscription for recurring billing state.
• Invoice for renewals and failed payments.
• Charge or PaymentIntent for payment settlement and refunds.

The key mistake is only thinking about the first payment. If you want revenue by campaign, you also need to decide how renewals, upgrades, downgrades, refunds, cancellations, and churn should inherit or change attribution.

The metadata bridge

The browser tracker knows the AttribIQ project, visitor, and session. Before checkout, your frontend sends that attribution object to your backend.

const attribution = window.attribiq.getAttribution()

await fetch("/api/create-checkout-session", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ price_id: "price_123", attribution })
})

The backend copies that context into Stripe:

const session = await stripe.checkout.sessions.create({
  mode: "subscription",
  line_items: [{ price: priceId, quantity: 1 }],
  success_url: "https://example.com/billing/success?session_id={CHECKOUT_SESSION_ID}",
  cancel_url: "https://example.com/pricing",
  client_reference_id: attribution.visitor_id,
  metadata: {
    attribiq_project_id: attribution.project_id,
    attribiq_visitor_id: attribution.visitor_id,
    attribiq_session_id: attribution.session_id
  },
  subscription_data: {
    metadata: {
      attribiq_project_id: attribution.project_id,
      attribiq_visitor_id: attribution.visitor_id,
      attribiq_session_id: attribution.session_id
    }
  }
})

Copying metadata to both places matters. The Checkout Session helps with the first conversion. Subscription metadata helps with future invoice and subscription events.

Choose the ingestion path

There are two Stripe ingestion paths.

For most teams, Stripe should send selected webhook events directly to AttribIQ's native receiver. AttribIQ verifies the Stripe signature when the endpoint secret is configured, ignores duplicate Stripe event IDs, extracts the AttribIQ metadata, writes the revenue event, and runs attribution.

Use a customer-owned relay only when your backend needs to normalize custom billing semantics before AttribIQ receives the event. In that path, your webhook handler should:

1. Verify the Stripe webhook signature.
2. Store the Stripe event ID and reject duplicate deliveries.
3. Extract AttribIQ metadata from the event object.
4. Normalize the event into purchase, subscription_started, renewal, upgrade, downgrade, refund, cancellation, or churn.
5. Use Stripe object IDs for idempotency.
6. Send the normalized revenue event to POST /v1/revenue.

Do not rely on redirect success pages as the source of truth. They are useful for UI, but webhooks are the reliable payment lifecycle feed.

Attribution rules for renewals

Most SaaS teams attribute renewals back to the original acquisition source unless they have a reason to model expansion separately. That makes reports like "MRR by campaign" stable and understandable.

Refunds should subtract from the attributed source that received the original credit. Churn should be visible by source too. A campaign that creates many initial purchases but high refunds may be worse than a quieter channel with stronger retention.

Next steps

Start with passing attribution into Stripe Checkout, then connect Stripe to AttribIQ. If you do not use Stripe or need a custom relay, use the generic Payment API guide.