Tax Categories

B2CB2BB2XB2C CORE COMMERCEB2B CORE COMMERCEB2X CORE COMMERCEPRODUCT CATALOGAgenticLift

Tax Categories define how Products are to be taxed in different countries.

A maximum number of 100 TaxCategories can be created per Project. This is a soft limit that can be increased per Project after a performance impact review. See Limit increase guidance.
Learn more about taxes in our self-paced Model your taxes module.

Representations

TaxCategory

id​
String​

Unique identifier of the TaxCategory.

version​
Int64​

Current version of the TaxCategory.

key​
String​

User-defined unique identifier of the TaxCategory.

MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
name​
String​

Name of the TaxCategory.

description​
String​

Description of the TaxCategory.

rates​
Array of TaxRate​

Tax rates and subrates of states and countries. Each TaxRate in the array has a unique ID.

createdAt​
DateTime​

Date and time (UTC) the TaxCategory was initially created.

createdBy​BETA
CreatedBy​

IDs and references that created the TaxCategory.

lastModifiedAt​
DateTime​

Date and time (UTC) the TaxCategory was last updated.

lastModifiedBy​BETA
LastModifiedBy​

IDs and references that last modified the TaxCategory.

TaxCategoryDraft

key​
String​

User-defined unique identifier for the TaxCategory.

If the value is used by another TaxCategory in the Project, a DuplicateField error is returned.
MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
name​
String​

Name of the TaxCategory.

If the provided name is used by another TaxCategory in the Project, an InvalidOperation error is returned.
description​
String​

Description of the TaxCategory.

rates​
Array of TaxRateDraft​

Tax rates and subrates of states and countries.

TaxCategoryPagedQueryResponse

PagedQueryResult with results containing an array of TaxCategory.
limit​
Int64​
Number of results requested.
Default: 20​Minimum: 0​Maximum: 500​
offset​
Int64​
Number of elements skipped.
Default: 0​Maximum: 10000​
count​
Int64​

Actual number of results returned.

total​
Int64​
Total number of results matching the query. This number is an estimation that is not strongly consistent. This field is returned by default. For improved performance, calculating this field can be deactivated by using the query parameter withTotal=false. When the results are filtered with a Query Predicate, total is subject to a limit.
results​
Array of TaxCategory​
TaxCategories matching the query.

TaxCategoryReference

Reference to a TaxCategory.
id​
String​
Unique identifier of the referenced TaxCategory.
typeId​
ReferenceTypeId​
tax-category
obj​
TaxCategory​
Contains the representation of the expanded TaxCategory. Only present in responses to requests with Reference Expansion for TaxCategories.

TaxCategoryKeyReference

Used by the Import API to identify a TaxCategory.
key​
String​

User-defined unique identifier of the referenced TaxCategory.

typeId​
ReferenceType​
tax-category

TaxCategoryResourceIdentifier

ResourceIdentifier to a TaxCategory. Either id or key is required. If both are set, an InvalidJsonInput error is returned.
id​
String​
Unique identifier of the referenced TaxCategory. Required if key is absent.
key​
String​
User-defined unique identifier of the referenced TaxCategory. Required if id is absent.
MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
typeId​
ReferenceTypeId​
tax-category

TaxRate

This type is equivalent to TaxRate and TaxRateInput in the GraphQL API.
id​
String​
Present if the TaxRate is part of a TaxCategory. Absent for external TaxRates in LineItem, CustomLineItem, and ShippingInfo.
key​
String​
User-defined identifier of the TaxRate. Unique within the TaxCategory containing it. Present when set using TaxRateDraft. Not available for external TaxRates created using ExternalTaxRateDraft.
MinLength: 2​MaxLength: 256​Pattern: ^[a-zA-Z0-9_-]​
name​
String​

Name of the TaxRate.

