> ## 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 taxes
Limited Release
A tax configuration defines a reusable tax rate that the system automatically applies to calculate taxes.
You can apply taxes to:
* Billing entities for regional tax requirements.
* Customers for customer-specific tax rates.
* Pricing plans and their components (base fees, usage charges, minimum commitments).
* Subscriptions through plan overrides.
## 1. Understand tax configuration
Before you create a tax, decide on these configuration details based on your business requirements and regional regulations. Then, you can make a POST call to the Create tax endpoint to send the information to PayPal. It is your responsibility to ensure the accuracy of the tax calculation and to remit such taxes to the appropriate tax authorities.
**Basic identification**
* **Name**: Set a descriptive name that identifies the tax.
* **Code**: Create a unique identifier to reference the tax in API calls.
* **Description**: Add a detailed description for the tax configuration.
**Tax calculation**
**Rate**: Specify the percentage rate for the tax.
After you create a tax, you cannot change its code. You can only update the name, rate, and description. For more information, see Update tax details.
## 2. Create tax
Use a valid access token and make a POST call to the `/v1/commerce/billing/taxes` endpoint. Include the following parameters:
| Parameter | Action |
| -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`
Required, string | Provide a descriptive name that identifies the tax. |
| `code`
Required, string | Set a unique code to identify this tax. |
| `rate`
Required, string | Specify the percentage rate for the tax. Use a decimal value from `0.01` to `100.00` with exactly two decimal places (for example, `20.00`). |
| `description`
string | Provide additional details about the tax configuration. |
For information on all parameters, see API reference.
```shell lines title="Sample request" theme={null}
curl -X POST 'https://api-m.sandbox.paypal.com/v1/commerce/billing/taxes' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ' \
-d '{
"name": "Standard VAT",
"code": "standard_vat",
"rate": "20.00",
"description": "Standard Value Added Tax"
}'
```
```json lines title="Sample response" theme={null}
{
"id": "1a901a90-1a90-1a90-1a90-1a901a901a90",
"name": "Standard VAT",
"code": "standard_vat",
"description": "Standard Value Added Tax",
"rate": "20.00",
"created_at": "2023-07-06T14:35:58Z"
}
```
A successful call returns a `201 Created` response. The response includes the following parameter:
| Parameter | Description | Further action |
| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `code`
string | Unique code for the tax configuration. | Use this `code` when applying taxes to billing entities, customers, pricing plans, or subscriptions. |
For information on all parameters, see API reference.
## 3. Apply taxes
After creating your tax configurations, you can apply them throughout your billing system:
| Action | How to apply taxes |
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Apply to billing entities** | After creating billing entities, update them to include `tax_codes` with the tax codes that apply to that entity. |
| **Apply to customers** | When registering customers, include `tax_codes` in your request body with the tax codes that apply to that customer. |
| **Apply to pricing plans** | When creating pricing plans:
• Include `tax_codes` at the plan level for taxes on the base fee
• Use `usage_based_charges[].tax_codes` for taxes on specific usage charges
• Use `minimum_commitment.tax_codes` for taxes on minimum commitments |
| **Apply to subscriptions** | When creating subscriptions, use the `plan_overrides` object to customize tax codes:
• `plan_overrides.tax_codes` for plan-level taxes
• `plan_overrides.charges[].tax_codes` for charge-specific taxes
• `plan_overrides.minimum_commitment.tax_codes` for minimum commitment taxes |
| **Manage existing taxes** | Use the tax management APIs to list all configured taxes, retrieve specific tax details, and update tax rates or descriptions as regulatory requirements change. For more information, see Manage taxes. |