# Tax classes (Legacy)

{% hint style="danger" %}
As of April 2022, this concept has been marked as **legacy**.

To learn about the current tax classes concept, check out the [Tax classes guide](https://developer.emporix.io/ce/core-commerce/taxes-v2).
{% endhint %}

## Tax configuration

Tax categories (classes) are defined globally and apply to all sites within a tenant. They are stored under the `taxConfiguration` key in the [Emporix API Configuration Service](https://app.gitbook.com/s/d4POTWomuSS7d3dnh4Dg/api-guides/configuration/configuration-service).

<details>

<summary>JSON example</summary>

```json
{
  "key": "taxConfiguration",
  "value": {
    "taxClassOrder": [
      "FULL",
      "HALF",
      "ZERO"
    ],
    "taxClasses": {
      "FULL": 19,
      "HALF": 7,
      "ZERO": 0
    }
  }
}
```

</details>

By default, the following tax categories are configured:

* 19% (`FULL`)
* 7% (`HALF`)
* 0% (`ZERO`)

## Custom tax categories

You can update the default tax categories' names and values according to your business's needs.

{% hint style="warning" %}
If you intend to generate invoices through dedicated Emporix API services, you need to keep the original tax naming convention. However, you can still freely change the tax values according to the market in which your business operates.
{% endhint %}

Updating the tax configuration does not impact already placed orders or carts with tax values overwritten for individual line items.

## Relations between tax categories and other resources

Tax categories are closely linked to products and product prices. The influence of tax configurations on these resources is described in their respective sections.

### Products

Tax categories can be assigned to specific products for the purposes of accounting and invoice creation. There can be only one tax category assigned to a particular product.

A product's tax category is referenced in the `taxClass` field inside the `productCustomAttributes` mixin.

<details>

<summary>See an example of a product with the tax category assigned</summary>

```json
{
    "id": "61b779cff5758b79d5815890",
    "name": "Apple Juice",
    "metadata": {
        "mixins": {
            "productCustomAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/v1560527845/schemata/CAAS/productCustomAttributesMixIn-v38.json"
        }
    },
    "mixins": {
        "productCustomAttributes": {
            "taxClass": "HALF"
        }
    }
}
```

</details>

{% hint style="info" %}
To learn more about mixins and mixin schemas, check out the [Standard practices in Emporix API](https://app.gitbook.com/s/d4POTWomuSS7d3dnh4Dg/standard-practices/mixins).
{% endhint %}

### Prices

Currently, all prices in the Emporix e-commerce system are stored as gross values (regardless of the channel through which they had been configured). Net values are calculated based on products' gross prices and tax rates when you generate an invoice.

## Managing tax categories through Emporix API

{% hint style="danger" %}
API calls presented in the tutorials require authorization with a [service access token](https://app.gitbook.com/s/d4POTWomuSS7d3dnh4Dg/api-guides/authentication/oauth-service) and specific scopes. Required scopes are mentioned in each tutorial.

To learn more about authorization in Emporix API, check out the [Authorization and scopes guide](https://developer.emporix.io/ce/core-commerce/taxes-v2/broken-reference).
{% endhint %}

### How to check what tax rates are configured for your tenant

First, request a [service access token](https://app.gitbook.com/s/d4POTWomuSS7d3dnh4Dg/api-guides/authentication/oauth-service) with the `configuration.configuration_view` scope.

To retrieve your tenant's tax configuration, you need to call the [Retrieving a configuration](https://app.gitbook.com/s/d4POTWomuSS7d3dnh4Dg/api-guides/configuration/configuration-service) endpoint.

<details>

<summary>cURL example</summary>

```shell
curl --location --request GET 'https://api.emporix.io/configuration/{{tenant}}/configurations/taxConfiguration' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{service_access_token}}'
```

</details>

<details>

<summary>Response example</summary>

```json
{
  "key" : "taxConfiguration",
  "secured" : false,
  "value" : {
    "taxClassOrder" : [ "FULL", "HALF", "ZERO" ],
    "taxClasses" : {
      "FULL" : 19,
      "HALF" : 7,
      "ZERO" : 0
    }
  },
  "version" : 2
}
```

</details>

### How to change your tenant's tax categories

First, request a [service access token](https://app.gitbook.com/s/d4POTWomuSS7d3dnh4Dg/api-guides/authentication/oauth-service) with the `configuration.configuration_manage` scope.

To change your tenant's tax configuration, you need to call the [Updating a configuration](https://app.gitbook.com/s/d4POTWomuSS7d3dnh4Dg/api-guides/configuration/configuration-service) endpoint with updated tax categories in the request body.

<details>

<summary>cURL example</summary>

```shell

curl --location --request PUT 'https://api.emporix.io/configuration/{{tenant}}/configurations/taxConfiguration' \
--header 'Authorization: Bearer {{service_access_token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "key": "taxConfiguration",
    "value": {
        "taxClassOrder": [
            "FULL",
            "HALF",
            "ZERO"
        ],
        "taxClasses": {
            "FULL": 20,
            "HALF": 10,
            "ZERO": 0
        }
    }
}'

```

</details>

<details>

<summary>Response example</summary>

```json
{
  "key" : "taxConfiguration",
  "secured" : false,
  "value" : {
    "taxClassOrder" : [ "FULL", "HALF", "ZERO" ],
    "taxClasses" : {
      "FULL" : 20,
      "HALF" : 10,
      "ZERO" : 0
    }
  },
  "version" : 2
}
```

</details>

### How to assign a tax category to an existing product

First, request a [service access token](https://app.gitbook.com/s/d4POTWomuSS7d3dnh4Dg/api-guides/authentication/oauth-service) with the `configuration.configuration_manage` scope.

To assign a tax category to an existing product, you need to call the [Updating a product's details](https://app.gitbook.com/s/d4POTWomuSS7d3dnh4Dg/api-guides/products-labels-and-brands/product-service) endpoint with the tax category's name in the request body.

<details>

<summary>cURL example</summary>

```shell
curl --location --request PUT 'https://api.emporix.io/product/{{tenant}}/products/{{productId}}?partial=true' \
--header 'Authorization: Bearer {{service_access_token}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "mixins":{
        "productCustomAttributes":{
            "taxClass":"FULL"
        }
    },
    "metadata": {
        "mixins":{
            "productCustomAttributes":"https://res.cloudinary.com/saas-ag/raw/upload/schemata/productCustomAttributesMixIn.v29.json"
        }
    }
}'
```

</details>

<details>

<summary>Response example</summary>

```json
{
    "code": "OK",
    "status": 200,
    "message": "Operation succeeded"
}
```

</details>