amount​
Float​
Tax rate. If subrates are used, the amount is the sum of all rates in subRates.
Minimum: 0​Maximum: 1​
includedInPrice​
Boolean​
Whether tax is included in Embedded Prices or Standalone Prices, and the taxedPrice is present on LineItems. In this case, the totalNet price on TaxedPrice includes the TaxRate.
country​
CountryCode​
Country in which the tax rate is applied in ISO 3166-1 alpha-2 format.
Pattern: ^[A-Z]{2}$​
state​
String​
State within the country, such as Texas in the United States. The value is case-sensitive and must use the same casing as the state value in the Cart shippingAddress.
subRates​
Array of SubRate​
Used when the total tax is a combination of multiple taxes (for example, local, state/provincial, and/or federal taxes). The total of all subrates must equal the TaxRate amount. These subrates are used to calculate the taxPortions field of a Cart or Order and the taxedPrice field of LineItems, CustomLineItems, and ShippingInfos.

SubRate

It is used to calculate the taxPortions field in a Cart or Order.
name​
String​

Name of the SubRate.

amount​
Float​
Minimum: 0​Maximum: 1​

TaxRateDraft

key​
String​

User-defined identifier of the TaxRate.

If the provided key is used by another TaxRate in the TaxCategory, a DuplicateField error is returned.
MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
name​
String​

Name of the TaxRate.

amount​
Float​

Tax rate.

Either amount or subRates must be defined. If both are defined, the value of this field must be equal to the sum of the subRates amounts; otherwise, an InvalidOperation error is returned.
Minimum: 0​Maximum: 1​
includedInPrice​
Boolean​
Whether tax is included in Embedded Prices or Standalone Prices, and the taxedPrice is present on LineItems. In this case, the totalNet price on TaxedPrice includes the TaxRate.
country​
CountryCode​
Country in which the tax rate is applied in ISO 3166-1 alpha-2 format.
If the provided combination of country and state exists for the TaxCategory, a DuplicateField error is returned.
Pattern: ^[A-Z]{2}$​
state​
String​
State within the country, such as Texas in the United States. The value is case-sensitive and must use the same casing as the state value in the Cart shippingAddress. Empty strings are treated as if state was omitted.
If the provided combination of country and state exists for the TaxCategory, a DuplicateField error is returned.
subRates​
Array of SubRate​
Used when the total tax is a combination of multiple taxes (for example, local, state/provincial, and/or federal taxes). If amount is defined, the total of all subrates must equal amount. These subrates are used to calculate the taxPortions field of a Cart or Order and the taxedPrice field of LineItems, CustomLineItems, and ShippingInfos.

Get TaxCategory

Get TaxCategory by ID

GET
https://api.{region}.commercetools.com/{projectKey}/tax-categories/{id}
OAuth 2.0 Scopes:
view_products:{projectKey}view_tax_categories:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
id
​
String
​
id of the TaxCategory.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200

TaxCategory

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/tax-categories/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: TaxCategoryjson
{
  "id": "c60f7377-2643-4e99-adb5-b2909657444d",
  "version": 1,
  "name": "test-tax-category",
  "rates": [
    {
      "name": "HST Ontario",
      "amount": 0.13,
      "includedInPrice": true,
      "country": "CA",
      "state": "ON",
      "subRates": [
        {
          "name": "Federal rate (GST 5%)",
          "amount": 0.05
        },
        {
          "name": "Provincial rate (PST 8%)",
          "amount": 0.08
        }
      ]
    }
  ],
  "createdAt": "2016-02-24T15:33:40.811Z",
  "lastModifiedAt": "2016-02-24T15:33:40.811Z"
}

Get TaxCategory by Key

GET
https://api.{region}.commercetools.com/{projectKey}/tax-categories/key={key}
OAuth 2.0 Scopes:
view_products:{projectKey}view_tax_categories:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
key
​
String
​
key of the TaxCategory.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200

TaxCategory

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/tax-categories/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: TaxCategoryjson
{
  "id": "c60f7377-2643-4e99-adb5-b2909657444d",
  "version": 1,
  "name": "test-tax-category",
  "rates": [
    {
      "name": "HST Ontario",
      "amount": 0.13,
      "includedInPrice": true,
      "country": "CA",
      "state": "ON",
      "subRates": [
        {
          "name": "Federal rate (GST 5%)",
          "amount": 0.05
        },
        {
          "name": "Provincial rate (PST 8%)",
          "amount": 0.08
        }
      ]
    }
  ],
  "createdAt": "2016-02-24T15:33:40.811Z",
  "lastModifiedAt": "2016-02-24T15:33:40.811Z"
}

