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.

<h4 id="mechanics">Mechanics of business entity transfer</h4>
<p>When calling this endpoint, the active and deprecated resources are processed as follows:</p>

<ol>
    <li>For the active resource:</li>
    <ol>
        <li><code>id</code> and <code>active_id</code> are set to match the deprecated resource's <code>id</code>.</li>
        <li><code>business_entity_id</code> is set to <code>destination_business_entity_id</code> parameter.</li>
    </ol>
    <li>For the deprecated resource:</li>
    <ol>
        <li>For <code>customer</code> and <code>subscription</code> resources, the value of <code>active_id</code> is set to match the resource <code>id</code>.</li>
        <li>The value of <code>id</code> is changed to a new random value.</li>
    </ol>
</ol>

<h4 id="considerations">Considerations for business entity transfer</h4>
<ul>
    <li>When this API is endpoint is called, Chargebee blocks concurrent calls to incompatible <code>POST</code> operations.</li>
    <li>When a resource is transferred more than once, each transfer deprecates the previous active resource and creates a new active resource.</li>
    <li><code>payment_source</code> resources linked to the <code>customer</code> are immediately transferred to the destination business entity.</li>
    <li><code>subscription</code> resources linked to the <code>customer</code> are transferred automatically to the destination business entity as follows:</li>
    <ul>
        <li><code>active</code> subscription resources are transferred on their next renewal. </li>
        <li><code>paused</code> subscription resources are transferred when resumed.</li>
        <li><code>future</code> subscription resources are transferred on their <code><a href='subscriptions?prod_cat_ver=2#subscription_start_date'>start_date</a></code>.</li>
        <li><code>non_renewing</code> and <code>cancelled</code> subscription resources are not transferred and remain linked to the deprecated customer resource.</li>
    </ul>
    <li>Other resources linked to the customer, such as <code>invoice</code>, <code>quote</code>, <code>credit_note</code>, and <code>transaction</code>, remain linked to the deprecated customer resource.</li>
    <li>Deprecated <code>customer</code> and <code>subscription</code> resources are not returned in list APIs such as <a href='customers?prod_cat_ver=2#list_customers'>List customers</a> or <a href='subscriptions?prod_cat_ver=2#list_subscriptions'>List subscriptions</a>.</li>
</ul>

<div class='alert alert-info'>
    <strong>See also</strong>
    <ul>
        <li><a href='https://www.chargebee.com/docs/2.0/mbe-data-management-actions.html' target='_blank'>Permitted operations</a> on deprecated and active resources.</li>
        <li><a href='https://www.chargebee.com/docs/2.0/mbe-about-resources-and-managing-associated-workflow-processes.html' target='_blank'>Additional considerations for business entity transfer.</a></li>
    </ul>
</div>

<h4 id="example">Example</h4>
<p>The following example illustrates the transfer of a <code>customer</code> resource from a business entity (source) to another (destination). The example also shows how <code><a href='payment_sources?prod_cat_ver=2'>payment_source</a></code>, <code>subscription</code>, and <code>invoice</code> resources attached to the <code>customer</code> resource are affected.</p>

<h5>1. Initial state before the transfer</h5>

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

<docs-snippet>screenshot|transfer_resource_1.jpg</docs-snippet>

<h5>2. Invoking the API endpoint</h5>

<p>To transfer the <code>customer</code> resource to a new business entity <code>acme-eu</code>, you would call the endpoint as follows:</p>
<div class="cb-code-io" data-swiftype-index='false'>
    <code class="prettyprint lang-shell">

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"