This guide walks through the core implementation tasks for Subscriber Wallet: setting a primary payment method, storing additional payment methods, assigning billing info to subscriptions and purchases, and managing payment method changes over time. All steps are available through the Recurly API.

Not included in Starter or Pro — contact Recurly Sales to upgrade

1Definition 2Key concepts 3Integration guide 4Best practices

Definition

Subscriber Wallet is the Recurly feature that allows a single account to store multiple payment methods, each with a unique billing_info_id. One payment method is designated as primary and used as the default for all transactions. Individual subscriptions and purchases can be pinned to a specific payment method by passing its billing_info_id at the time of creation or update.

Key concepts

Concept	Description
Billing info	The full set of details associated with a payment method — card number, address, IP address, etc. Each billing info entry has a unique `billing_info_id`.
Payment method	The funding source for a transaction. Supported types include credit/debit cards, bank accounts, PayPal, and other Recurly-supported methods.
Primary payment method	The default billing info used for any transaction where no specific `billing_info_id` is provided. Every account has exactly one primary payment method at any given time.
`billing_info_id`	A unique identifier assigned to each billing info entry. Used to reference a specific payment method when creating or updating subscriptions and purchases.

Integration guide

Step 1 — Set a primary payment method

The first payment method added to an account automatically becomes the primary. Only one payment method can be primary at a time.

To designate a different existing payment method as primary, send a PUT request to:

PUT /accounts/{account_code}/billing_infos/{billing_info_id}

Include primary_payment_method: true in the request body. The previously primary method is automatically demoted to non-primary.

Step 2 — Add additional payment methods

An account can store up to 20 billing infos. Each new entry receives a unique billing_info_id that can be referenced in future subscription or purchase requests.

To add a payment method, send a POST request to:

POST /accounts/{account_code}/billing_infos

Provide the payment details in the request body (card data, bank account details, or digital wallet specifics). When updating billing info during a transaction via the /purchases or /subscriptions endpoints, the following rules apply:

If primary_payment_method: true — the existing primary billing info is updated
If primary_payment_method: false — a new non-primary billing info is created
If primary_payment_method is omitted — the existing primary billing info is updated

Step 3 — Assign a payment method to a subscription or purchase

When creating or updating a subscription or purchase, pass the billing_info_id of the desired payment method to pin it to that specific method.

On subscription creation or update:

POST /subscriptions
PUT  /subscriptions/{subscription_id}

On purchase:

POST /purchases

Include billing_info_id at the subscription or line-item level. If no billing_info_id is provided, the account's current primary payment method is used.

Note A subscription pinned to a specific billing_info_id retains that assignment even if the account's primary payment method later changes. If the assigned billing info is deleted, the subscription falls back to the primary.

Step 4 — Update a subscription's payment method

To change the payment method on an existing subscription, send a PUT request to the subscription with the new billing_info_id:

PUT /subscriptions/{subscription_id}

To reassign a subscription back to the primary payment method without specifying an ID, omit billing_info_id from the request — the subscription will default to whatever is currently primary.

Step 5 — List and manage payment methods

To retrieve all payment methods stored on an account:

GET /accounts/{account_code}/billing_infos

Each entry in the response includes its billing_info_id and a primary_payment_method flag.

To update the details of an existing payment method (for example, a new card number or updated billing address):

PUT /accounts/{account_code}/billing_infos/{billing_info_id}

To delete a non-primary payment method:

DELETE /accounts/{account_code}/billing_infos/{billing_info_id}

To delete the primary payment method when multiple are present, first promote a different method to primary using the PUT endpoint above, then delete the former primary.

Deleting the only payment method Deleting all payment methods on an account with active subscriptions may cause those subscriptions to expire unless a new payment method is added. Subscriptions or invoices linked to a deleted billing info automatically fall back to the primary — or expire if no primary exists.

Step 6 — Change the primary payment method

To promote a payment method to primary:

PUT /accounts/{account_code}/billing_infos/{billing_info_id}

Set primary_payment_method: true in the request body. The current primary is automatically demoted.

When the primary payment method changes:

Subscriptions with no billing_info_id set switch to the new primary
Subscriptions pinned to a specific billing_info_id are unaffected
Updating billing info triggers a collection attempt on all unpaid invoices associated with that billing info

Best practices

Avoid submitting identical billing info multiple times for the same account. Recurly's duplicate billing info prevention feature can help block accidental duplicates, but the account will error once the 20-method limit is reached
Reference existing payment methods by billing_info_id rather than re-submitting the same card or account details on each purchase or subscription
To change the payment method used for the next recurring charge, update the subscription's billing_info_id before the charge date
For immediate subscription changes, update the billing info before initiating the change to ensure the correct method is charged