Recharge + Iterable Integration

The Recharge integration brings subscription customers, subscriptions, orders, and charges from Recharge into Iterable in real time. Use it to personalize campaigns with subscription status and product details, to message customers before an upcoming charge, and to start a recovery journey when a charge fails.

The integration syncs new activity after setup; it does not backfill existing Recharge data.

# In this article

# Overview

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

• Customer events update the Iterable user profile (name, Recharge customer ID, and subscription counts).
• Subscription, order, and charge events are tracked as Iterable custom events, which you can use as journey triggers and for segmentation.

Recharge event	What Iterable stores	Iterable event name
Customer created	User profile update	—
Customer updated	User profile update	—
Subscription created	Custom event	rechargeSubscriptionCreated
Subscription updated	Custom event	rechargeSubscriptionUpdated
Subscription cancelled	Custom event	rechargeSubscriptionCancelled
Subscription paused	Custom event	rechargeSubscriptionPaused
Order created	Custom event	rechargeOrderCreated
Order upcoming	Custom event	rechargeOrderUpcoming
Charge upcoming	Custom event	rechargeChargeUpcoming
Charge failed	Custom event	rechargeChargeFailed

Customer created and customer updated write the same profile fields.

# Prerequisites

Before you connect Recharge, confirm the following:

• You can create an API token in Recharge. In the Recharge admin, go to Tools & apps > API tokens.

• The token can manage webhooks and read each object you want to sync. Set:

  • Webhooks: Read and write — Iterable creates, lists, and removes the webhooks for the events you turn on.
  • Customers: Read — required for customer created and customer updated. Also used when Iterable looks up a customer whose email or external id is not on a subscription, order, or charge webhook.
  • Subscriptions: Read — required for subscription created, updated, cancelled, and paused.
  • Orders: Read — required for order created and order upcoming, and also for charge upcoming and charge failed. Recharge treats charge webhooks as part of Orders access.

  Read access on an object covers every event for that object. You do not turn individual events on or off on the token. Iterable subscribes only to the events you leave on during setup.

• You have the token's API client secret. On the same token page, copy API client secret as well as the API token.

• Recharge customers can be matched to Iterable users with one of the identity options below.

# Identity options

Pick the option that matches how your Iterable project already identifies users. The default is email.

Identity	Choose this when	What Iterable uses
email (default)	Your Iterable project uses email as the unique identifier.	The Recharge customer's email. The Iterable profile is keyed by email.
recharge_customer_id	Your Iterable userId is the Recharge customer id.	Recharge's customer id, stored as Iterable userId.
external_customer_id	Your Iterable userId is the customer id from your ecommerce platform (for example, the Shopify customer id that Recharge stores).	external_customer_id.ecommerce, stored as Iterable userId.

When you choose recharge_customer_id or external_customer_id, Iterable doesn't copy the customer's email onto the profile. The profile is keyed only by userId. Use email if you need this integration to set the email address.

# Setup

# 1. Create a Recharge API token

1. In Recharge, go to Tools & apps > API tokens.
2. Create a token with access to:

• Webhooks: Read and write — Iterable creates, lists, and removes the webhooks for the events you turn on.
• Customers: Read — required for customer created and customer updated. Also used when Iterable looks up a customer whose email or external id is not on a subscription, order, or charge webhook.
• Subscriptions: Read — required for subscription created, updated, cancelled, and paused.
• Orders: Read — required for order created and order upcoming, and also for charge upcoming and charge failed. Recharge treats charge webhooks as part of Orders access.

3. Copy the API token and the API client secret. For help locating the secret see Recharge's webhook validation guide.

# 2. Connect Recharge and Iterable

1. In Iterable, go to Integrations > Integrations Hub.
2. Open Recharge.
3. On Connections, paste the Recharge API Key and API Client Secret.

# 3. Choose an identity and which events to sync

On Event Selection:

1. Set Primary Identifier to email, recharge_customer_id, or external_customer_id. See Identity options.
2. Leave an event on to sync it, or turn it off to ignore it. Every event is on by default.

Group	Events
User updates	Customer created, Customer updated
Custom events	Subscription created, Subscription updated, Subscription cancelled, Subscription paused, Order created, Order upcoming, Charge upcoming, Charge failed

# 4. Review and finish

On Review, confirm the identity line and the list of events that will sync.

