Connect Stripe to AttribIQ

Stripe should send revenue events to AttribIQ after your checkout flow carries AttribIQ metadata into Stripe.

The integration has two valid paths:

Most teams should start with native Stripe webhooks. The relay path is an escape hatch, not a requirement.

Before you connect Stripe

Install the tracker and pass attribution into Checkout first.

Your backend should create Stripe Checkout and include these metadata fields:

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

Subscription metadata is important. Checkout metadata covers the initial checkout event, while subscription metadata keeps renewals and subscription lifecycle events connected to the original attribution identifiers.

Configure native Stripe webhooks

In Stripe, create a webhook endpoint for AttribIQ:

https://api.attribiq.com/v1/integrations/stripe/webhook

Use the API hostname for your AttribIQ deployment if you are not using the hosted service.

Start with this conservative event set:

• invoice.paid
• charge.refunded
• customer.subscription.deleted

This set captures paid invoices, refunds, and cancellations while avoiding ambiguous checkout setup sessions and broad subscription update events.

Add these events only after you confirm that their semantics match your billing model:

• checkout.session.completed
• customer.subscription.created
• customer.subscription.updated

checkout.session.completed is useful for one-time purchases and subscription starts, but setup-mode sessions should not become purchases. customer.subscription.updated can represent upgrades, downgrades, status changes, or metadata-only changes, so it needs careful handling before it should affect revenue reports.

Configure the signing secret

Stripe signs each webhook endpoint with its own signing secret. AttribIQ verifies Stripe signatures when the endpoint secret is configured for the receiver.

After creating the endpoint in Stripe:

1. Open the webhook endpoint in Stripe.
2. Reveal the endpoint signing secret.
3. Configure that secret in AttribIQ for the Stripe revenue webhook receiver.

If your AttribIQ workspace does not yet expose self-serve Stripe signing-secret settings, use one of these paths:

• Ask support or your deployment operator to configure the native Stripe webhook secret.
• Use the Payment API relay path from your own backend until project-level Stripe settings are available.

Do not reuse your AttribIQ billing webhook secret or a different Stripe endpoint secret. Stripe endpoint secrets are specific to each webhook endpoint.

Test in Stripe test mode

Use test mode before sending live events.

1. Visit your site with UTM parameters.
2. Start checkout from a tracked page.
3. Inspect the Stripe Checkout Session metadata.
4. For subscriptions, inspect the Stripe Subscription metadata.
5. Send or replay the selected test events from Stripe.
6. Confirm the AttribIQ revenue report shows revenue.
7. Confirm duplicate Stripe deliveries return as duplicates and do not double-count revenue.
8. Confirm missing visitor or session IDs appear as unattributed revenue instead of fabricated attribution.

If revenue is missing but Stripe metadata is present, check webhook delivery logs and signing-secret configuration first.

If the initial payment is attributed but renewals are not, subscription metadata is usually missing.

Use a Payment API relay instead

Use a relay if your backend should remain the payment-event source of truth.

The relay receives Stripe events, applies your billing rules, and posts normalized events to AttribIQ:

POST /v1/revenue
Authorization: Bearer sk_project_...
Idempotency-Key: in_123
Content-Type: application/json

{
  "provider": "stripe",
  "transaction_id": "in_123",
  "event_type": "renewal",
  "amount": 2900,
  "currency": "EUR",
  "occurred_at": "2026-06-25T10:30:00Z",
  "visitor_id": "v_abc",
  "session_id": "s_def",
  "metadata": {
    "stripe_invoice_id": "in_123",
    "plan": "builder"
  }
}

Use stable Stripe object IDs or durable billing-event IDs for transaction_id and Idempotency-Key. Do not generate a fresh random ID on retry.

Next steps

Read how to pass attribution to Stripe Checkout for the metadata bridge. Use the Payment API reference if your backend will send normalized revenue events instead of direct Stripe webhooks.