Stripe Billing

Connect your Stripe account to allow purchase events to integrate directly to Invitebase. These purchase events can then be used to verify referrals as qualification gates — no purchase instrumentation in your codebase.

Connect Stripe

Identity: linking Stripe customers to referred users

Stripe does not know your app's user IDs unless you tell it. Invitebase resolves a Stripe customer to a referred user in this order:

1. client_reference_id on the Checkout Session — set it to your user ID when creating the session:

const session = await stripe.checkout.sessions.create({
  mode: 'subscription',
  line_items: [{ price: 'price_pro_monthly', quantity: 1 }],
  client_reference_id: user.id, // ← your ID, same value you pass to identify()
  success_url: 'https://example.com/welcome',
  cancel_url: 'https://example.com/pricing',
});

2. metadata.invitebase_user_id on the Customer — for flows that do not go through Checkout:

await stripe.customers.update(customerId, {
  metadata: { invitebase_user_id: user.id },
});

3. Email fallback — if neither is present, Invitebase matches the customer's email against identified users. Exact-match only; treat it as a safety net, not the plan.

Whichever you use, the value must equal the ID you pass to identify(). Events for customers Invitebase cannot resolve yet are parked and retried once the user is identified or the metadata appears.

Event mapping

Mapped events carry price_id, product_id, amount, currency, and plan properties you can restrict gate conditions by, and show up in Developer tools → Events with the raw Stripe payload attached (source: stripe on the API). The canonical names match the RevenueCat and Adapty adapters, so one campaign can span your web and mobile funnels.

Use it in a gate

To validate on a paid web subscription, add one required condition on subscription_started in the gate builder, restricted to plan: paid, with a 14-day window.

Restrict the condition to a specific price with price_id: price_pro_annual, or add a second condition on the first renewal (subscription_renewed) to reward only retained customers. Refunds feed fraud controls — a refund inside the hold window claws the reward back before payout.

Test with Stripe test mode

1. Set up a linked test referral (see the walkthrough).
2. Run a test-mode Checkout with client_reference_id set to the referred test user and card 4242 4242 4242 4242.
3. Stripe fires checkout.session.completed and customer.subscription.created to your test connection; the gate evaluates and the referral flips to validated.
4. For renewal and trial-conversion gates, use Stripe test clocks to advance time instead of waiting a billing cycle.

What's next