1 business_entity Resource
- 1.1 Specifying business entity in API operations
- 1.2 API behavior based on business entity specified
- 1.3 Terminology
- 1.4 Sample business_entity
- 1.5 Attributes
2 Endpoints
- 2.1 Transfer a customer to another business entity
  - 2.1.1 Prerequisites
  - 2.1.2 Mechanics of business entity transfer
  - 2.1.3 Considerations for business entity transfer
  - 2.1.4 Example
  - 2.1.5 Sample request
  - 2.1.6 Sample response
  - 2.1.7 Input Parameters
  - 2.1.8 Returns
- 2.2 List business entity transfers
  - 2.2.1 Sample request
  - 2.2.2 Sample response
  - 2.2.3 Input parameters
  - 2.2.4 Filter parameters
  - 2.2.5 Returns

`business_entity` Resource

Early Access

Multiple Business Entities is in early access.

The business_entity resource represents a business unit or brand under your organization. Key resources in Chargebee Billing (such as customer, subscriptions, invoices, and transactions) along with the associated site configurations, fall under a business entity. Each Chargebee Billing site has one business entity by default. You may create multiple business entities in the following scenarios:

Multiple Business Units: You may be running your business under different regional units with different "invoice-from" addresses. This is usually done to manage taxation and bookkeeping. In such a case, you may create a business entity for each business unit.
Multiple Brands: You may have multiple brands within your business, such as those acquired via mergers and acquisitions. You may create a business entity for each brand.

Creating multiple business entities lets you separate configuration and data for your business units or brands so that you can manage their billing and revenue operations independently.

See also

More information on business entities and the configuration options available.

Specifying business entity in API operations

All API operations in Chargebee have site context. The "context" of an API operation is the subset of site data it has access to. An API operation can only read or write data within its context. By default, an API operation has "site context", which means it has access to the entire site's data. If your site has multiple business entities, you can specify the business entity context for an API call by passing a custom HTTP request header.

API behavior based on business entity specified

The table below explains how Chargebee responds to various API calls depending on whether the business entity ID is specified as part of the API call.

Note

Some of the terminology used here is defined in the next section.

	Operation/Type of operation	Behavior	Examples

	Operation/Type of operation	Behavior	Examples
1	Any operation that creates a `customer` resource.	If `business_entity_id` is provided, the `customer` resource is created and linked to it. If `business_entity_id` is not provided, the `customer` resource is created under the default business entity of the site.	Create a customer When Create a checkout for charge items and quick charges or Create checkout for a new subscription is called, providing a value for `customer[id]` that is not already present in the site. This creates a new `customer` resource.
2	Create a resource other than `customer`	If `business_entity_id` is provided, and it is the same as that linked to the target resource: the resource is created and linked to the business entity provided. If `business_entity_id` is provided, and it is not the same as that linked to the target resource, a `404 Not Found` response is sent because the resource cannot be found in the context of the business entity specified. If `business_entity_id` is not provided, the resource is created and linked to the business entity of the target resource.	Create a subscription: the target resource is a `customer`. Create a comment: the target resource is specified in the value provided for `entity_type`. Create an invoice for items and one-time charges: depending on the ID specified, the target resource is either a `customer` or a `subscription`.
3	Update/delete a resource	If `business_entity_id` is provided, and it is the same as that linked to the resource, the operation proceeds successfully. If `business_entity_id` is provided, and it is not the same as that linked to the resource, a `404 Not Found` response is sent because the resource cannot be found in the context of the business entity specified. If `business_entity_id` is not provided, the operation proceeds successfully.	Update a customer Update a subscription Update a card payment source
4	List resources	If `business_entity_id` is provided, then only those resources linked to the business entity are returned since the context of the operation is now restricted to the business entity specified. If `business_entity_id` is not provided, then all resources in the site are returned.	List customers List payment sources
5	Retrieve a resource	If `business_entity_id` is provided, and it is the same as that linked to the resource, the resource is retrieved successfully. If `business_entity_id` is provided, and it is not the same as that linked to the resource, a `404 Not Found` response is sent because the resource cannot be found in the context of the business entity specified. If `business_entity_id` is not provided, the resource is retrieved successfully.	Retrieve a customer Retrieve a comment

Terminology

This section defines some useful terms for describing how business entities work.

Linked business entity

Any resource is always associated with precisely one and only one business entity. We call it the linked business entity of the resource, or simply, the business entity of the resource.

Default business entity

When customer resource is created and no business entity is specified, it is linked to the business entity designated as the default business entity of the site. A site always has a default business entity. At first, it is the same as the first business entity of the site and can be changed once more business entities are created. Contact Support to change the default business entity.

Context of an operation

Any site has data in it. This includes all the various resources such as customers, subscriptions, invoices, comments, and so on. The "context" of an API operation is the subset of site data it has access to. An API operation can only read or write data within its context. By default, an API operation has "site context", which means it has access to the entire site's data. However, when a business entity is specified in an API operation, it has "business entity context", which means that the operation only has access to the data linked to the business entity.

Target resource

