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. |
TaxCategoryKeyReference
key โStringโ | User-defined unique identifier of the referenced TaxCategory. |
typeId โ | tax-category Type of referenced resource. |
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
status if the TaxCategory exists, or a 404
status 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
status if the Tax Category exists, or a 404
status 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
status if any TaxCategories match the query predicate, or a 404
status 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"
}