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: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 | Date and time (UTC) the TaxCategory was initially created. |
createdBy BETA | Present on resources created after 1 February 2019 except for events not tracked. |
lastModifiedAt | Date and time (UTC) the TaxCategory was last updated. |
lastModifiedBy BETA | Present on resources created after 1 February 2019 except for events not tracked. |
TaxCategoryDraft
key String | User-defined unique identifier for 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 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 |
results Array of TaxCategory | TaxCategories matching the query. |
TaxCategoryReference
Reference to a TaxCategory.
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 |
key String | User-defined unique identifier of the referenced TaxCategory. Either 2 MaxLength: 256 Pattern: ^[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. |
key String | User-defined unique identifier of the TaxRate. 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 must be the sum of all subrates. Maximum:1 |
includedInPrice Boolean | If |
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
key String | User-defined unique identifier of the TaxRate. MinLength:2 MaxLength: 256 Pattern: ^[a-zA-Z0-9_-] |
name String | Name of the TaxRate. |
amount Float | Tax rate.
Must be supplied if no 1 |
includedInPrice Boolean | If |
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
view_products:{projectKey},
view_tax_categories:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
expand | The parameter can be passed multiple times. |
curl --get https://api.{region}.commercetools.com/{projectKey}/tax-categories/{id} -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
{"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
view_products:{projectKey},
view_tax_categories:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
key String |
|
expand | The parameter can be passed multiple times. |
curl --get https://api.{region}.commercetools.com/{projectKey}/tax-categories/key={key} -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
{"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
view_products:{projectKey},
view_tax_categories:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
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 | Number of results requested. |
offset Int | Number of elements skipped. |
withTotal Boolean | Controls the calculation of the total number of query results. Set to |
curl --get https://api.{region}.commercetools.com/{projectKey}/tax-categories -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
{"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
manage_products:{projectKey},
manage_tax_categories:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
expand | The parameter can be passed multiple times. |
application/json
application/json
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" : "test-tax-category","amount" : 0.2,"includedInPrice" : true,"country" : "DE"} ]}DATA
{"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
manage_products:{projectKey},
manage_tax_categories:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
expand | The parameter can be passed multiple times. |
application/json
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 ConcurrentModification error is returned. |
actions Array of TaxCategoryUpdateAction | Update actions to be performed on the TaxCategory. |
application/json
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
{"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
manage_products:{projectKey},
manage_tax_categories:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
key String |
|
expand | The parameter can be passed multiple times. |
application/json
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 ConcurrentModification error is returned. |
actions Array of TaxCategoryUpdateAction | Update actions to be performed on the TaxCategory. |
application/json
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
{"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. |
{"action" : "changeName","name" : "name"}
Set Key
action String | "setKey" |
key String | Value to set. If empty, any existing value will be removed. MinLength:2 MaxLength: 256 Pattern: ^[A-Za-z0-9_-]+$ |
{"action" : "setKey","key" : "keyString"}
Set Description
action String | "setDescription" |
description String | Value to set. If empty, any existing value will be removed. |
{"action" : "setDescription","description" : "new Description"}
Add TaxRate
action String | "addTaxRate" |
taxRate | Value to append to the |
{"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 |
taxRateKey String | Key of the TaxRate to replace.
Either |
taxRate | New TaxRate to replace with. |
{"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 |
taxRateKey String | Key of the TaxRate to remove.
Either |
{"action" : "removeTaxRate","taxRateId" : "{{taxRateID}}"}
Delete TaxCategory
Delete TaxCategory by ID
manage_products:{projectKey},
manage_tax_categories:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
version Int | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/tax-categories/{id}?version={version} -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
{"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
manage_products:{projectKey},
manage_tax_categories:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
key String |
|
version Int | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/tax-categories/key={key}?version={version} -i \--header 'Authorization: Bearer ${BEARER_TOKEN}'
{"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"}