Skip to main content
A tax configuration defines a reusable tax rate that the system automatically applies to calculate taxes. You can apply taxes to: To set up taxes in your billing system:
  1. Understand tax configuration
  2. Create tax
  3. Apply taxes

​
1. Understand tax configuration

Before you create a tax, decide on these configuration details based on your business requirements and regional regulations. Then, use the Create tax API to send the information to PayPal. 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.
Important: Once 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 send a POST request to /v1/commerce/billing/taxes with tax details. On successful tax creation, the PayPal server returns the created tax object with a unique identifier. 
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"
    }'

​
Request body parameters

Parameter nameDescription
name
Required, string		Name of the tax.
code
Required, string		Unique identifier to reference the tax in API calls.
rate
Required, string		Percentage rate that the system applies to transactions. A decimal amount from 0.01 to 100.00, with exactly two decimal places. Example: 20.00.
description
string		Detailed description of the tax.

​
Response parameters

Note: This section documents only the response parameters relevant for the next step. For the exhaustive list of response parameters, see API reference.
Parameter nameDescription and further action
code
string		Unique identifier for the tax configuration. Use this code when applying taxes to billing entities, customers, pricing plans, or subscriptions.

​
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.
⌘I