Skip to main content
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: To create and configure billing entities:
  1. Understand billing entity configuration
  2. Create billing entity
  3. Manage billing entities

​
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, use the Create billing entity API 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.
Important: 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 send a POST request to /v1/commerce/billing/billing-entities with all required request parameters. On successful billing entity creation, the PayPal server returns a billing entity ID. 
curl -X POST --location 'https://api-m.sandbox.paypal.com/v1/commerce/billing/billing-entities' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <ACCESS-TOKEN>' \
-d '{
    "name": "Acme Western Division",
    "code": "acme_west",
    "default_currency": "USD",
    "finalize_zero_amount_invoice": true,
    "address": {
        "line1": "789 Tech Boulevard",
        "line2": "Suite 1200",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94107",
        "country": "US"
    },
    "legal_name": "Acme Corporation Western LLC",
    "legal_number": "US87654321",
    "tax_identification_number": "87-6543210",
    "email": "west-billing@acmeinc.com",
    "timezone": "America/Los_Angeles"
}'

​
Request body parameters

Parameter nameDescription
name
Required, string		Name of the billing entity.
code
Required, string		Unique identifier to reference the billing entity in API calls.
default_currency
string		Three-letter ISO currency code for the billing entity’s primary currency. See supported currencies.
finalize_zero_amount_invoice
boolean		Determines whether to finalize invoices with zero amounts. Set to true to finalize zero-amount invoices.
address
object		Address information for the billing entity with fields: line1, line2, city, state, postal_code, country.
Note: This section documents only a subset of relevant request parameters. For the exhaustive list of request parameters, see API reference.

​
Response parameters

Note: This section documents only the response parameters relevant for the next step. For the exhaustive list of response fields, see API reference.
Parameter nameDescription and further action
code
string		Unique identifier for the billing entity. Use this code when registering customers to assign them to this billing entity.

​
3. Manage billing entities

To review a billing entity’s current configuration and available management options, call the Get billing entity details endpoint and review the billing entity properties.
Billing entity componentUpdatablePossible management optionsImpact on existing customers
NameYesUpdate billing entity nameNo impact - identification only
Billing configuration and tax codesYesUpdate billing entity details - currency, invoice settings, address information, and tax codesUpdates apply to new invoices and operations
Billing entity codeNoBilling entity cannot be modified - unique identifier remains permanentN/A - cannot be modified
⌘I