# Entities

An entity represents a business unit that operates independently and can sell products to multiple countries. Each entity has its own Zuora environment in which the entity users can perform business operations independent of the other entities. In a multi-entity hierarchy, an entity can share certain business objects with the other entities. Users that are created in an entity can be granted access to the other entities with different roles and permissions. 

**Note**: Entities are available only if you have the <a href="https://knowledgecenter.zuora.com/Billing/Tenant_Management/Multi-entity" target="_blank">Multi-entity</a> feature enabled. If you want to have access to the Multi-entity feature, submit a request at <a href=“http://support.zuora.com/” target=“_blank”>Zuora Global Support</a>. 


## Multi-entity: Create an entity

 - [POST /v1/entities](https://developer.zuora.com/v1-api-reference/older-api/entities/post_entities.md): Creates an entity in a multi-entity hierarchy.

### User Access Permission
You must make the call as a global entity administrator.

### Notes
* We recommend that you assign only one administrator to manage the entity hierarchy, because an administrator of the global entity by default can only access to the entities that are created by themselves.

## Multi-entity: List entities

 - [GET /v1/entities](https://developer.zuora.com/v1-api-reference/older-api/entities/get_entities.md): Retrieves detailed information of certain entities in a multi-entity hierarchy.


You can retrieve:

 - Provisioned entities
  
 - Unprovisioned entities
  
 - Both provisioned and unprovisioned entities

### User Access Permission

You can make the call as any entity user.

## Multi-entity: Update an entity

 - [PUT /v1/entities/{id}](https://developer.zuora.com/v1-api-reference/older-api/entities/put_entities.md): Edits the following information about an unprovisioned entity:

 - Name
 
 - Display name
 
 - Locale
 
 - Timezone

### User Access Permission
You must make the call as a global entity administrator.

### Notes
* You are not allowed to edit the locale and time zone of the provisioned entities through the REST API.
* You are not allowed to edit the display name of the global entity.

## Multi-entity: Retrieve an entity

 - [GET /v1/entities/{id}](https://developer.zuora.com/v1-api-reference/older-api/entities/get_entitybyid.md): Retrieves detailed information about a specified entity.

### User Access Permission
You can make the call as any entity user.

## Multi-entity: Delete an entity

 - [DELETE /v1/entities/{id}](https://developer.zuora.com/v1-api-reference/older-api/entities/delete_entities.md): Removes an entity and its sub-entities from a multi-entity hierarchy. You can only remove unprovisioned entities. An error occurred when you remove a provisioned entity.

### User Access Permission
You must make the call as a global entity administrator.

## Multi-entity: Provision an entity

 - [PUT /v1/entities/{id}/provision](https://developer.zuora.com/v1-api-reference/older-api/entities/put_provisionentity.md): Provisions an entity. You can only provision an entity if its parent entity is provisioned.

### User Access Permission
You must make the call as a global entity administrator. 

### Notes
* Zuora does not allow you to remove a provisioned entity from the multi-entity hierarchy. So before you provision an entity, make sure that you put the entity in the correct place in the multi-entity hierarchy.