POST /business_entities/transfers

Prerequisites

• Transfers must always be initiated for an active customer resources and never for a deprecated resources.

• A customer resource cannot be transferred more than three times in a single calendar year. For example, if already moved thrice in the year 2023, a customer resource can only be moved again in 2024.

• The customer resource must not have any of the following:

  • An account hierarchy relationship.

  • subscription resource with

    • status in_trial or
    • advance invoice schedules. (subscription.has_scheduled_advance_invoices as true.)

  • invoice resource with status as pending. (Close pending invoices before invoking this API.)

  • invoice resources that are advance invoices. (invoice.has_advance_charges as true.)

  • quote resources with status as open or accepted.

  • transaction resource with:

    • status as in_progress or
    • status as success, type as authorization, and a non-zero amount_capturable.

  • Non-zero unbilled_charges. (Invoice unbilled charges before invoking this API.)

  • Non-zero refundable_credits. (Apply credits to unpaid invoices before invoking this API.)

• The customer resource must not be a gifter of a gift subscription with status scheduled or unclaimed.

Mechanics of business entity transfer

When calling this endpoint, the active and deprecated resources are processed as follows:

1. For the active resource:

   1. id and active_id are set to match the deprecated resource's id.
   2. business_entity_id is set to destination_business_entity_id parameter.

2. For the deprecated resource:

   1. For customer and subscription resources, the value of active_id is set to match the resource id.
   2. The value of id is changed to a new random value.

Considerations for business entity transfer

• When this API is endpoint is called, Chargebee blocks concurrent calls to incompatible POST operations.

• When a resource is transferred more than once, each transfer deprecates the previous active resource and creates a new active resource.

• payment_source resources linked to the customer are immediately transferred to the destination business entity.

• subscription resources linked to the customer are transferred automatically to the destination business entity as follows:

  • active subscription resources are transferred on their next renewal.
  • paused subscription resources are transferred when resumed.
  • future subscription resources are transferred on their start_date.
  • non_renewing and cancelled subscription resources are not transferred and remain linked to the deprecated customer resource.

• Other resources linked to the customer, such as invoice, quote, credit_note, and transaction, remain linked to the deprecated customer resource.

• Deprecated customer and subscription resources are not returned in list APIs such as List customers or List subscriptions.

Example

The following example illustrates the transfer of a customer resource from a business entity (source) to another (destination). The example also shows how payment_source, subscription, and invoice resources attached to the customer resource are affected.

1. Initial state before the transfer

Imagine a customer resource with the id Ab6dRFt belonging to the business entity acme-us . This customer has a linked payment_source , subscription , and an invoice .

2. Invoking the API endpoint

To transfer the customer resource to a new business entity acme-eu, you would call the endpoint as follows:

curl  https://{site}.chargebee.com/api/v2/business_entities/transfers \
-u {api_key}:\
-d active_resource_ids[0]="Ab6dRFt" \
-d destination_business_entity_ids[0]="acme-us" \
-d reason_code[0]="correction"

The customer resource is deprecated in favor of a new active customer resource. Notice that the id of the deprecated customer resource is transferred to the new, active customer resource. Meanwhile, the deprecated resource is assigned a new random id.

The payment_source resource is also deprecated and a new active payment_source resource is created and linked to the new customer resource. Here too, the active resource adopts the id of the deprecated payment_source, which in turn is assigned a new random id.

The subscription and invoice resources remain linked to the deprecated customer resource.

3. Transfer of linked subscription resources

When the subscription renews, it automatically transfers to the business entity of the active customer resource. This process mirrors the transfer of the customer resource, resulting in a new active subscription resource linked to the active customer resource and the business entity acme-eu.