Query TaxCategories

GET
https://api.{region}.commercetools.com/{projectKey}/tax-categories
OAuth 2.0 Scopes:
view_products:{projectKey}view_tax_categories:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Query parameters:
where
​
QueryPredicate
​
The parameter can be passed multiple times.
sort
​
Sort
​
The parameter can be passed multiple times.
expand
​
Expansion
​
The parameter can be passed multiple times.
limit
​
Int32
​
Number of results requested.
Default: 20​
Minimum: 0​
Maximum: 500​
offset
​
Int32
​
Number of elements skipped.
Default: 0​
Maximum: 10000​
withTotal
​
Boolean
​
Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.
Default: true​
var.<varName>
​
String
​
Predicate parameter values.
The parameter can be passed multiple times.
Response:
200

TaxCategoryPagedQueryResponse

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/tax-categories -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: TaxCategoryPagedQueryResponsejson
{
  "limit": 20,
  "offset": 0,
  "count": 1,
  "total": 1,
  "results": [
    {
      "id": "c60f7377-2643-4e99-adb5-b2909657444d",
      "version": 1,
      "name": "test-tax-category",
      "rates": [
        {
          "name": "HST Ontario",
          "amount": 0.13,
          "includedInPrice": true,
          "country": "CA",
          "state": "ON",
          "subRates": [
            {
              "name": "Federal rate (GST 5%)",
              "amount": 0.05
            },
            {
              "name": "Provincial rate (PST 8%)",
              "amount": 0.08
            }
          ]
        }
      ],
      "createdAt": "2016-02-24T15:33:40.811Z",
      "lastModifiedAt": "2016-02-24T15:33:40.811Z"
    }
  ]
}

Check if TaxCategory exists

Check if TaxCategory exists by ID

HEAD
https://api.{region}.commercetools.com/{projectKey}/tax-categories/{id}
Checks if a TaxCategory exists with the provided id. Returns a 200 status if the TaxCategory exists, or a 404 status otherwise.
OAuth 2.0 Scopes:
view_products:{projectKey}view_tax_categories:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
id
​
String
​
id of the TaxCategory.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/tax-categories/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if TaxCategory exists by Key

HEAD
https://api.{region}.commercetools.com/{projectKey}/tax-categories/key={key}
Checks if a TaxCategory exists with the provided key. Returns a 200 status if the Tax Category exists, or a 404 status otherwise.
OAuth 2.0 Scopes:
view_products:{projectKey}view_tax_categories:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
key
​
String
​
key of the TaxCategory.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/tax-categories/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if TaxCategory exists by Query Predicate

HEAD
https://api.{region}.commercetools.com/{projectKey}/tax-categories
Checks if one or more Tax Categories exist for the provided query predicate. Returns a 200 status if any TaxCategories match the query predicate, or a 404 status otherwise.
OAuth 2.0 Scopes:
view_products:{projectKey}view_tax_categories:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Query parameters:
where
​
QueryPredicate
​
The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/tax-categories -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Create TaxCategory

POST
https://api.{region}.commercetools.com/{projectKey}/tax-categories
OAuth 2.0 Scopes:
manage_products:{projectKey}manage_tax_categories:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Request Body:TaxCategoryDraftasapplication/json
Response:
201

