OnRampOnRamp/Docs

Stripe integration

Sync paid invoices and subscription lifecycle events from Stripe into OnRamp to see revenue alongside your funnel data.

What gets synced

Stripe eventOnRamp event type
First paid invoice (subscription create)subscription_started
Renewal invoice paidsubscription_renewed
Subscription deleted / canceledsubscription_canceled
invoice.payment_succeeded webhooksubscription_started or subscription_renewed

Revenue amounts, currency, and Stripe price ID are stored with each event.

Connect

  1. Go to Settings → Integrations → Add integration → Stripe
  2. Paste your Stripe Secret key (sk_live_... or sk_test_... for testing)
  3. Choose an identity strategy (see below)
  4. Click Connect - OnRamp validates the key and starts the initial sync

OnRamp only needs read access. Create a Restricted key in the Stripe dashboard with read permissions on Customers and Invoices if you prefer not to use your full secret key.

Identity strategies

OnRamp must match a Stripe customer to an OnRamp anonymous_id. Choose the strategy that fits your app:

Option A - anonymous_id via metadata (most reliable)

When creating or updating a Stripe customer, set:

javascript
await stripe.customers.update(customerId, {
  metadata: { onramp_anonymous_id: onramp.anonymousId },
})

OnRamp checks this metadata field first. No event property configuration needed.

Option B - email match via identify()

Call OnRamp.identify() after the user signs in. OnRamp matches the email against the Stripe customer's email address.

javascript
// React / Next.js
const { identify } = useOnRamp()
identify({ email: user.email })

// React Native / Expo
OnRamp.identify({ email: user.email })

Select Identity strategy: email when connecting.

Option C - custom user ID via identify()

If your app uses its own user ID as the Stripe customer's metadata or description, pass it via identify():

javascript
identify({ userId: currentUser.id })

Select Identity strategy: property and set Identity property to userId.

Webhook (optional but recommended)

Configuring a Stripe webhook lets OnRamp capture cancellations and refunds in real time rather than waiting for the next 6-hour sync.

  1. In the Stripe dashboard, go to Developers → Webhooks → Add endpoint
  2. Set the URL to your OnRamp webhook endpoint (shown in Settings → Integrations after connecting)
  3. Select these events:
    • invoice.payment_succeeded
    • customer.subscription.deleted
  4. Copy the Signing secret and paste it into the integration settings in OnRamp

Initial sync

After connecting, OnRamp paginates through all paid invoices newest-first and stops at the last synced invoice on subsequent runs. Large Stripe accounts with many invoices may take a few minutes to fully backfill.

The sync cursor is stored per integration - reconnecting with a new key preserves your sync position.

Troubleshooting

"Credential validation failed" - check that the secret key is correct and not expired. Restricted keys need read access to Customers and Invoices.

No revenue appearing - verify the identity strategy matches how your app tracks users. Check the integration's last sync error in Settings → Integrations.

Duplicate events - OnRamp uses invoice IDs as deduplication keys in ClickHouse, so re-syncing the same invoices is safe.