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

TaxCategoryDraft

TaxCategoryPagedQueryResponse

TaxCategoryReference

TaxCategoryResourceIdentifier

TaxRate

SubRate

TaxRateDraft

TaxCategory

`id` String	Unique ID of the TaxCategory.
`version` Int	Current version of the TaxCategory.
`key` String	User-defined unique identifier for the TaxCategory. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`createdAt` DateTime	Date and time (UTC) the TaxCategory was initially created.
`createdBy`BETA CreatedBy	Present on resources created after 1 February 2019 except for events not tracked.
`lastModifiedAt` DateTime	Date and time (UTC) the TaxCategory was last updated.
`lastModifiedBy`BETA LastModifiedBy	Present on resources created after 1 February 2019 except for events not tracked.
`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 assigned by the platform.

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 in the query request.
`offset` Int	Offset supplied by the client or the server default. It is the number of elements skipped, not a page number.
`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

Reference to a TaxCategory.

`id` String	Unique ID of the referenced TaxCategory.
`typeId` String	`"tax-category"`
`obj` TaxCategory	Contains the representation of the expanded TaxCategory. Only present in responses to requests with Reference Expansion for TaxCategory.

TaxCategoryResourceIdentifier

ResourceIdentifier to a TaxCategory.

`id` String	Unique ID of the referenced TaxCategory. Either `id` or `key` is required.
`key` String	Unique key of the referenced TaxCategory. Either `id` or `key` is required. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`typeId` String	`"tax-category"`

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 Prices and the `taxedPrice` is present on LineItems. In this case, the platform calculates the `totalNet` price based on 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 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	Set to `true`, if tax should be included in Prices and the `taxedPrice` should be present on Line Items. In this case, the platform calculates the `totalNet` price based on 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 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

Expansion

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}'

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:

200TaxCategory

Request Example:cURL

curl -X GET https://api.{region}.commercetools.com/{projectKey}/tax-categories/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'

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.
`/^var[.][a-zA-Z0-9]+$/` Any string parameter matching this regular expression	Predicate parameter values. 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` Int	Number of results returned.
`offset` Int	Number of results 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}'

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: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

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:

`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` Array of TaxCategoryUpdateAction	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

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:

`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` Array of TaxCategoryUpdateAction	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

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

`key` String	Value to set. If empty, any existing value will be removed. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`action` String	`"setKey"`

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` 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.
`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.

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:

`expand` Expansion	The parameter can be passed multiple times.
`version` Int	Last seen version of the resource.

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}'

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:

`expand` Expansion	The parameter can be passed multiple times.
`version` Int	Last seen version of the resource.

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}'