Business entities

API Version

Product Catalog

Library

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. Context restrictions cannot be assigned to API keys. However, 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 defined in the next section.

Operation/Type of operation	Behavior	Examples
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.
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`.
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
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
Retreive 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.

Example

Consider the List customers API. When you call the API without specifying a business entity, its context is that of the site and therefore returns customer resources for the entire site. However, when you specify a business entity, the context is only that of the business entity, and therefore the customer resources of only the selected business entity are returned.

Let's look at the Create checkout for a new subscription API. Say you're calling this API and providing the customer[id] parameter. When no business entity is specified, the operation has site context and therefore looks up the ID among all the customer resources in the site. However, when a business entity is provided, the operation has business entity context and looks up the ID only among the customers linked to that 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 [ JSON ]

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

Model Class

id

string, max chars=50
A unique and immutable identifier for the business entity. It is always autogenerated.

name

string, max chars=100
A human-friendly name for the business entity.

status

enumerated string
Current status of the business entity.

Possible values are

activeThe business entity is active and can be used.inactiveThe business entity is inactive and cannot be used.

deleted

boolean, default=false
Indicates that the business entity has been deleted.

created_at

timestamp(UTC) in seconds
Timestamp when this business entity was created.

resource_version

optional, 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.

updated_at

optional, timestamp(UTC) in seconds
The time period when the business entity was updated.

Important

This API will not work if you have specified a business entity in the custom HTTP header.

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 deprecated, while the new copy becomes the active resource.

More details

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:

For the active resource:

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

For the deprecated resource:

For customer and subscription resources, the value of active_id is set to match the resource id.
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.

See also

Permitted operations on deprecated and active resources.
Additional considerations for business entity transfer.

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.

Sample Codes

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"

copy

Click to Copy

Transfer customer to another business entity

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"

Sample Result [ 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"
            }
        },
        {..}
    ]
}

Method

active_resource_ids[]

required, list of string

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, list of string

The list of unique identifiers of the business_entity resources to which the corresponding customer resource must be transferred.

reason_codes[]

required, list of string
The list of reasons for changing the business entity of the corresponding customer resources.

business_entity_transfer

always returned
business_entity_transfer encapsulates the details of the movement of a resource (such as customer and subscription) from one business_entity to another.

Related Endpoints

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).

Tip

To retrieve a history of all the business entity transfers for a resource, pass the filter parameters active_resource_id[is] and resource_type[].

Sample Codes

curl  https://{site}.chargebee.com/api/v2/business_entities/transfers \
     -G  \
     -u {site_api_key}:\
     --data-urlencode resource_type="customer" \
     --data-urlencode active_resource_id="Customer-1"

copy

Click to Copy

curl  https://{site}.chargebee.com/api/v2/business_entities/transfers \
     -G  \
     -u {site_api_key}:\
     --data-urlencode resource_type="customer" \
     --data-urlencode active_resource_id="Customer-1"

Sample Result [ JSON ]

{
    "list": [
        {
            "business_entity_transfer": {
                "id": "__dev__263BEVU6h5FoKu",
                "resource_type": "customer",
                "reason_code": "Correction",
                "created_at": 1608209939,
                "object": "business_entity_transfer",
                "destination_business_entity_id": "Entity-4",
                "source_business_entity_id": "Entity-3",
                "resource_id": "__dev__263BEVU6h5FlTp",
                "active_resource_id": "__dev__263BEVU6h5DnYj"
            }
        },
        {..}
    ]
}

Method

limit[]

optional, integer, default=10, min=1, max=100
The number of resources to be returned.

offset[]

optional, string, max chars=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.

sort_by

optional, string filter
Sorts based on the specified attribute.
Supported attributes : created_at
Supported sort-orders :

Example →
This will sort the result based on the 'created_at' attribute in ascending(earliest first) order.

Filter Params

For operator usages, see the Pagination and Filtering section.

resource_type

optional, string filter

Filter business_entity_transfer resources based on resource_type.

Tip

Use this filter along with active_resource_id[is] to retrieve the history of all the business entity transfers for a resource.

Supported operators :

Example → customer

resource_id

optional, string filter
Filter business_entity_transfer resources based on resource_id.
Supported operators :

Example → 9bsvnHgsvmsI

active_resource_id

optional, string filter

Filter business_entity_transfer resources based on active_resource_id.

Tip

Use this filter along with resource_type[] to retrieve the history of all the business entity transfers for a resource.

Supported operators :

Example → 8gsnbYfsMLds

created_at

optional, timestamp(UTC) in seconds filter
To filter based on Created At.
Supported operators :

Example → 1702022464

business_entity_transfer

always returned
business_entity_transfer encapsulates the details of the movement of a resource (such as customer and subscription) from one business_entity to another.

Related Endpoints

next_offset

optional, 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`.

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 [ JSON ]

API Index URL GET

Model Class

Business entity attributes

Consent Fields for Business entity

Custom Fields for Business entity

Transfer a customer to another business entity ¶

More details

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

Notes

Sample Result [ JSON ]

URL Format POST

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

List business entity transfers ¶

Notes

Sample Result [ JSON ]

URL Format GET

Method

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Sample admin console URL

3. Transfer of linked `subscription` resources