Understand how Recharge create and records customers when they check out with a subscription product.

Understanding customers

Recharge creates a Customer record when a customer checks out on an ecommerce storefront with a Recharge subscription.

The Customer object contains key information such as:

  • The customer's Recharge id
  • Billing information
  • The external id associated with the customer on an ecommerce platform

The Customer record changes when either a merchant updates the Customer information or when the customer edit their information in the Recharge Customer Portal.

read_customerRequired to read to the customer record.
write_customerRequired to write to the customer record.
write_paymentsThis scope is only needed when creating or updating customer payment token information.

You may need to interact with the Customer object when, for example, a customer adds a new payment method to their account on an external e-commerce store or changes their billing information.



Creating a customer within Recharge does not create a customer record within an external ecommerce platform.

Customers and Addresses

The Addresses endpoint is a child of the Customer object. Customers can have many addresses associated with their account. Addresses cannot be associated with multiple customers.

The address nested under a customer resource is the customer's billing address associated with their payment method. It is not the address associated with delivery of a subscription. For the subscription shipping address, see Subscriptions.

Customer payment method

Update the customer object to add or update a customer's payment method. Recharge doesn't accept payment information directly. You should send a tokenized customer representation from the payment processor to add or update the payment method. When using Stripe as your payment processor, the customer token should begin with the prefix cus, not tok.

Customer FAQ

How to define and detect a churned customer?

You can use the webhook customer/deactivated to access information about customers (whether they are active or inactive). A customer is considered churned when their status is set to inactive. This happens when:

  1. A customer cancels their subscriptions or all of their subscription expires and the subscription parameter cancelled_at is shown
    1. Customers remain active if they have additional subscriptions with pending charges
  2. Max number of retries is reached on a charge and the store admin closes the charges
  3. number_of_charges_before_expiration is reached

Suggested Article

To learn about how you can view upcoming delivery schedules for customers, see the Customer Delivery Schedule page.

Need Help? Contact Us