Skip to main content
Limited Release
A tax configuration defines a reusable tax rate that the system automatically applies to calculate taxes. You can apply taxes to:

​
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:
ParameterAction
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"
    }'
A successful call returns a 201 Created response. The response includes the following parameter:
ParameterDescriptionFurther 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:
ActionHow to apply taxes
Apply to billing entitiesAfter creating billing entities, update them to include tax_codes with the tax codes that apply to that entity.
Apply to customersWhen registering customers, include tax_codes in your request body with the tax codes that apply to that customer.
Apply to pricing plansWhen 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 subscriptionsWhen 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 taxesUse 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.