TaxCategory

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/tax-categories -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "name" : "test-tax-category",
  "rates" : [ {
    "name" : "HST Ontario",
    "amount" : 0.13,
    "includedInPrice" : true,
    "country" : "CA",
    "state" : "ON",
    "subRates" : [ {
      "name" : "Federal rate (GST 5%)",
      "amount" : 0.05
    }, {
      "name" : "Provincial rate (PST 8%)",
      "amount" : 0.08
    } ]
  } ]
}
DATA
201 Response Example: TaxCategoryjson
{
  "id": "c60f7377-2643-4e99-adb5-b2909657444d",
  "version": 1,
  "name": "test-tax-category",
  "rates": [
    {
      "name": "HST Ontario",
      "amount": 0.13,
      "includedInPrice": true,
      "country": "CA",
      "state": "ON",
      "subRates": [
        {
          "name": "Federal rate (GST 5%)",
          "amount": 0.05
        },
        {
          "name": "Provincial rate (PST 8%)",
          "amount": 0.08
        }
      ]
    }
  ],
  "createdAt": "2016-02-24T15:33:40.811Z",
  "lastModifiedAt": "2016-02-24T15:33:40.811Z"
}

Update TaxCategory

Update TaxCategory by ID

POST
https://api.{region}.commercetools.com/{projectKey}/tax-categories/{id}
OAuth 2.0 Scopes:
manage_products:{projectKey}manage_tax_categories:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
id
​
String
​
id of the TaxCategory.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Request Body:
application/json
version​
Int64​
Expected version of the TaxCategory on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned.
actions​
Array of TaxCategoryUpdateAction​

Update actions to be performed on the TaxCategory.

Response:
200

TaxCategory

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/tax-categories/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 1,
  "actions" : [ {
    "action" : "changeName",
    "name" : "New Name"
  } ]
}
DATA
200 Response Example: TaxCategoryjson
{
  "id": "c60f7377-2643-4e99-adb5-b2909657444d",
  "version": 1,
  "name": "test-tax-category",
  "rates": [
    {
      "name": "HST Ontario",
      "amount": 0.13,
      "includedInPrice": true,
      "country": "CA",
      "state": "ON",
      "subRates": [
        {
          "name": "Federal rate (GST 5%)",
          "amount": 0.05
        },
        {
          "name": "Provincial rate (PST 8%)",
          "amount": 0.08
        }
      ]
    }
  ],
  "createdAt": "2016-02-24T15:33:40.811Z",
  "lastModifiedAt": "2016-02-24T15:33:40.811Z"
}

Update TaxCategory by Key

POST
https://api.{region}.commercetools.com/{projectKey}/tax-categories/key={key}
OAuth 2.0 Scopes:
manage_products:{projectKey}manage_tax_categories:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
key
​
String
​
key of the TaxCategory.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Request Body:
application/json
version​
Int64​
Expected version of the TaxCategory on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned.
actions​
Array of TaxCategoryUpdateAction​

Update actions to be performed on the TaxCategory.

Response:
200

TaxCategory

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/tax-categories/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 1,
  "actions" : [ {
    "action" : "changeName",
    "name" : "New Name"
  } ]
}
DATA
200 Response Example: TaxCategoryjson
{
  "id": "c60f7377-2643-4e99-adb5-b2909657444d",
  "version": 1,
  "name": "test-tax-category",
  "rates": [
    {
      "name": "HST Ontario",
      "amount": 0.13,
      "includedInPrice": true,
      "country": "CA",
      "state": "ON",
      "subRates": [
        {
          "name": "Federal rate (GST 5%)",
          "amount": 0.05
        },
        {
          "name": "Provincial rate (PST 8%)",
          "amount": 0.08
        }
      ]
    }
  ],
  "createdAt": "2016-02-24T15:33:40.811Z",
  "lastModifiedAt": "2016-02-24T15:33:40.811Z"
}

Update actions

Change Name

action​
String​
"changeName"
name​
String​

New value to set.

If the provided name is used by another TaxCategory in the Project, an InvalidOperation error is returned.
Example: json
{
  "action": "changeName",
  "name": "New Name"
}

Set Key

action​
String​
"setKey"
key​
String​

Value to set. If omitted, any existing value is removed.

If the value is used by another TaxCategory in the Project, a DuplicateField error is returned.
MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
Example: json
{
  "action": "setKey",
  "key": "keyString"
}

Set Description

action​
String​
"setDescription"
description​
String​

Value to set. If omitted, any existing value is removed.

Example: json
{
  "action": "setDescription",
  "description": "new Description"
}

