Tax Categories define how Products are to be taxed in different countries.
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 ​DateTime​ | Date and time (UTC) the TaxCategory was initially created. |
createdBy ​BETACreatedBy​ | IDs and references that created the TaxCategory. |
lastModifiedAt ​DateTime​ | Date and time (UTC) the TaxCategory was last updated. |
lastModifiedBy ​BETA | IDs and references that last modified the TaxCategory. |
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
limit ​Int​ | Number of results requested. Default: 20 ​Minimum: 0 ​Maximum: 500 ​ |
offset ​Int​ | Number of elements skipped. Default: 0 ​Maximum: 10000 ​ |
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 ​ | tax-category Type of referenced resource. |
obj ​TaxCategory​ | Contains the representation of the expanded TaxCategory. Only present in responses to requests with Reference Expansion for TaxCategories. |
TaxCategoryResourceIdentifier
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 MinLength: id is absent.2 ​MaxLength: 256 ​Pattern: ^[A-Za-z0-9_-]+$ ​ |
typeId ​ | tax-category Type of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource. |
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 is the sum of all rates in Minimum: subRates .0 ​Maximum: 1 ​ |
includedInPrice ​Boolean​ | If true , 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. |
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
name ​String​ | Name of the SubRate. |
amount ​Float​ | Minimum: 0 ​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 Minimum: subRates are specified.
If subRates are specified, this field can be omitted or it must be the sum of amounts of all subRates .0 ​Maximum: 1 ​ |
includedInPrice ​Boolean​ | If true , 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. |
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. |
Get TaxCategory
Get TaxCategory by ID
view_products:{projectKey}
view_tax_categories:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
id String ​ | id of the TaxCategory. |
expand | The parameter can be passed multiple times. |
application/json
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": "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
view_products:{projectKey}
view_tax_categories:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
key String ​ | key of the TaxCategory. |
expand | The parameter can be passed multiple times. |
application/json
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": "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
view_products:{projectKey}
view_tax_categories:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
where | 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. Default: 20 ​Minimum: 0 ​Maximum: 500 ​ |
offset Int ​ | 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. |
application/json
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": "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
id
. Returns a 200 OK
status if the TaxCategory exists or a 404 Not Found
otherwise.view_products:{projectKey}
view_tax_categories:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
id String ​ | id of the TaxCategory. |
curl --head https://api.{region}.commercetools.com/{projectKey}/tax-categories/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Check if TaxCategory exists by Key
key
. Returns a 200 OK
status if the Tax Category exists or a 404 Not Found
otherwise.view_products:{projectKey}
view_tax_categories:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
key String ​ | key of the TaxCategory. |
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
200 OK
status if any TaxCategories match the query predicate, or a 404 Not Found
otherwise.view_products:{projectKey}
view_tax_categories:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
where | The parameter can be passed multiple times. |
curl --head https://api.{region}.commercetools.com/{projectKey}/tax-categories -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
Create TaxCategory
manage_products:{projectKey}
manage_tax_categories:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
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" : "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
{
"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
manage_products:{projectKey}
manage_tax_categories:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
id String ​ | id of the TaxCategory. |
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 will be 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": "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
manage_products:{projectKey}
manage_tax_categories:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
key String ​ | key of the TaxCategory. |
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 will be 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": "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. Must not be empty. |
{
"action": "changeName",
"name": "New 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 ​TaxRateDraft​ | Value to append to the rates array. |
{
"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 is required for this update action. |
taxRateKey ​String​ | Key of the TaxRate to replace.
Either taxRateId or taxRateKey is required for this update action. |
taxRate ​TaxRateDraft​ | 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 taxRateId or taxRateKey is required for this update action. |
taxRateKey ​String​ | Key of the TaxRate to remove.
Either taxRateId or taxRateKey is required for this update action. |
{
"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 ​ | key of the Project. |
id String ​ | id of the TaxCategory. |
version Int ​ | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
application/json
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": "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
manage_products:{projectKey}
manage_tax_categories:{projectKey}
region String ​ | Region in which the Project is hosted. |
projectKey String ​ | key of the Project. |
key String ​ | key of the TaxCategory. |
version Int ​ | Last seen version of the resource. |
expand | The parameter can be passed multiple times. |
application/json
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": "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"
}