To confirm it is working, update a Recharge customer who already has the identifier you selected (an email, a Recharge customer id, or an external customer id). In Iterable, the matching profile should show fields such as rechargeCustomerId and firstName. Subscription, order, and charge events appear on the user's event history under the names in the table above.

# User profile fields

Customer created and customer updated write these fields onto the matching Iterable user.

Recharge field	Iterable field	Type
id	rechargeCustomerId	string
external_customer_id.ecommerce	rechargeExternalCustomerId	string
first_name	firstName	string
last_name	lastName	string
subscriptions_total_count	rechargeTotalSubscriptionCount	number
subscriptions_active_count	rechargeActiveSubscriptionCount	number
has_valid_payment_method	rechargeHasValidPaymentMethod	true/false
has_payment_method_in_dunning	rechargePaymentMethodInDunning	true/false
created_at	rechargeCreatedAt	date
updated_at	rechargeUpdatedAt	date

# Custom event schemas

Every custom event also carries the identity you selected (email or userId) and, when Recharge sends one, an event id so a retried delivery is not counted twice.

# Subscription events

rechargeSubscriptionCreated, rechargeSubscriptionUpdated, and rechargeSubscriptionPaused use the fields in this table. rechargeSubscriptionCancelled uses this table plus the cancellation fields below it.

Recharge field	Iterable data field	Type
id	subscriptionId	string
customer_id	rechargeCustomerId	string
status	status	string
product_title	productTitle	string
variant_title	variantTitle	string
external_product_id.ecommerce	externalProductId	string
external_variant_id.ecommerce	externalVariantId	string
sku	sku	string
quantity	quantity	number
price	price	number
next_charge_scheduled_at	nextChargeScheduledAt	date
charge_interval_frequency	chargeIntervalFrequency	number
order_interval_frequency	orderIntervalFrequency	number
order_interval_unit	orderIntervalUnit	string
is_prepaid	isPrepaid	true/false

Cancellation fields, only on rechargeSubscriptionCancelled:

Recharge field	Iterable data field	Type
cancelled_at	cancelledAt	date
cancellation_reason	cancellationReason	string
cancellation_reason_comments	cancellationComments	string

# Order events

rechargeOrderCreated and rechargeOrderUpcoming use the same fields. Recharge sends order upcoming before the order is processed, which you can use to message a subscriber ahead of a renewal.

Recharge field	Iterable data field	Type
id	orderId	string
customer_id (or customer.id)	rechargeCustomerId	string
charge_id (or charge.id)	chargeId	string
external_order_id.ecommerce	externalOrderId	string
external_order_numbers.ecommerce	externalOrderNumber	string
status	status	string
type	orderType	string
is_prepaid	isPrepaid	true/false
currency	currency	string
total_price	totalPrice	number
scheduled_at	scheduledAt	date
processed_at	processedAt	date
created_at	createdAt	date
line_items[]	lineItems	list

# Charge events

rechargeChargeUpcoming uses the fields in this table. rechargeChargeFailed uses this table plus the failure fields below it. Recharge sends charge upcoming before it attempts the charge, and charge failed when the payment does not succeed.

Recharge field	Iterable data field	Type
id	chargeId	string
customer_id (or customer.id)	rechargeCustomerId	string
status	status	string
type	chargeType	string
currency	currency	string
total_price	totalPrice	number
scheduled_at	scheduledAt	date
processed_at	processedAt	date
created_at	createdAt	date
orders_count	ordersCount	number
line_items[]	lineItems	list

Failure fields, only on rechargeChargeFailed:

Recharge field	Iterable data field	Type
error_type	errorType	string
error	errorMessage	string
retry_date	retryAt	date
processor_name	paymentProcessor	string

errorMessage is the processor's decline text (for example, a card decline). Use rechargeChargeFailed as the journey trigger for a payment-recovery campaign, and retryAt if you want the message to account for when Recharge will try again.

# Line items

Each entry in lineItems on an order or charge event has these fields. Empty line-item values are left off that entry. If Recharge sends no line items, lineItems is omitted.

Recharge line item field	Iterable field	Type
purchase_item_id	subscriptionId	string
external_product_id.ecommerce	externalProductId	string
external_variant_id.ecommerce	externalVariantId	string
title	productTitle	string
variant_title	variantTitle	string
sku	sku	string
quantity	quantity	number
unit_price	unitPrice	number
total_price	totalPrice	number

subscriptionId on a line item is Recharge's purchase item ID for that line, and for a subscription product is the subscription ID.