> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paypal.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Create billing entities
Limited Release
A billing entity represents a distinct billing configuration within your business that handles billing operations for specific regions, divisions, or legal entities.
Billing entities connect the following:
* Customers through billing entity code assignment.
* Tax codes for compliance requirements in different jurisdictions.
* Invoices and credit notes that inherit billing entity context.
## 1. Understand billing entity configuration
Before you create a billing entity, decide on these configuration details based on your business structure and compliance requirements. Then, you can make a POST call to the Create billing entity endpoint to send the information to PayPal.
**Basic identification**
* **Name**: Set a descriptive name that identifies the billing entity.
* **Code**: Create a unique identifier to reference the billing entity in API calls.
**Billing configuration**
* **Default currency**: Set the primary currency for this billing entity's operations.
* **Invoice settings**: Configure whether to finalize invoices with zero amounts.
* **Address information**: Provide the billing entity's legal or operational address for compliance and tax purposes.
**Tax codes**: Associate relevant tax configurations with the billing entity. See Update billing entity details.
Ensure you create the billing entity before you assign the tax codes. You cannot assign tax codes during the initial billing entity creation process.
## 2. Create billing entity
Use a valid access token and make a POST call to the `/v1/commerce/billing/billing-entities` endpoint. Include the following parameters:
| Parameter | Action |
| -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`
Required, string | Provide a descriptive name that identifies the billing entity. |
| `code`
Required, string | Set a unique code to identify this billing entity. |
| `default_currency`
string | Set the three-letter ISO currency code for the billing entity's primary currency (for example, `USD`). See supported currencies. |
| `finalize_zero_amount_invoice`
boolean | Set to `true` to finalize invoices with zero amounts or `false` to skip them. |
| `address`
object | Provide the billing entity's address with fields: `line1`, `line2`, `city`, `state`, `postal_code`, `country`. |
For information on all parameters, see API reference.
```shell lines title="Sample request" theme={null}
curl -X POST -L 'https://api-m.sandbox.paypal.com/v1/commerce/billing/billing-entities' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ' \
-d '{
"code": "acme_west",
"name": "Acme Western Division",
"default_currency": "USD",
"finalize_zero_amount_invoice": true,
"address": {
"line1": "789 Tech Boulevard",
"line2": "Suite 1200",
"city": "San Francisco",
"state": "CA",
"country": "US",
"postal_code": "94107"
},
"legal_name": "Acme Corporation Western LLC",
"legal_number": "US87654321",
"email": "west-billing@acmeinc.com",
"timezone": "America/Los_Angeles"
}'
```
```json lines title="Sample response" theme={null}
{
"id": "e7f4c956-23fc-663d-a8c3-egcb1f5d4h0e",
"code": "acme_west",
"name": "Acme Western Division",
"default_currency": "USD",
"finalize_zero_amount_invoice": true,
"is_default": false,
"address": {
"line1": "789 Tech Boulevard",
"line2": "Suite 1200",
"city": "San Francisco",
"state": "CA",
"country": "US",
"postal_code": "94107"
},
"legal_name": "Acme Corporation Western LLC",
"legal_number": "US87654321",
"email": "west-billing@acmeinc.com",
"timezone": "America/Los_Angeles",
"created_at": "2023-01-15T00:00:00Z",
"updated_at": "2023-01-15T00:00:00Z"
}
```
A successful call returns a `201 Created` response. The response includes the following parameter:
| Parameter | Description | Further action |
| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `code`
string | Unique code for the billing entity. | Use this `code` when registering customers or managing the billing entity. |
For information on all parameters, see API reference.
## 3. Manage billing entities
To review a billing entity's current configuration and available management options, make a GET call to the /v1/commerce/billing/billing-entities/{code} endpoint and review the billing entity properties.
| Billing entity component | Updatable | Possible management options | Impact on existing customers |
| --------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| **Name** | Yes | Update billing entity name | No impact - identification only |
| **Billing configuration and tax codes** | Yes | Update billing entity details - currency, invoice settings, address information, and tax codes | Updates apply to new invoices and operations |
| **Billing entity code** | No | Billing entity cannot be modified - unique identifier remains permanent | N/A - cannot be modified |