Tax classes (Legacy)

Depending on the countries where your business operates, you need to configure relevant tax classes.

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.

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.

JSON example

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

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.

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.

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.

See an example of a product with the tax category assigned

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

To learn more about mixins and mixin schemas, check out the Standard practices in Emporix API.

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

API calls presented in the tutorials require authorization with a service access token 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.

How to check what tax rates are configured for your tenant

First, request a service access token with the configuration.configuration_view scope.

To retrieve your tenant's tax configuration, you need to call the Retrieving a configuration endpoint.

cURL example

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

Response example

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

How to change your tenant's tax categories

First, request a service access token with the configuration.configuration_manage scope.

To change your tenant's tax configuration, you need to call the Updating a configuration endpoint with updated tax categories in the request body.

cURL example

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

Response example

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

How to assign a tax category to an existing product

First, request a service access token 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 endpoint with the tax category's name in the request body.

cURL example

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

Response example

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