> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibefollow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Import existing users from Stripe

> Backfill your customers, trials, and billing history into Vibefollow with a read-only Stripe key — no code required.

If your billing already runs on Stripe, you don't have to backfill historical users and subscription events through the SDK. Connect Stripe in the dashboard and Vibefollow does a one-time import of your customers and their billing history as canonical lifecycle events.

<Note>
  This is a **dashboard integration**, not an SDK call. There is no `/v1/stripe` endpoint. Use it for the initial backfill, then keep the [SDK](/sdk/overview) for ongoing product-usage events Stripe can't see.
</Note>

## What gets imported

Vibefollow reads your Stripe Customers, Subscriptions, and Invoices and maps them to canonical [lifecycle events](/events/lifecycle-events):

| Stripe object                  | Becomes                                                          |
| ------------------------------ | ---------------------------------------------------------------- |
| Customer                       | A user (`identify`) + a `user_signed_up` event                   |
| Subscription in trial          | `trial_started` (with `trialDays` derived from the trial window) |
| Active / past subscription     | `subscription_changed` (with `interval` and `mrr`)               |
| Cancelled subscription         | `subscription_cancelled`                                         |
| Failed / uncollectible invoice | `payment_failed`                                                 |

<Info>
  Welcome emails are **suppressed** for imported users, so long-standing customers don't get a "welcome" email months after they actually signed up. Product-usage events (`feature_used`, `onboarding_step`, `usage_threshold_reached`) aren't in Stripe — keep sending those with the SDK.
</Info>

## Create a restricted key

Vibefollow only ever needs **read** access, and never accepts a live secret key (`sk_live_…`).

<Steps>
  <Step title="Open the Stripe Dashboard">
    Go to [**Developers → API keys → Create restricted key**](https://dashboard.stripe.com/apikeys/create).
  </Step>

  <Step title="Grant read-only Billing access">
    Set **Read** on **Customers** (Core), and switch the entire **Billing** section to **Read** — that covers Subscriptions and Invoices in one click. No write scopes and no Account scope are required.
  </Step>

  <Step title="Copy the key">
    Create the key and copy it. A restricted key starts with `rk_`. (A test-mode key works too, so you can try the import against sandbox data first.)
  </Step>
</Steps>

## Connect and import

<Steps>
  <Step title="Paste the key">
    In Vibefollow, open **Import → Stripe**, paste the restricted key, and click **Connect Stripe**. The key is validated live against Stripe, encrypted at rest, and never shown again.
  </Step>

  <Step title="Pick an import window">
    Choose how far back to import — all time, or the last 3 / 6 / 12 / 24 months.
  </Step>

  <Step title="Run the backfill">
    Click **Import my customers**. The backfill runs in the background; progress shows live and you can cancel between batches.
  </Step>
</Steps>

<Warning>
  Live secret keys (`sk_live_…`) are rejected before any network call. Always create a dedicated **restricted** key — it is read-only, so Vibefollow can never modify your Stripe data.
</Warning>

## After the import

The import is one-time, not a live sync. You can re-run it later to pull in newer billing history, but ongoing real-time signals should come through the SDK:

* Keep emitting product-usage events (`feature_used`, `onboarding_step`, `usage_threshold_reached`) from your backend.
* New billing events can continue to arrive via the SDK, or via a fresh Stripe import.

See the [SDK quickstart](/quickstart) to wire up real-time events.