Tax Categories

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

A maximum number of 100 TaxCategories can be created per Project. Learn more about this limit.

Representations

TaxCategory

id
String

Unique identifier of the TaxCategory.

version
Int

Current version of the TaxCategory.

key
String

User-defined unique identifier of the TaxCategory.

MinLength: 2MaxLength: 256Pattern: ^[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

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

createdByBETA

Present on resources created after 1 February 2019 except for events not tracked.

lastModifiedAt

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

lastModifiedByBETA

Present on resources created after 1 February 2019 except for events not tracked.

TaxCategoryDraft

key
String

User-defined unique identifier for the TaxCategory.

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

Name of the TaxCategory.

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
Int

Number of results requested.

offset
Int

Number of elements skipped.

count
Int

Actual number of results returned.

total
Int

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

id
String

Unique identifier of the referenced TaxCategory.

typeId
String
"tax-category"

References a TaxCategory.

obj

Contains the representation of the expanded TaxCategory. Only present in responses to requests with Reference Expansion for TaxCategories.

TaxCategoryResourceIdentifier

id
String

Unique identifier of the referenced TaxCategory. Either id or key is required.

key
String

User-defined unique identifier of the referenced TaxCategory. Either id or key is required.

MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
typeId
String
"tax-category"

References a TaxCategory.

TaxRate

id
String

Present if the TaxRate is part of a TaxCategory. Absent for external TaxRates in LineItem, CustomLineItem, and ShippingInfo.

name
String

Name of the TaxRate.

amount
Float

Tax rate. If subrates are used, the amount must be the sum of all subrates.

Maximum: 1
includedInPrice
Boolean

If true, tax is included in Embedded Prices and the taxedPrice is present on LineItems. In this case, the totalNet price on TaxedPrice includes the TaxRate.

country

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.

subRates
Array of SubRate

Used to calculate the taxPortions field in a Cart or Order. It is useful if the total tax of a country (such as the US) is a combination of multiple taxes (such as state and local taxes).

SubRate BETA

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

name
String

Name of the SubRate.

amount
Float
Maximum: 1

TaxRateDraft

name
String

Name of the TaxRate.

amount
Float

Tax rate. Must be supplied if no subRates are specified. If subRates are specified, this field can be omitted or it must be the sum of amounts of all subRates.

Maximum: 1
includedInPrice
Boolean

If true, tax is included in Embedded Prices and the taxedPrice is present on LineItems. In this case, the totalNet price on TaxedPrice includes the TaxRate.

country

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.

subRates
Array of SubRate

Used to calculate the taxPortions field in a Cart or Order. It is useful if the total tax of a country (such as the US) is a combination of multiple taxes (such as state and local taxes).

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
The parameter can be passed multiple times.
Response:

200TaxCategory

Request Example:cURL
curl -X 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" : "test-tax-category",
"amount" : 0.2,
"includedInPrice" : true,
"country" : "DE",
"id" : "vWTk7VjT",
"subRates" : [ ]
} ],
"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
The parameter can be passed multiple times.
Response:

200TaxCategory

Request Example:cURL
curl -X 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" : "test-tax-category",
"amount" : 0.2,
"includedInPrice" : true,
"country" : "DE",
"id" : "vWTk7VjT",
"subRates" : [ ]
} ],
"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
The parameter can be passed multiple times.
/^var[.][a-zA-Z0-9]+$/
Any string parameter matching this regular expression

Predicate parameter values.

The parameter can be passed multiple times.
sort
The parameter can be passed multiple times.
expand
The parameter can be passed multiple times.
limit
Int
offset
Int

Number of elements skipped.

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.

Response:

200TaxCategoryPagedQueryResponse

Request Example:cURL
curl -X 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" : "test-tax-category",
"amount" : 0.2,
"includedInPrice" : true,
"country" : "DE",
"id" : "vWTk7VjT",
"subRates" : [ ]
} ],
"createdAt" : "2016-02-24T15:33:40.811Z",
"lastModifiedAt" : "2016-02-24T15:33:40.811Z"
} ]
}

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
The parameter can be passed multiple times.
Request Body:TaxCategoryDraft
Response:

201TaxCategory

Request Example:cURL
curl -X POST 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" : "test-tax-category",
"amount" : 0.2,
"includedInPrice" : true,
"country" : "DE"
} ]
}
DATA
201 Response Example: TaxCategoryjson
{
"id" : "c60f7377-2643-4e99-adb5-b2909657444d",
"version" : 1,
"name" : "test-tax-category",
"rates" : [ {
"name" : "test-tax-category",
"amount" : 0.2,
"includedInPrice" : true,
"country" : "DE",
"id" : "vWTk7VjT",
"subRates" : [ ]
} ],
"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
The parameter can be passed multiple times.
Request Body:
version
Int

Expected version of the TaxCategory on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.

actions

Update actions to be performed on the TaxCategory.

Response:

200TaxCategory

Request Example:cURL
curl -X POST 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" : "test-tax-category",
"amount" : 0.2,
"includedInPrice" : true,
"country" : "DE",
"id" : "vWTk7VjT",
"subRates" : [ ]
} ],
"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
The parameter can be passed multiple times.
Request Body:
version
Int

Expected version of the TaxCategory on which the changes should be applied. If the expected version does not match the actual version, a 409 Conflict will be returned.

actions

Update actions to be performed on the TaxCategory.

Response:

200TaxCategory

Request Example:cURL
curl -X POST 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" : "test-tax-category",
"amount" : 0.2,
"includedInPrice" : true,
"country" : "DE",
"id" : "vWTk7VjT",
"subRates" : [ ]
} ],
"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. Must not be empty.

Example: json
{
"action" : "changeName",
"name" : "name"
}

Set Key

action
String
"setKey"
key
String

Value to set. If empty, any existing value will be removed.

MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
Example: json
{
"action" : "setKey",
"key" : "keyString"
}

Set Description

action
String
"setDescription"
description
String

Value to set. If empty, any existing value will be removed.

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

Add TaxRate

action
String
"addTaxRate"
taxRate

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.

taxRate

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.

Example: json
{
"action" : "removeTaxRate",
"taxRateId" : "{{taxRateID}}"
}

Delete TaxCategory

Delete TaxCategory by ID

DELETE
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:
version
Int

Last seen version of the resource.

expand
The parameter can be passed multiple times.
Response:

200TaxCategory

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" : "test-tax-category",
"amount" : 0.2,
"includedInPrice" : true,
"country" : "DE",
"id" : "vWTk7VjT",
"subRates" : [ ]
} ],
"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}
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
Int

Last seen version of the resource.

expand
The parameter can be passed multiple times.
Response:

200TaxCategory

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" : "test-tax-category",
"amount" : 0.2,
"includedInPrice" : true,
"country" : "DE",
"id" : "vWTk7VjT",
"subRates" : [ ]
} ],
"createdAt" : "2016-02-24T15:33:40.811Z",
"lastModifiedAt" : "2016-02-24T15:33:40.811Z"
}