Stripe

Sync customer data from your warehouse to Stripe. Keep your Stripe customer records enriched with the latest profile data, addresses, and custom metadata from your data warehouse.

Prerequisites

• A Stripe account (any plan)
• A Stripe secret API key with write access to the Customers resource
• Access to the Stripe Dashboard (Developers section)

Authentication

Stripe uses a secret API key for authentication.

Secret API Key

1. Log in to the Stripe Dashboard
2. Navigate to Developers > API keys
3. Copy your Secret key (starts with sk_live_... for production or sk_test_... for test mode)
4. Paste it into the Secret Key field in Zeotap

Important: Use the secret key, not the publishable key. The publishable key (pk_...) does not have write access to customer data.

For test syncs, use a test mode key (sk_test_...). Switch to a live key (sk_live_...) when you are ready to sync to production.

Configuration

Stripe does not require additional configuration fields beyond authentication.

Target Settings

Supported Operations

Sync Modes

Audience Sync Modes

Stripe does not have a list or audience membership concept, so audience sync modes are not supported.

Features

• Field Mapping: Yes
• Schema Introspection: No — Stripe customer fields are well-known and provided as default destination fields

Required Mapping Fields

Default Destination Fields

Any field not in the standard list above is automatically sent as a metadata[field_name] key-value pair on the Stripe customer object. Stripe metadata supports up to 50 keys, each with a maximum of 500 characters for both key and value.

How It Works

1. Field Mapping: Zeotap maps your warehouse columns to Stripe customer fields. Standard fields (email, name, phone, description, address) are sent as top-level parameters. All other fields are sent as customer metadata.

2. Request Format: Stripe requires application/x-www-form-urlencoded request bodies (not JSON). Zeotap handles this encoding automatically. Nested fields use bracket notation (e.g., address[line1], metadata[plan]).

3. Per-Record API Calls: Stripe does not offer a batch API for customer management. Each row in your sync results in a single API call. Zeotap processes rows sequentially within each batch.

4. Sync Mode Behavior:

   • Insert: Creates a new customer for every row via POST /v1/customers.
   • Update: Updates an existing customer via POST /v1/customers/{id}. Requires a Stripe customer ID in the configured ID field.
   • Upsert: If a Stripe customer ID is present, attempts to update the customer. If the customer does not exist (404), creates a new one. If no ID is present, creates a new customer.

5. Error Handling: Failed rows are tracked individually with per-row error details. Transient errors (rate limits, server errors) are retried automatically with exponential backoff.

Rate Limits

Stripe enforces a default rate limit of 25 requests per second per API key in live mode. Test mode keys have a lower limit of 25 requests per second as well.

Zeotap automatically handles rate limiting:

• HTTP 429 responses trigger exponential backoff with retry
• The Retry-After header is respected when present
• Up to 3 retries per request

Because Stripe has no batch API, syncing large datasets (10,000+ customers) may take several minutes. Consider scheduling syncs during off-peak hours if you are close to your rate limit.

Best Practices

• Use test mode first: Configure your destination with a test mode API key (sk_test_...) and validate the sync before switching to production.
• Map the customer ID field: For upsert and update modes, always configure the Customer ID Field in target settings and map a column containing the Stripe customer ID (cus_...). Without it, upsert mode creates duplicate customers.
• Keep metadata lean: Stripe limits metadata to 50 keys per customer. Map only the fields you need.
• Use address bracket notation: Map address components to address[line1], address[city], etc. to populate the structured address object on the customer.

Troubleshooting

Authentication failed: invalid API key

Verify you are using a secret key (starts with sk_live_... or sk_test_...), not a publishable key (pk_...). Regenerate the key in the Stripe Dashboard if it has been revoked.

Customer ID is required for update mode

Update mode requires a Stripe customer ID (cus_...) for each row. Ensure the Customer ID Field is configured in target settings and that the corresponding column in your warehouse contains valid Stripe customer IDs.

Rate limiting (429 errors)

Stripe limits API requests to 25 per second. Zeotap retries automatically, but persistent rate limit errors may indicate too many concurrent syncs or other applications sharing the same API key. Reduce sync frequency or contact Stripe to request a higher rate limit.

Metadata key limit exceeded

Stripe allows a maximum of 50 metadata keys per customer. If your field mapping includes more than 50 non-standard fields, some will be rejected. Reduce the number of mapped fields or consolidate data into fewer keys.

Customer not found (404) in update mode

The Stripe customer ID in your data does not match an existing customer. Verify the ID column contains valid cus_... identifiers. In upsert mode, a 404 triggers automatic creation of a new customer.

Address fields not populating

Ensure address fields are mapped using bracket notation: address[line1], address[city], address[state], address[postal_code], address[country]. Mapping to address_line1 or line1 will send the value as metadata instead of the structured address object.

Test mode vs. live mode data mismatch

Test mode and live mode are completely separate environments in Stripe. Customer IDs from test mode (cus_... created with sk_test_) do not exist in live mode. When switching from test to production, update your API key and expect new customers to be created.

Sync is slow for large datasets

Stripe does not offer a batch API — each customer requires an individual API call. At 25 requests per second, syncing 10,000 customers takes approximately 7 minutes. Schedule large syncs during off-peak hours.