Stripe Loader

The Stripe loader pulls payment, subscription, and customer data from your Stripe account into your data warehouse. It uses Stripe’s list API endpoints with cursor-based pagination and supports incremental sync via the created timestamp for most objects.

Prerequisites

A Stripe account (Test mode or Live mode)
A Stripe API key with read permissions
A connected Warehouse (target warehouse) with write permissions on the target schema

Authentication

The Stripe loader uses API Key authentication.

Obtaining an API Key

Log in to the Stripe Dashboard
Navigate to Developers > API Keys
Copy your Secret key (starts with sk_live_ for live mode or sk_test_ for test mode)
In SignalSmith, paste the key into the API Key field

Security recommendations:

Use a restricted key with only read permissions. In Stripe, click “Create restricted key” and grant Read access to the resources you need.
Never use your live secret key for testing. Use sk_test_ keys with SignalSmith’s test mode to validate the configuration first.

Key Type	Prefix	Use Case
Live Secret	`sk_live_`	Production data extraction
Test Secret	`sk_test_`	Testing and development
Restricted	`rk_live_` / `rk_test_`	Recommended — scoped read-only access

Available Objects

Object	API Name	Description	Default Sync Mode
Customers	`customers`	Customer records with email, name, and metadata	Incremental
Charges	`charges`	Individual payment charges (succeeded, failed, refunded)	Incremental
Subscriptions	`subscriptions`	Recurring billing subscriptions and their statuses	Incremental
Invoices	`invoices`	Invoice records tied to subscriptions or one-off payments	Incremental
Invoice Items	`invoice_items`	Individual line items on invoices	Incremental
Products	`products`	Product catalog entries	Incremental
Prices	`prices`	Pricing definitions (recurring, one-time, tiered)	Incremental
Payment Intents	`payment_intents`	Payment flow records from the Payment Intents API	Incremental
Payment Methods	`payment_methods`	Stored payment methods (cards, bank accounts)	Full Refresh
Refunds	`refunds`	Refund records associated with charges	Incremental
Disputes	`disputes`	Chargeback and dispute records	Incremental
Coupons	`coupons`	Discount coupons	Full Refresh
Plans	`plans`	Legacy pricing plans (superseded by Prices)	Full Refresh
Balance Transactions	`balance_transactions`	Ledger entries for all money movement	Incremental
Events	`events`	Stripe webhook event log (last 30 days)	Incremental

Configuration

Setting	Description	Default
API Key	Stripe secret key or restricted key	— (required)
Mode	Live or Test	Live
Objects	List of objects to sync	— (you choose during setup)
Sync Mode	Full Refresh or Incremental (per object)	Incremental
Cursor Field	Field used for incremental sync	`created`
Primary Key	Field(s) that uniquely identify a record	`id`
Target Schema	Warehouse schema for Stripe tables	— (required)
Table Prefix	Optional prefix for table names	`stripe_`
Schedule	Sync frequency	Hourly

Scheduling Notes

Rate limits: Stripe allows 100 read requests per second in live mode and 25 per second in test mode. SignalSmith paginates efficiently and respects these limits with automatic backoff.
Incremental sync cursor: Most Stripe objects use the created timestamp for incremental sync. This means records are captured when they are created, but modifications to existing records (e.g., subscription status changes) are captured by re-fetching recent records within a lookback window.
Lookback window: For incremental syncs, SignalSmith applies a configurable lookback window (default: 3 days) to re-fetch recently created records that may have been updated. This ensures modifications are captured.
Event log retention: Stripe retains events for 30 days. If you sync events, the initial backfill captures the last 30 days. Incremental syncs keep the table up to date going forward.
Nested objects: Stripe’s API returns deeply nested JSON objects (e.g., metadata, address, shipping). SignalSmith flattens these into individual columns where possible and stores complex nested structures as JSON columns.

Schema Mapping

Stripe field types are mapped to warehouse-compatible types:

Stripe Type	Warehouse Type	Notes
`string`	`VARCHAR`
`integer`	`BIGINT`	Amounts are in the smallest currency unit (cents)
`boolean`	`BOOLEAN`
`timestamp`	`TIMESTAMP`	Unix epoch converted to UTC timestamp
`hash` (nested object)	`JSON` / `VARCHAR`	Flattened when possible, JSON otherwise
`array`	`JSON` / `VARCHAR`	Stored as JSON array
`enum`	`VARCHAR`	Status fields like `active`, `canceled`, `past_due`

Currency and Amounts

Stripe stores all monetary amounts in the smallest currency unit (e.g., cents for USD, pence for GBP). The loader preserves this format. For example, a $10.50 charge is stored as 1050. Your models should divide by 100 (or the appropriate factor for the currency) when calculating display values.

Troubleshooting

Issue	Solution
”Invalid API Key provided”	Verify the key is correct and not expired. Check that you’re using the right mode (live vs. test)
“Permission denied” on specific objects	If using a restricted key, ensure the key has `Read` access to the required resources
”Rate limit exceeded”	SignalSmith handles rate limits automatically. If this persists with many objects, reduce sync frequency or stagger object extraction
Missing recent charges	Incremental sync uses `created` timestamp. Very recently created charges may appear on the next run
Amounts look wrong (too large)	Stripe amounts are in cents. Divide by 100 in your model for dollar/euro values
Nested fields are JSON strings	Complex nested objects are stored as JSON. Use your warehouse’s JSON parsing functions in models
Test mode data appearing in production	Verify you configured the loader with a `sk_live_` key, not `sk_test_`

Next Steps

Create a model to transform your raw Stripe data
Build revenue dashboards by joining customers, subscriptions, and charges
Sync enriched customer data to marketing and support tools

HubSpot Zendesk