Create taxes - Paypal Docs

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.

curl -X POST 'https://api-m.sandbox.paypal.com/v1/commerce/billing/taxes' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <ACCESS-TOKEN>' \
    -d '{
      "name": "Standard VAT",
      "code": "standard_vat",
      "rate": "20.00",
      "description": "Standard Value Added Tax"
    }'

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

​1. Understand tax configuration

​2. Create tax

​3. Apply taxes

1. Understand tax configuration

2. Create tax

3. Apply taxes