Add TaxRate

action​
String​
"addTaxRate"
taxRate​
TaxRateDraft​
Value to append to the rates array.
Example: json
{
  "action": "addTaxRate",
  "taxRate": {
    "name": "TaxRateName",
    "amount": 0.3,
    "includedInPrice": true,
    "country": "DE"
  }
}

Replace TaxRate

action​
String​
"replaceTaxRate"
taxRateId​
String​
ID of the TaxRate to replace. Either taxRateId or taxRateKey must be provided.
If the referenced TaxRate does not exist within the TaxCategory, an InvalidOperation error is returned.
taxRateKey​
String​
Key of the TaxRate to replace. Either taxRateId or taxRateKey must be provided.
If the referenced TaxRate does not exist within the TaxCategory, an InvalidOperation error is returned.
taxRate​
TaxRateDraft​

New TaxRate to replace with.

Example: json
{
  "action": "replaceTaxRate",
  "taxRateId": "{{taxRateID}}",
  "taxRate": {
    "name": "TaxRateName",
    "amount": 0.4,
    "includedInPrice": true,
    "country": "DE"
  }
}

Remove TaxRate

action​
String​
"removeTaxRate"
taxRateId​
String​
ID of the TaxRate to remove. Either taxRateId or taxRateKey must be provided.
If the referenced TaxRate does not exist within the TaxCategory, an InvalidOperation error is returned.
taxRateKey​
String​
Key of the TaxRate to remove. Either taxRateId or taxRateKey must be provided.
If the referenced TaxRate does not exist within the TaxCategory, an InvalidOperation error is returned.
Example: json
{
  "action": "removeTaxRate",
  "taxRateId": "{{taxRateID}}"
}

Delete TaxCategory

Delete TaxCategory by ID

DELETE
https://api.{region}.commercetools.com/{projectKey}/tax-categories/{id}
If the TaxCategory is referenced by a resource, a ReferenceExists error is returned.
OAuth 2.0 Scopes:
manage_products:{projectKey}manage_tax_categories:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
id
​
String
​
id of the TaxCategory.
Query parameters:
version
​
Int64
​

Last seen version of the resource.

expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200

TaxCategory

as
application/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/tax-categories/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: TaxCategoryjson
{
  "id": "c60f7377-2643-4e99-adb5-b2909657444d",
  "version": 1,
  "name": "test-tax-category",
  "rates": [
    {
      "name": "HST Ontario",
      "amount": 0.13,
      "includedInPrice": true,
      "country": "CA",
      "state": "ON",
      "subRates": [
        {
          "name": "Federal rate (GST 5%)",
          "amount": 0.05
        },
        {
          "name": "Provincial rate (PST 8%)",
          "amount": 0.08
        }
      ]
    }
  ],
  "createdAt": "2016-02-24T15:33:40.811Z",
  "lastModifiedAt": "2016-02-24T15:33:40.811Z"
}

Delete TaxCategory by Key

DELETE
https://api.{region}.commercetools.com/{projectKey}/tax-categories/key={key}
If the TaxCategory is referenced by a resource, a ReferenceExists error is returned.
OAuth 2.0 Scopes:
manage_products:{projectKey}manage_tax_categories:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
key
​
String
​
key of the TaxCategory.
Query parameters:
version
​
Int64
​

Last seen version of the resource.

expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200

TaxCategory

as
application/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/tax-categories/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: TaxCategoryjson
{
  "id": "c60f7377-2643-4e99-adb5-b2909657444d",
  "version": 1,
  "name": "test-tax-category",
  "rates": [
    {
      "name": "HST Ontario",
      "amount": 0.13,
      "includedInPrice": true,
      "country": "CA",
      "state": "ON",
      "subRates": [
        {
          "name": "Federal rate (GST 5%)",
          "amount": 0.05
        },
        {
          "name": "Provincial rate (PST 8%)",
          "amount": 0.08
        }
      ]
    }
  ],
  "createdAt": "2016-02-24T15:33:40.811Z",
  "lastModifiedAt": "2016-02-24T15:33:40.811Z"
}