Articles in this section

Stripe + Iterable Integration

The Stripe integration brings customer, subscription, and payment activity from Stripe into Iterable in real time. Use it to keep user profiles current, to message customers when a subscription starts or ends, and to start a recovery journey when an invoice payment fails.

New activity syncs after setup. You can also import existing Stripe customers into Iterable user profiles when you turn the integration on.

# In this article

# Overview

Each Stripe event is matched to an Iterable user, then written in one of two ways:

  • Customer events update the Iterable user profile.
  • Subscription, charge, and invoice events are tracked as Iterable custom events, which you can use as journey triggers and for segmentation.
Stripe event What Iterable stores Iterable event name
Customer created User profile update —
Customer updated User profile update —
Subscription created Custom event stripeSubscriptionCreated
Subscription deleted Custom event stripeSubscriptionDeleted
Charge succeeded Custom event stripeChargeSucceeded
Invoice payment failed Custom event stripeInvoicePaymentFailed

Customer created and customer updated use the same profile fields.

# Prerequisites

Connecting Stripe requires that:

  • You can create a restricted API key for the Stripe account you want to connect.
  • Your Stripe customers have the identifier required by your Iterable project, as described below.

# How users are identified

The identity type is set on the Iterable connection, rather than selected separately for Stripe.

Iterable project type Identifier used
Email-based Stripe customer's email address
User ID-based Stripe customer ID (cus_...), used as Iterable userId

  • For an email-based project, Sync settings includes Also map Stripe customer ID to Iterable userId. This option is off by default. Turn it on only if you want to use Stripe customer IDs as Iterable userId values.

  • For a user ID-based project, Stripe customer IDs are always used as userId values. To match existing Iterable users, their userId values must match the Stripe customer IDs. The integration doesn't set the profile email unless you add an email field mapping.

# Setup

# 1. Create a restricted Stripe API key

  1. In the Stripe Dashboard, go to Developers > API keys.
  2. Create a restricted API key with the following permissions:
Resource Permission Used for
Customers Read Customer updates, customer lookups, and historical customer import
Subscriptions Read Subscription created and deleted events
Charges and Refunds Read Charge succeeded events
Invoices Read Invoice payment failed events
Webhook endpoints Write Creating, updating, and removing the integration's webhook endpoints
  1. Copy the key. You will paste it into Iterable.

# 2. Connect Stripe and Iterable

  1. In Iterable, go to Integrations > Integrations Hub.
  2. Open Stripe.
  3. On Connections, enter the restricted Stripe API key and connect the Iterable project that will receive the data.

# 3. Choose what to sync

On Sync settings, select the activity you want to sync. All events are enabled by default.

Group Events
User updates Customer profile updates (created and updated)
Custom events Subscription created, Subscription deleted, Charge succeeded, Invoice payment failed

# 4. Choose whether to import existing customers

Under Historical import, enable Import existing customers to import current Stripe customers when you finish setup. This option is off by default.

The import:

  • Includes customers only. Existing subscriptions, charges, and failed invoices are not imported.
  • Uses the same identity settings and customer field mappings as live customer updates.
  • Runs once. Turning the option off and on again after the import has started doesn't run another import.

# 5. Review field mappings

On Field Mapping, each selected event has a tab with default mappings.

  • Stripe field: Select a source field from the dropdown.
  • Iterable field: Enter the destination field name on the user profile or custom event.
  • Add a row to map another available Stripe field, or remove a row to stop syncing that field.

See Default user profile mappings and Default custom event mappings for the fields included by default.

# 6. Review and finish

On Review, confirm your selected events and field mappings, then finish setup. If you enabled Import existing customers, the import starts.

# 7. Confirm data is syncing

  1. Confirm that customer profile updates are enabled.
  2. In the connected Stripe account and mode, create or update a customer with the identifier required by your Iterable project.
  3. Open the corresponding user profile in Iterable and check for the mapped fields, such as stripeCustomerId.
  4. To test custom events, generate one of the selected activities in Stripe and check the user's event history in Iterable.

Custom events appear under the event names listed in the Overview.

# Default user profile mappings

Customer created and customer updated use the following mappings by default.

For email-based projects, the email address identifies the user and is handled separately from these mappings.

Stripe field Iterable field Type
id stripeCustomerId string
name stripeName string
phone stripePhone string
currency stripeCurrency string
created stripeCreatedAt date

# Default custom event mappings

The following tables describe the default mappings. If you add, remove, or rename fields during setup, the resulting event data reflects those changes.

# Subscription created → stripeSubscriptionCreated

Use this event to start a subscription onboarding journey.

Stripe field Iterable data field Type
id subscriptionId string
customer stripeCustomerId string
status status string
currency currency string
current_period_start currentPeriodStart date
current_period_end currentPeriodEnd date
trial_start trialStart date
trial_end trialEnd date

If a subscription has no trial, trialStart and trialEnd are omitted.

# Subscription deleted → stripeSubscriptionDeleted

Use this event to start a win-back journey when a subscription ends.

Scheduling a cancellation for the end of a billing period does not immediately trigger this event. It is sent when the subscription actually ends.

Stripe field Iterable data field Type
id subscriptionId string
customer stripeCustomerId string
status status string
canceled_at canceledAt date
cancellation_details cancellationDetails object

cancellationDetails contains Stripe's cancellation details. The reason is available in cancellationDetails.reason, such as cancellation_requested.

# Charge succeeded → stripeChargeSucceeded

Use this event to trigger messaging after a successful charge.

Stripe field Iterable data field Type
id chargeId string
customer stripeCustomerId string
amount amount number
currency currency string
description description string
payment_method paymentMethodId string
receipt_url receiptUrl string

# Invoice payment failed → stripeInvoicePaymentFailed

Use this event to start a payment-recovery journey.

Stripe field Iterable data field Type
id invoiceId string
customer stripeCustomerId string
parent.subscription_details.subscription subscriptionId string
amount_due amountDue number
amount_paid amountPaid number
currency currency string
attempt_count attemptCount number
next_payment_attempt nextPaymentAttempt date
status status string

The default mapping reads subscriptionId from parent.subscription_details.subscription, falling back to the top-level subscription field for older Stripe API versions.

When present, nextPaymentAttempt indicates the next scheduled payment attempt.

# Notes

  • Temporary problems are retried. If Iterable or the Stripe customer lookup fails because of a temporary error, the same delivery is tried up to three times. A delivery that can't be matched, or that Iterable rejects as invalid, is not retried.

  • Historical import is customers only, and it runs once. Existing subscriptions, charges, and failed invoices from before setup are not imported.

Related articles