Skip to main content
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:

​
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:
ParameterAction
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"
}'
A successful call returns a 201 Created response. The response includes the following parameter:
ParameterDescriptionFurther 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 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