Create a tax - Paypal Docs

Create a tax

curl --request POST \
  --url https://api-m.sandbox.paypal.com/v1/commerce/billing/taxes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
}

{
  "name": "INVALID_REQUEST",
  "message": "Request is not well-formed, syntactically incorrect, or violates schema.",
  "debug_id": "dc99e3955cdd8",
  "details": [
    {
      "field": "/email",
      "value": "abc",
      "location": "body",
      "issue": "INVALID_PARAMETER_VALUE",
      "description": "The value of a field does not conform to the expected format."
    }
  ]
}

{
  "name": "NOT_AUTHORIZED",
  "message": "Authorization failed due to insufficient permissions.",
  "debug_id": "565f78f101498",
  "details": [
    {
      "issue": "PERMISSION_DENIED",
      "description": "You do not have permission to access or perform operations on this resource."
    }
  ]
}

{
  "name": "UNPROCESSABLE_ENTITY",
  "message": "The requested action could not be performed, semantically incorrect, or failed business validation.",
  "debug_id": "90957fca61718",
  "details": [
    {
      "field": "/email",
      "value": "sdfwdj@sdfs.com",
      "location": "body",
      "issue": "UNSUPPORTED_EMAIL",
      "description": "The email provided is not supported."
    }
  ]
}

{
  "name": "INTERNAL_SERVER_ERROR",
  "message": "An internal server error has occurred.",
  "debug_id": "90957fca61718"
}

POST

/

taxes

Create a tax

curl --request POST \
  --url https://api-m.sandbox.paypal.com/v1/commerce/billing/taxes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
}

{
  "name": "INVALID_REQUEST",
  "message": "Request is not well-formed, syntactically incorrect, or violates schema.",
  "debug_id": "dc99e3955cdd8",
  "details": [
    {
      "field": "/email",
      "value": "abc",
      "location": "body",
      "issue": "INVALID_PARAMETER_VALUE",
      "description": "The value of a field does not conform to the expected format."
    }
  ]
}

{
  "name": "NOT_AUTHORIZED",
  "message": "Authorization failed due to insufficient permissions.",
  "debug_id": "565f78f101498",
  "details": [
    {
      "issue": "PERMISSION_DENIED",
      "description": "You do not have permission to access or perform operations on this resource."
    }
  ]
}

{
  "name": "UNPROCESSABLE_ENTITY",
  "message": "The requested action could not be performed, semantically incorrect, or failed business validation.",
  "debug_id": "90957fca61718",
  "details": [
    {
      "field": "/email",
      "value": "sdfwdj@sdfs.com",
      "location": "body",
      "issue": "UNSUPPORTED_EMAIL",
      "description": "The email provided is not supported."
    }
  ]
}

{
  "name": "INTERNAL_SERVER_ERROR",
  "message": "An internal server error has occurred.",
  "debug_id": "90957fca61718"
}

Authorizations

Authorization

string

header

required

Use the /v1/oauth2/token endpoint to obtain an access token and pass it as a Bearer token in the Authorization header.

Body

application/json

Tax creation request

Request body for creating a new tax

name

string

required

Name of the tax

Example:

"TVA"

rate

string

required

The percentage rate of the tax applied to transactions. A decimal amount from 0.01 to 100.00 inclusive, always with exactly two decimal places, no leading zeros except 0.xx.

Pattern: ^(?!0+(?:\.0+)?$)(?:0?\.\d{1,2}|[1-9]\d?(?:\.\d{1,2})?|100(?:\.0{1,2})?)$

Example:

"20.00"

code

string

required

Unique code used to identify the tax. Must contain only alphanumeric characters, underscores, and hyphens.

Pattern: ^[a-zA-Z0-9_-]*$

Example:

"standard_vat"

description

string

Detailed description of the tax for internal reference

Example:

"French standard VAT"

Response

Successfully created tax

Represents a customizable tax rate that can be applied to invoices and fees

name

string

required

Name of the tax

Example:

"TVA"

rate

string

The percentage rate of the tax applied to transactions. A decimal amount from 0.01 to 100.00 inclusive, always with exactly two decimal places, no leading zeros except 0.xx.

Pattern: ^(?!0+(?:\.0+)?$)(?:0?\.\d{1,2}|[1-9]\d?(?:\.\d{1,2})?|100(?:\.0{1,2})?)$

Example:

"20.00"

description

string

Detailed description of the tax for internal reference

Example:

"French standard VAT"

code

string

Unique code used to identify the tax. Must contain only alphanumeric characters, underscores, and hyphens.

Pattern: ^[a-zA-Z0-9_-]*$

Example:

"standard_vat"

id

string<uuid>

Unique identifier of the tax

Example:

"1a901a90-1a90-1a90-1a90-1a901a901a90"

created_at

string<date-time>

The effective start date of the subscription; can be past, current, or future. Date must be provided in ISO 8601 format

Example:

"2025-06-01T00:00:00Z"

⌘I