# Business entities

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


The `business_entity` resource represents a business unit or brand under your organization. Key resources in Chargebee Billing (such as `[customer](/docs/api/customers)`, `[subscriptions](/docs/api/subscriptions)`, `[invoices](/docs/api/invoices)`, and `[transactions](/docs/api/transactions)`) along with the associated site configurations, fall under a [business entity](https://www.chargebee.com/docs/2.0/mbe.html). Each Chargebee Billing [site](https://www.chargebee.com/docs/2.0/sites-intro.html) 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](https://www.chargebee.com/docs/2.0/mbe.html) on business entities and the configuration options available.

Specifying business entity in API operations

All API operations in Chargebee have site [context](/docs/api/business_entities). Context restrictions cannot be assigned to [API keys](https://www.chargebee.com/docs/2.0/api_keys.html). However, if your site has multiple business entities, you can specify the business entity [context](/docs/api/business_entities) for an API call by passing a [custom HTTP request header](/docs/api/advanced-features).

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 words used here are defined in the [Terminology section](/docs/api/business_entities).

**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](/docs/api/business_entities) of the site.

-   [Create a customer](/docs/api/customers/create-a-customer)
-   When [Create a checkout for charge items and quick charge](/docs/api/hosted_pages/checkout-charge-items-and-one-time-charges)s or [Create checkout for a new subscription](/docs/api/hosted_pages/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](/docs/api/business_entities) to the [target resource](/docs/api/business_entities): 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](/docs/api/business_entities) 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](/docs/api/subscriptions/create-subscription-for-items): the target resource is a `customer`.
-   [Create a comment](/docs/api/comments/create-a-comment): the target resource is specified in the value provided for `entity_type`.
-   [Create an invoice for items and one-time charges](/docs/api/invoices/create-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](/docs/api/business_entities) to the resource, the operation proceeds successfully.
-   If `business_entity_id` **is provided**, and it is not the same as that [linked](/docs/api/business_entities) to the resource, a `404 Not Found` response is sent because the resource cannot be found in the [context](/docs/api/business_entities) of the business entity specified.
-   If `business_entity_id` **is not provided**, the operation proceeds successfully.

-   [Update a customer](/docs/api/customers/update-a-customer)
-   [Update a subscription](/docs/api/subscriptions/update-subscription-for-items)
-   [Update a card payment source](/docs/api/payment_sources/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](/docs/api/business_entities) 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](/docs/api/customers/list-customers)
-   [List payment sources](/docs/api/payment_sources/list-payment-sources)

Retreive a resource

-   If `business_entity_id` **is provided**, and it is the same as that [linked](/docs/api/business_entities) to the resource, the resource is retrieved successfully.
-   If `business_entity_id` **is provided**, and it is not the same as that [linked](/docs/api/business_entities) to the resource, a `404 Not Found` response is sent because the resource cannot be found in the [context](/docs/api/business_entities) of the business entity specified.
-   If `business_entity_id` **is not provided**, the resource is retrieved successfully.

-   [Retrieve a customer](/docs/api/customers/retrieve-a-customer)
-   [Retrieve a comment](/docs/api/comments/retrieve-a-comment)

Terminology

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

#### Linked business entity[](#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[](#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[](#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](/docs/api/business_entities) 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](/docs/api/customers/list-customers). 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](/docs/api/hosted_pages/create-checkout-for-a-new-subscription). 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[](#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](/docs/api/invoices/create-invoice-for-items-and-one-time-charges), 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`](/docs/api/subscriptions/create-subscription-for-items), the target resource of a `subscription` resource is always a `customer` resource.
-   While [creating a `quote` resource of `type` `change_subscription`](/docs/api/quotes/create-a-quote-for-update-subscription-items), the target resource is a `subscription` resource.

## Sample Business entity

```json
{
  "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"
  }
}
```

## Business entities attributes

## Input Parameters

- `id` (required, string, max chars=50)
  A unique and immutable identifier for the business entity. It is always autogenerated.

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

- `status` (required, enumerated string)
  Current status of the business entity.
  Possible enum values:
    - `active`
      The business entity is active and can be used.
    - `inactive`
      The business entity is inactive and cannot be used.

- `deleted` (required, boolean, default=false)
  Indicates that the business entity has been deleted.

- `created_at` (required, 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.