POST /subscriptions/{subscription-id}/move

Moves a subscription from one customer to another asynchronously. All related resources such as unbilled_charge, invoice, credit_note, and transaction are also moved to the new customer.

After moving, Chargebee adds a comment to the original customer resource to document the move, including the to_customer_id and the ids of all the resources transferred to the destination customer.
Warning

If auto_collection is on, it might fail after this operation. Refer to the warning in copy_payment_source for details.
During the time that it takes for the operation to complete, no modifications are allowed on the source customer, the destination customer, and the subscription.
After moving a subscription, the change does not reflect in Chargebee Billing's accounting integrations or in Chargebee RevRec.
This API will return an error when multi-frequency billing is enabled.

Prerequisites {#move-prerequisites}

The subscription should not be part of a customer resource that is within an account hierarchy relationship.
There must be no invoices with the statuses payment_due, pending, or posted associated with the subscription.
The site must have consolidated invoicing disabled.
There should be no consolidated invoices linked to the subscription.
No credit_note resources with the statuses adjusted or refund_due should be associated with the subscription.
The site must have multi business entity disabled.

Asynchronous operation {#move-async}

If the above prerequisites are met, the API call returns a 200 OK response containing the subscription resource as is. However, the actual move operation can take up to five minutes to complete.

To know whether the operation was successful, we recommend that you watch for the subscription_changed event and see if subscription.customer_id has changed.

Limitations {#move-limitations}

Subscriptions cannot be moved on the same calendar day as their renewal. For instance, if a renewal is scheduled for 2 PM on April 10, 2024, the endpoint is restricted from 12 AM on April 10, 2024, until the renewal is completed.
After moving a subscription, the change does not reflect in Chargebee Billing's accounting integrations or in Chargebee RevRec.

Note : Resources linked to the original customer such as unbilled_charge, invoice, credit_note, and transaction but not linked to the subscription being moved, are not moved to the destination customer by this operation.

Servers

{protocol}://{site}.{environment}:{port}/api/v2
{protocol}://{site}-test.{environment}:{port}/api/v2

Path parameters

Name	Type	Required	Description
`subscription-id`	String	Yes

Request headers

Name	Type	Required	Description
`chargebee-request-origin-device`	String	No	The device from which the customer has made the request
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/x-www-form-urlencoded"
`chargebee-event-webhook`	String	No	skip only webhooks Possible values: `"all-disabled"`
`chargebee-business-entity-id`	String	No	If the site has multiple business entities, you can use this custom HTTP header to specify the business entity for which Chargebee should perform the operation.
`chargebee-event-actions`	String	No	skip all actions to be done on the events Possible values: `"all-disabled"`
`chargebee-request-origin-user`	String	No	The email address of your customer/user. Use this when the email address has only ASCII characters.
`chargebee-request-origin-ip`	String	No	The IP address of the customer where the request originated
`chargebee-request-origin-user-encoded`	String	No	The Base64-encoded email address of your customer/user. Use this if the email address has UTF-8 characters. When this header is provided, the header `chargebee-request-origin-user` is ignored.
`chargebee-event-email`	String	No	skip only emails Possible values: `"all-disabled"`

Request body fields

Name Type Required Description

Name	Type	Required	Description
`copy_payment_source`	Boolean	No	When `true`: If the subscription has an associated `payment_source`: A new duplicate copy of the `payment_source` resource is created. This new copy of the payment source is linked to the subscription and the destination customer. Note : Deleting any copy of the `payment_source` also deletes the other copies and the details stored at the payment gateway. When `false`: No new payment source is created for the subscription. Moreover, if a `payment_source` is already linked to the subscription, it gets removed, meaning the `subscription.payment_source_id` is cleared. Warning : When `copy_payment_source` is `false` and if subscription.auto_collection is enabled, auto-collection will fail, in turn preventing subscription renewal. To prevent auto-collection failure, link a payment source to the subscription after this operation. Default value: false
`to_customer_id`	String	Yes	Specifies the unique ID of the `customer` resource to which the subscription will be moved. Note : If there are multiple business entities, the `customer.business_entity_id` of the destination customer must match the `subscription.business_entity_id`.

copy_payment_source

Boolean

When true:

If the subscription has an associated payment_source:

A new duplicate copy of the payment_source resource is created.
This new copy of the payment source is linked to the subscription and the destination customer.

Note : Deleting any copy of the payment_source also deletes the other copies and the details stored at the payment gateway.

When false:

No new payment source is created for the subscription. Moreover, if a payment_source is already linked to the subscription, it gets removed, meaning the subscription.payment_source_id is cleared.
Warning : When copy_payment_source is false and if subscription.auto_collection is enabled, auto-collection will fail, in turn preventing subscription renewal. To prevent auto-collection failure, link a payment source to the subscription after this operation.

Default value: false

to_customer_id

String

Yes

Specifies the unique ID of the customer resource to which the subscription will be moved.
Note : If there are multiple business entities, the customer.business_entity_id of the destination customer must match the subscription.business_entity_id.

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.