While creating an API resource other than a customer, you specify a target resource under which it should be created. For example:

While creating an invoice resource for a one-time charge, you must specify either the customer or the subscription resource to which it belongs. The customer or subscription resource, in this case, is the target resource of the invoice.
While creating a subscription, the target resource of a subscription resource is always a customer resource.
While creating a quote resource of type change_subscription, the target resource is a subscription resource.

Sample `business_entity`

{
    "id": "1",
    "name": "1",
    "status": "active",
    "deleted": false,
    "created_at": 1709892529,
    "updated_at": 1709892626,
    "resource_version": 1709892626000,
    "object": "business_entity"
}

Attributes

	Name	Description

	Name	Description
1	`id`	STRING MAX CHARS = 50 A unique and immutable identifier for the business entity. It is always autogenerated.
2	`name`	STRING MAX CHARS = 50 A human-friendly name for the business entity.
3	`status`	ENUM The status of business entity. Possible values: `active` The business entity is active and can be used. `inactive` he business entity is inactive and cannot be used.
4	`resource_version`	LONG Version number of this resource. The `resource_version` is updated with a new timestamp in milliseconds for every change made to the resource. This attribute will be present only if the resource has been updated after 2016-09-28.
5	`deleted`	BOOLEAN `default=false` Indicates that the business entity has been deleted.
6	`created_at`	UNIX TIME Timestamp for when this business entity was created.
7	`updated_at`	UNIX TIME The time period when the business entity was updated.

Endpoints

Transfer a customer to another business entity

POST /business_entity/transfers

Transfers one or more customer resources from one business entity to another.

The transfer is executed by creating a copy of the customer resource. The original resource is called the deprecated resource, while the new copy is called the current resource.

Prerequisites

Transfers must always be initiated for a current 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 current and deprecated resources are processed as follows:

For the current 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.
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 current resource and creates a new current 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 current customer resource. The payment_source resource is also deprecated and a new current payment_source resource is created and linked to the new customer resource. 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 current customer resource. This process mirrors the transfer of the customer resource, resulting in a new current subscription resource linked to the current customer resource and the business entity acme-eu.

Sample request

Sample response

Input Parameters

	Parameter	Description

	Parameter	Description
1	`active_resource_ids[0..n]`	required list of string The list of unique identifiers of the `customer` resources to be transferred. Each `id` must belong to a current `customer` resource.
2	`destination_business_entity_ids[0..n]`	required list of string The list of unique identifiers of the `business_entity` resources to which the corresponding `customer` resource must be transferred.
3	`reason_codes[0..n]`	required list of string The list of reasons for changing the business entity of the corresponding `customer` resources.

Returns

Attribute	Description

Attribute	Description
`business_entity_transfer`	always returned Resource object representing business_entity_transfer.

List business entity transfers

Returns a list of business_entity_transfer resources meeting all the conditions specified in the filter parameters below. By default, this list is sorted by created_at in descending order (latest first).

Sample request

Sample response

Input parameters

1

sort_by[<sort-order>] string filter
Sorts based on the specified attribute.
Supported attributes : created_at
Supported sort-orders : asc and desc

Example → sort_by[asc] = "created_at" (This will sort the result based on the 'created_at' attribute in ascending(earliest first) order.)

2

limit integer default = 10 min =1 max=100

The number of resources to be returned.

3

offset string maxchars=1000

Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset to the value of next_offset obtained in the previous iteration of the API call.

Filter parameters

1	`resource_type[<operator>]` string filter Filter `business_entity_transfer` resources based on `resource_type`. Supported operators : `is` Example: `resource_type[is] = "customer"`
2	`resource_id[<operator>]` string filter Filter `business_entity_transfer` resources based on `resource_id`. Supported operators : `is` Example: `resource_id[is] = "9bsvnHgsvmsI"`
3	`active_resource_id[<operator>]` string filter Filter `business_entity_transfer` resources based on `active_resource_id`. Supported operators : `is` Example: `active_resource_id[is] = "8gsnbYfsMLds"`
4	`created_at[<operator>]` unix time in seconds filter Filter `business_entity_transfer` resources based on `created_at`. Supported operators : `after`, `before`, `on`, `between` Example → `created_at[after] = "1702022464"`

Returns

	Attribute	Description

	Attribute	Description
1	`business_entity_transfer`	always returned Resource object representing business_entity_transfer.
2	`next_offset`	string max chars=1000 This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter `offset`.

business_entity Resource

business_entity Resource

Specifying business entity in API operations

API behavior based on business entity specified

Terminology

Linked business entity

Default business entity

Context of an operation

Target resource

Sample business_entity

Attributes

Endpoints

Transfer a customer to another business entity

Prerequisites

Mechanics of business entity transfer

Considerations for business entity transfer

Example

1. Initial state before the transfer

2. Invoking the API endpoint

3. Transfer of linked subscription resources

Sample request

Sample response

Input Parameters

Returns

List business entity transfers

Sample request

Sample response

Input parameters

Filter parameters

Returns

`business_entity` Resource

Sample `business_entity`

3. Transfer of linked `subscription` resources