> This page is for Docs.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://zuora.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://zuora.ferndocs.com/_mcp/server.

# Zuora Tax Rates API settings

> Learn how to manage Zuora tax rates through the Settings API.

Learn how to manage Zuora tax rates through the Settings API.

## Retrieve a list of tax rates

To retrieve a list of tax rates, see the following request and a sample of 200 response:

HTTP request:

`GET https://rest.apisandbox.zuora.com/settings/tax-rate-periods/{ID}/tax-rates?size=100&page=1`

Request body:

<table>
  <tr>
    <th>
      Key
    </th>

    <th>
      Value
    </th>
  </tr>

  <tr>
    <td>
      Curl
    </td>

    <td>
      GET [https://rest.apisandbox.zuora.com/settings/tax-rate-periods/\\\{ID\\}/tax-rates?size=100\&page=1](https://rest.apisandbox.zuora.com/settings/tax-rate-periods/\\\{ID\\}/tax-rates?size=100\&page=1)
    </td>
  </tr>

  <tr>
    <td>
      Authorization
    </td>

    <td>
      Auth Type - Bearer Token \<oauth_token>
    </td>
  </tr>

  <tr>
    <td>
      Headers
    </td>

    <td>
      * Authorization - Bearer \<oauth_token>
      * Content-Type - application/json
    </td>
  </tr>
</table>

Response body:

```json
{
    "taxRates": [
        {
            "id": "8ad081dd90a5e74f0190ba75246f06b5",
            "taxRatePeriodId": "8ad081dd90a5e74f0190ba7523d106b4",
            "country": "United States",
            "state": "Alabama",
            "county": null,
            "city": null,
            "postalCode": null,
            "taxRegion": null,
            "taxRate1": 0.08,
            "taxRateType1": "Percentage",
            "taxName1": "Sales Tax",
            "taxJursdiction1": "State",
            "taxLocationCode1": "",
            "taxRateDescription1": "Alabama",
            "taxRate2": 0.0,
            "taxRateType2": null,
            "taxName2": null,
            "taxJursdiction2": null,
            "taxLocationCode2": null,
            "taxRateDescription2": null,
            "taxRate3": 0.0,
            "taxRateType3": null,
            "taxName3": null,
            "taxJursdiction3": null,
            "taxLocationCode3": null,
            "taxRateDescription3": null
        },
        {
            "id": "8ad081dd90a5e74f0190ba75247506b6",
            "taxRatePeriodId": "8ad081dd90a5e74f0190ba7523d106b4",
            "country": "United States",
            "state": "Alaska",
            "county": null,
            "city": null,
            "postalCode": null,
            "taxRegion": null,
            "taxRate1": 0.0,
            "taxRateType1": "Percentage",
            "taxName1": "Sales Tax",
            "taxJursdiction1": "State",
            "taxLocationCode1": "",
            "taxRateDescription1": "Alaska",
            "taxRate2": 0.0,
            "taxRateType2": null,
            "taxName2": null,
            "taxJursdiction2": null,
            "taxLocationCode2": null,
            "taxRateDescription2": null,
            "taxRate3": 0.0,
            "taxRateType3": null,
            "taxName3": null,
            "taxJursdiction3": null,
            "taxLocationCode3": null,
            "taxRateDescription3": null
        },
        {
            "id": "8ad081dd90a5e74f0190ba75247b06b7",
            "taxRatePeriodId": "8ad081dd90a5e74f0190ba7523d106b4",
            "country": "United States",
            "state": "Arizona",
            "county": null,
            "city": null,
            "postalCode": null,
            "taxRegion": null,
            "taxRate1": 0.056,
            "taxRateType1": "Percentage",
            "taxName1": "Sales Tax",
            "taxJursdiction1": "State",
            "taxLocationCode1": "",
            "taxRateDescription1": "Arizona",
            "taxRate2": 0.0,
            "taxRateType2": null,
            "taxName2": null,
            "taxJursdiction2": null,
            "taxLocationCode2": null,
            "taxRateDescription2": null,
            "taxRate3": 0.0,
            "taxRateType3": null,
            "taxName3": null,
            "taxJursdiction3": null,
            "taxLocationCode3": null,
            "taxRateDescription3": null
        },
        {
            "id": "8ad081dd90a5e74f0190ba75248006b8",
            "taxRatePeriodId": "8ad081dd90a5e74f0190ba7523d106b4",
            "country": "United States",
            "state": "Arkansas",
            "county": null,
            "city": null,
            "postalCode": null,
            "taxRegion": null,
            "taxRate1": 0.06,
            "taxRateType1": "Percentage",
            "taxName1": "Sales Tax",
            "taxJursdiction1": "State",
            "taxLocationCode1": "",
            "taxRateDescription1": "Arkansas",
            "taxRate2": 0.0,
            "taxRateType2": null,
            "taxName2": null,
            "taxJursdiction2": null,
            "taxLocationCode2": null,
            "taxRateDescription2": null,
            "taxRate3": 0.0,
            "taxRateType3": null,
            "taxName3": null,
            "taxJursdiction3": null,
            "taxLocationCode3": null,
            "taxRateDescription3": null
        },
        {
            "id": "8ad081dd90a5e74f0190ba75250b06d2",
            "taxRatePeriodId": "8ad081dd90a5e74f0190ba7523d106b4",
            "country": "United States",
            "state": "New Jersey",
            "county": null,
            "city": null,
            "postalCode": null,
            "taxRegion": null,
            "taxRate1": 0.07,
            "taxRateType1": "Percentage",
            "taxName1": "Sales Tax",
            "taxJursdiction1": "State",
            "taxLocationCode1": "",
            "taxRateDescription1": "New Jersey",
            "taxRate2": 0.0,
            "taxRateType2": null,
            "taxName2": null,
            "taxJursdiction2": null,
            "taxLocationCode2": null,
            "taxRateDescription2": null,
            "taxRate3": 0.0,
            "taxRateType3": null,
            "taxName3": null,
            "taxJursdiction3": null,
            "taxLocationCode3": null,
            "taxRateDescription3": null
        },
        {
            "id": "8ad081dd90a5e74f0190ba7525c806ec",
            "taxRatePeriodId": "8ad081dd90a5e74f0190ba7523d106b4",
            "country": "Italy",
            "state": null,
            "county": null,
            "city": null,
            "postalCode": null,
            "taxRegion": null,
            "taxRate1": 0.2,
            "taxRateType1": "Percentage",
            "taxName1": "VAT",
            "taxJursdiction1": "",
            "taxLocationCode1": "",
            "taxRateDescription1": "VAT",
            "taxRate2": 0.0,
            "taxRateType2": null,
            "taxName2": null,
            "taxJursdiction2": null,
            "taxLocationCode2": null,
            "taxRateDescription2": null,
            "taxRate3": 0.0,
            "taxRateType3": null,
            "taxName3": null,
            "taxJursdiction3": null,
            "taxLocationCode3": null,
            "taxRateDescription3": null
        },
        {
            "id": "8ad081dd90a5e74f0190ba75266c0707",
            "taxRatePeriodId": "8ad081dd90a5e74f0190ba7523d106b4",
            "country": "Canada",
            "state": "Yukon",
            "county": null,
            "city": null,
            "postalCode": null,
            "taxRegion": null,
            "taxRate1": 0.05,
            "taxRateType1": "Percentage",
            "taxName1": "CDNTax",
            "taxJursdiction1": "",
            "taxLocationCode1": "",
            "taxRateDescription1": "GST",
            "taxRate2": 0.0,
            "taxRateType2": null,
            "taxName2": null,
            "taxJursdiction2": null,
            "taxLocationCode2": null,
            "taxRateDescription2": null,
            "taxRate3": 0.0,
            "taxRateType3": null,
            "taxName3": null,
            "taxJursdiction3": null,
            "taxLocationCode3": null,
            "taxRateDescription3": null
        }
    ],
    "success": true
}
```

## Create Tax Rates

To create a new Tax rate, see the following request and a sample of 200 response:

HTTP request:

`POST https://rest.apisandbox.zuora.com/settings/tax-rate-periods/{taxRatePeriodID}/tax-rates`

Request body:

<table>
  <tr>
    <th>
      Key
    </th>

    <th>
      Value
    </th>
  </tr>

  <tr>
    <td>
      Curl
    </td>

    <td>
      POST [https://rest.apisandbox.zuora.com/settings/tax-rate-periods/\\\{taxRatePeriodID\\}/tax-rates](https://rest.apisandbox.zuora.com/settings/tax-rate-periods/\\\{taxRatePeriodID\\}/tax-rates)
    </td>
  </tr>

  <tr>
    <td>
      Authorization
    </td>

    <td>
      Auth Type - Bearer Token \<oauth_token>
    </td>
  </tr>

  <tr>
    <td>
      Headers
    </td>

    <td>
      * Authorization - Bearer \<oauth_token>
      * Content-Type - application/json
    </td>
  </tr>

  <tr>
    <td>
      Body
    </td>

    <td>
      \{

      "taxRates": \[

      \{

      "country": "string",

      "state": "string",

      "taxRate1": number,

      "taxRateType1": "Percentage",

      "taxName1": "string",

      "taxJurisdiction1": "string",

      "taxLocationCode1": "string",

      "taxRateDescription1": "string"

      }

      ]

      }

      Example:

      ```json
      {
         "taxRates": [
             {
                 "country": "United States",
                 "state": "California",
                 "taxRate1": 0.08,
                 "taxRateType1": "Percentage",
                 "taxName1": "taxName1",
                 "taxJursdiction1": "state",
                 "taxLocationCode1": "000-1",
                 "taxRateDescription1": "taxRateDescription1"
             }
         ]
      }
      ```
    </td>
  </tr>
</table>

Response body:

```json
{
   "taxRates": [
       {
           "id": "8ad08487917ed51f01918ddbf7352ff5",
           "taxRatePeriodId": "8ad081dd917ed47501918dcd15c954c0",
           "country": "United States",
           "state": "California",
           "county": null,
           "city": null,
           "postalCode": null,
           "taxRegion": null,
           "taxRate1": 0.08,
           "taxRateType1": "Percentage",
           "taxName1": "taxName1",
           "taxJursdiction1": "state",
           "taxLocationCode1": "000-1",
           "taxRateDescription1": "taxRateDescription1",
           "taxRate2": 0.0,
           "taxRateType2": null,
           "taxName2": null,
           "taxJursdiction2": null,
           "taxLocationCode2": null,
           "taxRateDescription2": null,
           "taxRate3": 0.0,
           "taxRateType3": null,
           "taxName3": null,
           "taxJursdiction3": null,
           "taxLocationCode3": null,
           "taxRateDescription3": null
       }
   ],
   "success": true
}
```

## Update Tax Rates

Tax rates cannot be updated. To make changes, you must delete the existing tax rate and create a new one.

## Delete Tax Rates

To delete a tax rate, see the following request and a sample of 200 response:

> **Note**
>
> This API deletes all tax rates for a period.

HTTP request:

`DELETE https://rest.apisandbox.zuora.com/settings/tax-rate-periods/{ID}/tax-rates`

Request body:

<table>
  <tr>
    <th>
      Key
    </th>

    <th>
      Value
    </th>
  </tr>

  <tr>
    <td>
      Curl
    </td>

    <td>
      DELETE [https://rest.apisandbox.zuora.com/settings/tax-rate-periods/\\\{ID\\}/tax-rates](https://rest.apisandbox.zuora.com/settings/tax-rate-periods/\\\{ID\\}/tax-rates)
    </td>
  </tr>

  <tr>
    <td>
      Authorization
    </td>

    <td>
      Auth Type - Bearer Token \<oauth_token>
    </td>
  </tr>

  <tr>
    <td>
      Headers
    </td>

    <td>
      * Authorization - Bearer \<oauth_token>
      * Content-Type - application/json
    </td>
  </tr>
</table>

Response body:

```json
{
   "success": true
}
```