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.

curl -X POST -L 'https://api-m.sandbox.paypal.com/v1/commerce/billing/billing-entities' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS-TOKEN>' \
-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"
}'

{
    "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/ 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

​1. Understand billing entity configuration

​2. Create billing entity

​3. Manage billing entities

1. Understand billing entity configuration

2. Create billing entity

3. Manage billing entities