Subscriber Wallet lets customers store multiple payment methods on a single account and assign specific billing info to individual subscriptions or purchases. A primary payment method serves as the default for all transactions, with the flexibility to override it per subscription — and a backup payment method available if a charge fails.

Additional fees apply — contact your Account Manager or Recurly Support to learn more

1Definition 2Key details 3Account hierarchy support 4Feature compatibility 5Exports

Definition

Subscriber Wallet is a Recurly feature that allows merchants and their subscribers to manage multiple payment methods on an account. Each payment method gets a unique billing info ID that can be assigned to specific subscriptions or one-time purchases. A primary payment method acts as the default for all transactions unless a different billing info ID is specified.

Key details

Setup

Wallet must be included in your Recurly contract. Contact [email protected] to enable it.

For new sites, Credit Invoices and Only Bill What Changed are enabled by default
Legacy sites may need to manually activate these feature flags before using Wallet
Use the latest API versions to ensure compatibility

Payment methods and subscriptions

The first payment method added to an account automatically becomes the primary payment method
An account can store up to 20 billing infos
Subscriptions default to the primary billing info when no billing_info_id is set. If the primary payment method changes, those subscriptions switch to the new primary
Setting a billing_info_id on a subscription assigns it to a specific, non-primary payment method. That assignment persists even if the primary payment method later changes
If a subscription's assigned payment method is deleted, it falls back to the account's primary payment method
Deleting all payment methods on an account with active subscriptions may cause subscriptions to expire unless a new payment method is added promptly

Invoices

Invoices generated via API use the billing info provided in the request, a specified billing_info_id, or the account's primary billing info if neither is provided
Past-due invoices can have their associated billing info updated via API for collection retries
Updating billing info on an account triggers a collection attempt on all unpaid invoices associated with that billing info
Unpaid or past-due invoices default to the primary payment method unless a specific payment method is set on the invoice

Deleting billing infos

Non-primary billing infos can be deleted freely
The sole primary billing info on an account can be deleted
When multiple billing infos exist, a new primary must be set before the current primary can be deleted

Note Subscriptions or invoices linked to a deleted billing info automatically switch to the primary billing info for future charges or retries, unless a new billing info is specified.

Collection method behavior

Collection method	Behavior
Automatic	Defaults to the primary billing info unless a specific `billing_info_id` is set on the subscription or invoice.
Manual	No billing info is required. Switching a subscription from Automatic to Manual removes any previously assigned billing info.

Admin UI

The Recurly Admin UI supports Wallet with a read-only view. Supported payment methods — including Visa, Mastercard, PayPal, and Amazon Pay — are displayed on the account page. Editing non-primary billing info is not available through Hosted Account Management pages, which display the primary billing info only.

Account hierarchy support

Wallet integrates fully with Account Hierarchy, including Invoice Rollup.

Child billing self

The child account manages its own payment:

Can use its primary payment method or a specific assigned payment method
The child account's backup payment method is used if an invoice fails

Important behaviors when changing bill-to accounts

All invoices must be paid before changing the bill_to account
After a bill_to change, subscriptions default to the primary payment method of the new bill_to account until a different payment method is specified
Changing the bill_to clears any previously set billing_info_id on a subscription. If the bill_to changes again, subscriptions default to the primary billing info of the new account until a new billing_info_id is set
Uninvoiced charges are included in the next invoice using the associated payment method at time of invoicing

Feature compatibility

Compatible features

Feature	Notes
Backup payment method	Provides an additional recovery mechanism if a primary charge fails.
Custom gateway routing	Fully compatible with Wallet payment routing.
Gateway failover	Fully compatible with Wallet payment routing.
Account Updater	Fully compatible with Wallet payment routing.
Calendar billing	Subscriptions set to Align or Aggregate onto the same invoice will do so if they share the same payment method.
3DS / PSD2	Wallet supports 3DS flows. Transaction challenges are linked to the specific billing info initially attempted.
All Recurly-supported payment methods	See the supported payment methods list.

Incompatible features

Auth and Capture
Adyen HPP
Verify Billing Info Endpoint

Additional behavior notes

Refunds are processed to the original payment method used for the transaction
To change billing info for the next recurring charge, update the billing info before the charge is due
For an immediate subscription change, update billing info before making the change
Recurly email templates include only the primary billing info
Third-party integrations (NetSuite, Salesforce, Zendesk) display only the primary payment method — and only when it is a credit card
The GET /accounts endpoint returns accounts with only the primary billing info
Fraud prevention applies at the account level, not at the individual billing info level

Exports

Accounts export (v4)

New and updated columns added to the Accounts export:

Column	Description
`primary_payment_method`	`TRUE` or `FALSE` — indicates whether this billing info is the primary payment method.
`billing_info_id`	The ID of the billing info for this row.
`tax_location_valid`	Tax location validity based on the specific billing info in each row.

Billing info export (v5)

New columns added to the billing_info export:

Column	Description
`primary_payment_method`	`TRUE` or `FALSE` — indicates whether this billing info is the primary payment method.
`billing_info_id`	The ID of the billing info.