Settings
API Version
Product Catalog
Library

Business entities

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.

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.

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 words used here are defined in the Terminology section.

Operation/Type of operationBehaviorExamples
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 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.
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.
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.
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.

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. Please choose the first business entity details carefully, as it can't be changed later, and this will be your default entity when no business entity is specified.

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:

Sample business entity [ JSON ]

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

API Index URL

https://{site}.chargebee.com/api/v2/business_entities

Model Class

 

      Business entity attributes
      
 
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.
 
 Show all values[+]
 
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. 
 
 
  
id id
 

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

          string, max chars=100
 A human-friendly name for the business entity. 
 
status 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.
 
 Show all values[+]
deleted deleted
 

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

          timestamp(UTC) in seconds
 Timestamp when this business entity was created. 
 
resource_version 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 updated_at
 

          optional, timestamp(UTC) in seconds
 The time period when the business entity was updated. 
 
 
 
Consent Fields for Business entity
 
 
Custom Fields for Business entity
 
 

      Transfer a customer to another business entity
      
 
Idempotency Supported
 
 
  Try in API Explorer
   
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.
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:
    


    • 

  • 

    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. 

    2. business_entity_id is set to destination_business_entity_id parameter.
      3. 

    

    2. 

  2. 

    For the deprecated resource:
    

      

    1. For customer and subscription resources, the value of active_id is set to match the resource id.
      2. 

    2. The value of id is changed to a new random value.
      3. 

    

    3. 

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
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 Request
      
 

  Try in API Explorer

 
 
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
 
 
 
200:
 
OK
 
STATUS
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "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
    
 
Method
 
 
Input Parameters
 
  
 
active_resource_ids[[0..n]][0..n]
 

      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[[0..n]][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.
 
 
reason_codes[[0..n]][0..n]
 

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

      always returned 
 Resource object representing business_entity_transfer
 
Sample admin console URL
 

      https://{site}.chargebee.com/admin-console/business_entities/123x
    

      List business entity transfers
      
  
 
  Try in API Explorer
   
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 Request
      
 

  Try in API Explorer

 
 
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
 
 
200:
 
OK
 
STATUS
 

    Sample Response [ JSON ]
 
Show more...
 
{
    "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"
            }
        },
        {..}
    ]
}
 

      URL Format
      GET
 

      https://{site}.chargebee.com/api/v2/business_entities/transfers
    
 
Method
 
 
Input Parameters
 
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[<sort-order>]
 
 optional, string filter

    Sorts based on the specified attribute.
    
Supported attributes : created_at 
Supported sort-orders : asc, desc 

Example → sort_by[asc] = "created_at"

    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[<operator>]
  
 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. 
 
 Possible values are :  
Supported operators : is
    

Example → resource_type[is] = "customer"
 
 
 
resource_type[is][operator]
 
 optional, string, min chars=1 filter
  Possible values are :  
Supported operators : 
    

Example → 
resource_id[<operator>]
  
 optional, string filter
 Filter business_entity_transfer resources based on resource_id. Possible values are :  
Supported operators : is
    

Example → resource_id[is] = "9bsvnHgsvmsI"
 
 
 
resource_id[is][operator]
 
 optional, string, min chars=1 filter
  Possible values are :  
Supported operators : 
    

Example → 
active_resource_id[<operator>]
  
 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. 
 
 Possible values are :  
Supported operators : is
    

Example → active_resource_id[is] = "8gsnbYfsMLds"
 
 
 
active_resource_id[is][operator]
 
 optional, string, min chars=1 filter
  Possible values are :  
Supported operators : 
    

Example → 
created_at[<operator>]
  
 optional, timestamp(UTC) in seconds filter
 To filter based on  Created At. Possible values are :  
Supported operators : after, before, on, between
    

Example → created_at[after] = "1702022464"
 
 
 
created_at[after][operator]
 
 optional, timestamp(UTC) in seconds filter
  Possible values are :  
Supported operators : 
    

Example → 
 
created_at[before][operator]
 
 optional, timestamp(UTC) in seconds filter
  Possible values are :  
Supported operators : 
    

Example → 
 
created_at[on][operator]
 
 optional, timestamp(UTC) in seconds filter
  Possible values are :  
Supported operators : 
    

Example → 
 
created_at[between][operator]
 
 optional, string filter
  Possible values are :  
Supported operators : 
    

Example → 
 
Returns
 
business_entity_transfer  business_entity_transfer
 

      always returned 
 Resource object representing business_entity_transfer
next_offset  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`.
 
Sample admin console URL
 

      https://{site}.chargebee.com/admin-console/business_entities/123x