Stripe Connector Setup

Overview

The Stripe connector is a source connector that extracts billing and subscription data for revenue planning. It uses the Stripe REST API with auto-pagination to pull customers, subscriptions, invoices, products, and prices. Authentication requires a single API key -- restricted keys with read-only access are strongly recommended.

Prerequisites

• A Stripe account (test mode or live mode)
• Access to the Stripe Dashboard to create API keys
• Stripe API version 2023-10-16 or later

Credential Fields

| Field | Required | Description | |-------|----------|-------------| | apiKey | Yes | Stripe API key. Use a restricted key with read-only access for security. |

Supported Object Types

| Object Type | Stripe Resource | Key Fields Extracted | |---|---|---| | customer | /v1/customers | ID, email, name, created, metadata, default payment method | | subscription | /v1/subscriptions | ID, customer, status, current period, items, plan, cancel date | | invoice | /v1/invoices | ID, customer, subscription, amount, status, line items, period | | product | /v1/products | ID, name, description, active, created, metadata | | price | /v1/prices | ID, product, unit amount, currency, recurring interval, active |

Setup Steps

1. Create a Restricted API Key

   In the Stripe Dashboard, navigate to Developers > API Keys > Create restricted key. Configure the following read-only permissions:

   • Customers: Read
   • Subscriptions: Read
   • Invoices: Read
   • Products: Read
   • Prices: Read

   Name the key "VersionForge Read-Only" and save. Copy the key (it starts with rk_test_ or rk_live_).

   Never use your Stripe secret key (sk_*) for VersionForge. A restricted key limits the blast radius if the key is ever exposed. VersionForge only needs read access.

2. Choose Test or Live Mode

   For initial setup and testing, use a test mode restricted key (rk_test_*). Test mode provides synthetic data that lets you validate the integration without touching real customer records. Switch to a live mode key when you are ready to extract production data.

3. Configure the Credential in VersionForge

   Go to Administration > Credentials > Add Credential. Select Stripe as the connector type. Enter the apiKey.

4. Configure the Sync Profile Source

   Create a sync profile with Stripe as the source. Select the object types you want to extract:

   {
     "objectType": "subscription",
     "filters": {
       "since": "2026-01-01T00:00:00Z"
     },
     "limit": 10000
   }
   

Incremental Extraction

The Stripe connector supports incremental extraction via the since filter. When set, VersionForge passes a created[gte] parameter to the Stripe API, limiting results to objects created on or after the specified timestamp.

For subscriptions, VersionForge also sets status=all to include canceled and past-due subscriptions in the extraction. This ensures your churn analysis captures the full lifecycle.

{
  "filters": {
    "since": "2026-03-01T00:00:00Z"
  }
}

Test Your Connection

Click Test Connection on the credential detail page. VersionForge calls stripe.accounts.retrieve() to verify the API key is valid. A successful test confirms:

• The API key is active and not revoked
• The key has sufficient permissions to authenticate
• The Stripe API is reachable from your VersionForge deployment

Field Extraction

VersionForge extracts a curated set of fields from each Stripe object, flattening nested paths into underscore-separated keys. For example, a subscription's plan.amount becomes plan_amount in the extracted record.

The content hash for each record is computed from the extracted fields, enabling VersionForge's change detection engine to detect changes between extraction runs without re-downloading unchanged records.

Common Issues

Invalid API Key -- The key was deleted, or you are mixing test and live mode keys. Verify the key in the Stripe Dashboard under Developers > API Keys.

Permission denied for a resource -- The restricted key is missing read access for the requested object type. Edit the key's permissions in the Stripe Dashboard.

Empty extraction for subscriptions -- If your since filter date is in the future, or you are using a test mode key with no test data, the extraction will return zero records. Create test data in Stripe's test mode or adjust the filter date.

Rate limiting -- Stripe allows 100 requests per second in live mode and 25 in test mode. VersionForge uses auto-pagination with a page size of 100 objects, so rate limiting is rare unless you are running multiple sync profiles simultaneously.