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 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`BETA CreatedBy	IDs and references that created the TaxCategory.
`lastModifiedAt` DateTime	Date and time (UTC) the TaxCategory was last updated.
`lastModifiedBy`BETA LastModifiedBy	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

PagedQueryResult with results containing an array of TaxCategory.

`limit` Int	Number of results requested. Default: `20`Maximum: `500`
`offset` Int	Number of elements skipped. Default: `0`Maximum: `10 000`
`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 identifier of the referenced TaxCategory.
`typeId` ReferenceTypeId	`"tax-category"` References a TaxCategory.
`obj` TaxCategory	Contains the representation of the expanded TaxCategory. Only present in responses to requests with Reference Expansion for TaxCategories.

TaxCategoryResourceIdentifier

ResourceIdentifier to a TaxCategory. Either 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 `id` is absent. MinLength: `2`MaxLength: `256`Pattern: `^[A-Za-z0-9_-]+$`
`typeId` ReferenceTypeId	`"tax-category"` References a TaxCategory.

TaxRate

This type is equivalent to TaxRate and TaxRateInput in the GraphQL API.

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

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

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:

200TaxCategoryasapplication/json

Request Example:cURL

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

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:

200TaxCategoryasapplication/json

Request Example:cURL

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

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.
`sort` Sort	The parameter can be passed multiple times.
`expand` Expansion	The parameter can be passed multiple times.
`limit` Int	Number of results requested. Default: `20`
`offset` Int	Number of elements skipped. Default: `0`
`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.

Response:

200TaxCategoryPagedQueryResponseasapplication/json

Request Example:cURL

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

HEAD

https://api.{region}.commercetools.com/{projectKey}/tax-categories/{id}

Checks if a TaxCategory exists for a given id. Returns a 200 OK status if the TaxCategory exists or a 404 Not Found otherwise.

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.

Response:

200

Request Example:cURL

curl --head https://api.{region}.commercetools.com/{projectKey}/tax-categories/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if TaxCategory exists by Key

HEAD

https://api.{region}.commercetools.com/{projectKey}/tax-categories/key={key}

Checks if a TaxCategory exists for a given key. Returns a 200 OK status if the Tax Category exists or a 404 Not Found otherwise.

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.

Response:

200

Request Example:cURL

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

HEAD

https://api.{region}.commercetools.com/{projectKey}/tax-categories

Checks if a TaxCategory exists for a given Query Predicate. Returns a 200 OK status if any TaxCategories match the Query Predicate, or a 404 Not Found otherwise.

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.

Response:

200

Request Example:cURL

curl --head 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:TaxCategoryDraftasapplication/json

Response:

201TaxCategoryasapplication/json

Request Example:cURL

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

201 Response Example: TaxCategoryjson

{
  "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

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:

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.

Response:

200TaxCategoryasapplication/json

Request Example:cURL

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

200 Response Example: TaxCategoryjson

{
  "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

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:

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.

Response:

200TaxCategoryasapplication/json

Request Example:cURL

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

200 Response Example: TaxCategoryjson

{
  "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.

Example: json

{
  "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_-]+$`

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

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

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

Response:

200TaxCategoryasapplication/json

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

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

Response:

200TaxCategoryasapplication/json

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