> ## 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.

# Manage billing entities

<div className="m-badge-page-wrapper">
  <Badge stroke color="orange" size="sm">Limited Release</Badge>
</div>

Billing entity management helps you update existing billing entities when your business requirements change. You can retrieve current billing entities and modify entity configurations, including assigning tax codes. This ensures proper billing context for different business divisions and jurisdictions.

## List billing entities

Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token" target="_blank" rel="noopener noreferrer">valid access token</a> and make a GET call to the `/v1/commerce/billing/billing-entities` endpoint.

<CodeGroup>
  ```shell lines title="Sample request" theme={null}
  curl -X GET 'https://api-m.sandbox.paypal.com/v1/commerce/billing/billing-entities' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>'
  ```

  ```json lines expandable title="Sample response" theme={null}
  [
      {
          "id": "b8e2a656-04eb-441c-a6b2-bfab9e2a0f7c",
          "code": "acme_inc",
          "name": "Acme Inc",
          "default_currency": "USD",
          "finalize_zero_amount_invoice": true,
          "is_default": true,
          "address": {
              "line1": "123 Business Ave",
              "city": "San Francisco",
              "state": "CA",
              "country": "US",
              "postal_code": "94107"
          },
          "legal_name": "Acme Corporation Inc.",
          "legal_number": "US123456789",
          "email": "billing@acmeinc.com",
          "timezone": "America/Los_Angeles",
          "created_at": "2023-01-15T00:00:00Z",
          "updated_at": "2023-01-15T00:00:00Z"
      },
      {
          "id": "c9f3b767-15fc-552d-b7c3-cfab0f3b1f8d",
          "code": "acme_eu",
          "name": "Acme Europe",
          "default_currency": "EUR",
          "finalize_zero_amount_invoice": true,
          "is_default": false,
          "address": {
              "line1": "456 Business Blvd",
              "city": "Paris",
              "country": "FR",
              "postal_code": "75001"
          },
          "legal_name": "Acme Corporation SARL",
          "legal_number": "FR987654321",
          "email": "europe-billing@acmeinc.com",
          "timezone": "Europe/Paris",
          "created_at": "2023-01-15T00:00:00Z",
          "updated_at": "2023-01-15T00:00:00Z"
      }
  ]
  ```
</CodeGroup>

A successful call returns a `200 OK` response with an array of billing entities.

## Update billing entity details

Use a <a href="/developer/how-to/api/get-started#2-get-an-access-token" target="_blank" rel="noopener noreferrer">valid access token</a> and make a PUT call to the `/v1/commerce/billing/billing-entities/{billing_entity_code}` endpoint with the modified request parameters such as name, currency, address, legal information, contact details, and tax codes.

**Path parameter**: `billing_entity_code` is the `code` you provided when you <a href="/limited-release/usage-based-billing/set-up-billing-process/create-billing-entities" target="_blank" rel="noopener noreferrer">created the billing entity</a>.

<Note>
  You can also assign existing tax codes to billing entities. Include the `tax_codes` parameter that reference the <a href="/limited-release/usage-based-billing/set-up-billing-process/create-taxes" target="_blank" rel="noopener noreferrer">created taxes</a>.
</Note>

For information on all parameters, see <a href="/reference/api/rest/billing-entities/update-a-billing-entity-by-code" target="_blank" rel="noopener noreferrer">API reference</a>.

<CodeGroup>
  ```shell lines expandable title="Sample request" theme={null}
  curl -X PUT 'https://api-m.sandbox.paypal.com/v1/commerce/billing/billing-entities/acme_inc' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS-TOKEN>' \
  -d '{
      "name": "Acme Inc (Updated)",
      "default_currency": "USD",
      "finalize_zero_amount_invoice": true,
      "address": {
          "line1": "123 Business Ave, Suite 500",
          "line2": "Floor 5",
          "city": "San Francisco",
          "state": "CA",
          "country": "US",
          "postal_code": "94107"
      },
      "legal_name": "Acme Corporation Inc. LLC",
      "legal_number": "US987654321",
      "tax_identification_number": "987-65-4321",
      "email": "billing-updated@acmeinc.com",
      "timezone": "America/Los_Angeles",
      "tax_codes": [
          "us_ca_sales_tax_8_25",
          "us_sf_city_tax_1_25"
      ]
  }'
  ```

  ```json lines expandable title="Sample response" theme={null}
  {
      "id": "b8e2a656-04eb-441c-a6b2-bfab9e2a0f7c",
      "code": "acme_inc",
      "name": "Acme Inc (Updated)",
      "default_currency": "USD",
      "finalize_zero_amount_invoice": true,
      "is_default": true,
      "address": {
          "line1": "123 Business Ave, Suite 500",
          "line2": "Floor 5",
          "city": "San Francisco",
          "state": "CA",
          "country": "US",
          "postal_code": "94107"
      },
      "legal_name": "Acme Corporation Inc. LLC",
      "legal_number": "US987654321",
      "tax_identification_number": "987-65-4321",
      "email": "billing-updated@acmeinc.com",
      "timezone": "America/Los_Angeles",
      "created_at": "2023-01-15T00:00:00Z",
      "updated_at": "2023-01-16T05:30:00Z",
      "taxes": [
          {
              "id": "d4e3c878-16fd-663d-a8c3-egcb1f5d4h0e",
              "name": "California State Sales Tax",
              "code": "us_ca_sales_tax_8_25",
              "description": "California State Sales Tax",
              "rate": "8.25",
              "created_at": "2023-01-15T00:00:00Z"
          },
          {
              "id": "e5f4d989-27ge-774f-d9e5-ehbc1g5d3h0e",
              "name": "San Francisco City Tax", 
              "code": "us_sf_city_tax_1_25",
              "description": "San Francisco City Tax",
              "rate": "1.25",
              "created_at": "2023-01-16T05:30:00Z"
          }
      ]
  }
  ```
</CodeGroup>

A successful call returns a `200 OK` response with the updated billing entity information.