How to move a subscription from one customer to another?
Problem Statement
You want to move an existing subscription from one customer record to another in Chargebee.
Solution
Chargebee provides two ways to move subscriptions between customers:
- Merge customers: Combine two customer records and move all subscriptions under a single customer.
- Move a subscription API: Move one or more subscriptions from one customer to another without merging the customer records.
Choose the approach based on whether you want to consolidate the entire customer data or move only specific subscriptions.
Additional Information
- If Account Hierarchy is enabled, the Merge customers API does not work. To move a subscription while Account Hierarchy is enabled, see How to move a subscription from one customer to another with account hierarchy.
- The Merge customers API moves the following from one customer to another:
- Payment methods
- Subscriptions
- Invoices
- Credit notes
- Transactions
- Unbilled charges
- Orders
- The Move a subscription API is not enabled by default. Contact Chargebee Support to enable it for your site.
- Limitations:
- Events and email logs are not moved
- Virtual bank accounts cannot be moved between customers
- When using Merge customers API, all subscriptions of the source customer are moved to the target customer
- With third-party accounting (e.g., Xero), the subscription may remain mapped to the original customer record after moving
- The Move a subscription API cannot be used when Multi-Frequency Billing is enabled.
- Move a subscription API — payment source: If you omit
copy_payment_sourceor set it tofalse, Chargebee removes any payment source linked to the subscription. When auto-collection is enabled, renewal can fail unless you link a payment source to the subscription after the move. Setcopy_payment_sourcetotrueto duplicate the linked payment source on the destination customer. See Move a subscription in the API reference. - Move a subscription API prerequisites: The operation is asynchronous. Before you call the API, ensure that the subscription's current customer is not in an Account Hierarchy relationship, consolidated invoicing is disabled, and no consolidated invoices are linked to the subscription. Resolve invoices linked to the subscription that are in Payment Due, Pending, or Posted status (for example, collect payment, void, or write off as appropriate for your process). The subscription must also have no linked credit notes with status
adjustedorrefund_due. When MBE is enabled, the destination customer must belong to the same business entity as the subscription. You cannot move a subscription on its renewal day until renewal completes (from the start of that calendar day until the renewal job finishes). If validation fails, the move job does not complete and you may see an error such as Invoice status cannot be in [ Payment Due ] state (the status name in the message matches the blocking invoice). - Move appears stuck or retries are blocked: If a move attempt does not complete, a later retry can return Merge operation for [customer-id] is already scheduled, even when no move appears to be in progress. A failed attempt can leave scheduling state on the source or target customer that blocks new move calls until it is cleared.
- Resolve any invoices still in Payment Due, Pending, or Posted status for the subscription you are moving.
- If you deleted the target customer after a failed move, create a new target customer record. The Move a subscription API cannot move a subscription to a deleted customer.
- Contact Chargebee Support with the customer ID from the error message and your site name so they can clear the stale scheduling state.
- Retry the Move a subscription API call after support confirms cleanup, or after a previously failed job completes successfully.