# Transfer a customer to another business entity

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


[Idempotency Supported](/docs/api/idempotency)

**Important** This API will not work if you have [specified a business entity](/docs/api/advanced-features#mbe-header-main) in the custom HTTP header.

Transfers one or more `[customer](/docs/api/customers)` resources from one business entity to another.

The transfer is executed by creating a copy of the `customer` resource. The original resource is deprecated, while the new copy becomes the active resource.

More details

#### Prerequisites[](#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](/docs/api/customers/customer-object#relationship)`.
        
    -   `subscription` resource with
        
        -   `status` `in_trial` or
        -   advance invoice schedules. (`[subscription.has_scheduled_advance_invoices](/docs/api/subscriptions/subscription-object#has_scheduled_advance_invoices)` as `true`.)
    -   `[invoice](/docs/api/invoices)` resource with `status` as `pending`. ([Close pending invoices](/docs/api/invoices/close-a-pending-invoice) before invoking this API.)
        
    -   `invoice` resources that are advance invoices. (`[invoice.has_advance_charges](/docs/api/invoices/invoice-object#has_advance_charges)` as `true`.)
        
    -   `[quote](/docs/api/quotes)` resources with `status` as `open` or `accepted`.
        
    -   `[transaction](/docs/api/transactions)` resource with:
        
        -   `status` as `in_progress` or
        -   `status` as `success`, `type` as `authorization`, and a non-zero `amount_capturable`.
    -   Non-zero `[unbilled_charges](/docs/api/customers/customer-object#unbilled_charges)`. ([Invoice unbilled charges](/docs/api/unbilled_charges/create-an-invoice-for-unbilled-charges) before invoking this API.)
        
    -   Non-zero `[refundable_credits](/docs/api/customers/customer-object#refundable_credits)`. ([Apply credits](/docs/api/invoices/apply-credits-for-an-invoice) to unpaid invoices before invoking this API.)
        
-   The `customer` resource must not be a [gifter](/docs/api/gifts/gift-object#gifter) of a gift subscription with `[status](/docs/api/gifts/gift-object#status)` `scheduled` or `unclaimed`.
    

#### Mechanics of business entity transfer[](#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[](#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](/docs/api/subscriptions/subscription-object#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](/docs/api/customers/list-customers) or [List subscriptions](/docs/api/subscriptions/list-subscriptions).
    

**See also**

-   [Permitted operations](https://www.chargebee.com/docs/2.0/mbe-data-management-actions.html) on deprecated and active resources.
-   [Additional considerations for business entity transfer.](https://www.chargebee.com/docs/2.0/mbe-about-resources-and-managing-associated-workflow-processes.html)

#### Example[](#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](/docs/api/payment_sources)`, `subscription`, and `invoice` resources attached to the `customer` resource are affected.

##### 1\. Initial state before the transfer[](#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` .

![Transfer resource 1](/images/transfer_resource_1.jpg)

##### 2\. Invoking the API endpoint[](#2-invoking-the-api-endpoint)

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

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.

![Transfer resource 2](/images/transfer_resource_2.jpg)

##### 3\. Transfer of linked `subscription` resources[](#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`.

![Transfer resource 3](/images/transfer_resource_3.jpg)

## Sample Request

#### cURL

```bash
curl  https://{site}.chargebee.com/api/v2/business_entities/transfers \
     -u {site_api_key}:\
     -d "active_resource_ids[0]"="Customer-1" \
     -d "active_resource_ids[1]"="Customer-2" \
     -d "destination_business_entity_ids[0]"="Entity-2" \
     -d "destination_business_entity_ids[1]"="Entity-2" \
     -d "reason_codes[0]"="Correction" \
     -d "reason_codes[1]"="Correction"
```

#### .NET

```dotnet
using ChargeBee.Api;
using ChargeBee.Models;

ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = BusinessEntity.CreateTransfers()
		.ActiveResourceIds(new List<string>{"Customer-1", "Customer-2"})
		.DestinationBusinessEntityIds(new List<string>{"Entity-2", "Entity-2"})
		.ReasonCodes(new List<string>{"Correction", "Correction"})
		.Request();

BusinessEntityTransfer businessEntityTransfer = result.BusinessEntityTransfer;
```

#### Go

```go
package main
import (
    "fmt"
    "github.com/chargebee/chargebee-go/v3"
    businessentityAction "github.com/chargebee/chargebee-go/v3/actions/businessentity"
    "github.com/chargebee/chargebee-go/v3/models/businessentity"
)
func main() {
    chargebee.Configure("{site_api_key}","{site}");
    res,err := businessentityAction.CreateTransfers(&businessentity.CreateTransfersRequestParams{
        ActiveResourceIds : []string{"Customer-1", "Customer-2"},
        DestinationBusinessEntityIds : []string{"Entity-2", "Entity-2"},
        ReasonCodes : []string{"Correction", "Correction"},
    }).Request()
    if err != nil {
        fmt.Println(err)
    } else {
        BusinessEntityTransfer := res.BusinessEntityTransfer
    }
}
```

#### Go

```go
package main

import (
  "fmt"
  "github.com/chargebee/chargebee-go/v4"
)

func main() {
  config := &chargebee.ClientConfig{
    SiteName: "{site}",
    ApiKey: "{site_api_key}",
  }    
  client := chargebee.NewClient(config)
  req := &chargebee.BusinessEntityCreateTransfersRequest{
    ActiveResourceIds : []string{"Customer-1", "Customer-2"},
    DestinationBusinessEntityIds : []string{"Entity-2", "Entity-2"},
    ReasonCodes : []string{"Correction", "Correction"},
}
  res, err := client.BusinessEntity.CreateTransfers(req)
      if err != nil {
        fmt.Println(err)
    } else {
        BusinessEntityTransfer := res.BusinessEntityTransfer
    }
}
```

#### Java

```java
import com.chargebee.*;
import com.chargebee.ListResult;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;
import java.io.IOException;

public class Sample {

    public static void main(String args[]) throws IOException, Exception {
        Environment.configure("{site}", "{site_api_key}");
        Result result = BusinessEntity.createTransfers()
            .activeResourceIds("Customer-2")
            .destinationBusinessEntityIds("Entity-2")
            .reasonCodes("Correction")
            .request();

        BusinessEntityTransfer businessEntityTransfer = result.businessEntityTransfer();
    }
}
```

#### Java

```java
import com.chargebee.v4.client.ChargebeeClient;
import com.chargebee.v4.models.businessEntity.params.BusinessEntityCreateTransfersParams;
import com.chargebee.v4.models.businessEntity.responses.BusinessEntityCreateTransfersResponse;
import com.chargebee.v4.models.businessEntityTransfer.BusinessEntityTransfer;
import java.util.List;

public class BusinessEntityCreateTransfers {

    public static void main(String[] args) {
        ChargebeeClient client = ChargebeeClient.builder()
            .apiKey("{site_api_key}")
            .siteName("{site}")
            .build();

        BusinessEntityCreateTransfersParams params = BusinessEntityCreateTransfersParams.builder()
            .activeResourceIds(List.of("Customer-2"))
            .destinationBusinessEntityIds(List.of("Entity-2"))
            .reasonCodes(List.of("Correction"))
            .build();

        BusinessEntityCreateTransfersResponse response = client.businessEntities().createTransfers(params);

        BusinessEntityTransfer businessEntityTransfer = response.getBusinessEntityTransfer();
    }
}
```

#### Node.js

```node
import Chargebee from "chargebee";

const chargebee = new Chargebee({
    site: "{site}",
    apiKey: "{site_api_key}",
});

try {
    const result = await chargebee.businessEntity.createTransfers({
        active_resource_ids: ["Customer-1", "Customer-2"],
        destination_business_entity_ids: ["Entity-2", "Entity-2"],
        reason_codes: ["Correction", "Correction"]
    });

    console.log(result);
    const businessEntityTransfer = result.business_entity_transfer;
} catch (err) {
    console.log(err);
}
```

#### PHP

```php
<?php

require __DIR__ . '/vendor/autoload.php';

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
    "site" => "{site}",
    "apiKey" => "{site_api_key}",
]);
$result = $chargebee->businessEntity()->createTransfers([
    "active_resource_ids" => ["Customer-1", "Customer-2"],
    "destination_business_entity_ids" => ["Entity-2", "Entity-2"],
    "reason_codes" => ["Correction", "Correction"]
]);
$businessEntityTransfer = $result->business_entity_transfer;
```

#### Python

```python
from chargebee import Chargebee

cb_client = Chargebee(api_key="{site_api_key}", site="{site}")
response = cb_client.BusinessEntity.create_transfers(
    cb_client.BusinessEntity.CreateTransfersParams(
        active_resource_ids=["Customer-1", "Customer-2"],
        destination_business_entity_ids=["Entity-2", "Entity-2"],
        reason_codes=["Correction", "Correction"]
    )
)
business_entity_transfer = response.business_entity_transfer
```

#### Ruby

```ruby
require 'chargebee'

ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")

result = ChargeBee::BusinessEntity.create_transfers({
  :active_resource_ids => ["Customer-1", "Customer-2"],
  :destination_business_entity_ids => ["Entity-2", "Entity-2"],
  :reason_codes => ["Correction", "Correction"]
})

business_entity_transfer = result.business_entity_transfer
```

## Sample Response

```json
{
  "list": [
    {
      "business_entity_transfer": {
        "id": "__dev__263BEVU6h5FoKt",
        "resource_type": "customer",
        "reason_code": "Correction",
        "created_at": 1608209339,
        "object": "business_entity_transfer",
        "destination_business_entity_id": "Entity-2",
        "source_business_entity_id": "Entity-1",
        "resource_id": "__dev__263BEVU6h5FlTn",
        "active_resource_id": "__dev__263BEVU6h5DnYj"
      }
    },
    {..}
  ]
}
```

## URL Format

**POST** https://[site].chargebee.com/api/v2/business_entities/transfers

## Input Parameters

- `active_resource_ids` (required, string, max chars=50)
  The list of unique identifiers of the `customer` resources to be transferred. Each `id` must belong to an active `customer` resource.
  
  **Note** If a `customer` resource was deprecated because it was moved previously, you cannot move it again. Instead, move the active version of the resource. Do this by passing the `active_id` of the deprecated resource.

- `destination_business_entity_ids` (required, string, max chars=50)
  The list of unique identifiers of the `business_entity` resources to which the corresponding `customer` resource must be transferred.

- `reason_codes` (required, string, max chars=50)
  The list of [reasons](/docs/api/business_entity_transfers/business_entity_transfer-object#reason_code) for changing the business entity of the corresponding `customer` resources.

## Returns

- `business_entity_transfer` (Business entity transfer object)
  Resource object representing `business_entity_transfer` .