Tax Service

Download OpenAPI specification:Download

E-mail: documentation@emporix.com

Create, manage and update tax (VAT, Sales Tax, Mwst) and tax classes.

Key Features:

  • Manage an unlimited number of tax classes - for example full (19%), reduced (7%), and nil (0%) - for different jurisdictions, such as countries. This model is applicable to the majority of European countries, including the United Kingdom (for countries with more complex tax requirements, we recommend using an external tax calculation service provider).
  • Create, manage and delete tax classes
  • Associate tax classes with countries
  • Calculate the tax that is either included in a gross price or that should be added to a net price
  • Calculate the correct tax depending on where a product is shipped to
  • Localize tax class names

Key Benefits:

  • Flexible definition of tax classes applicable to your products and services
  • Tax classes can be defined for different countries, each country may have its own set of tax classes
  • Associate classes with products to accurately reflect the tax they are attracting in a country
  • Display products with their net or gross prices
  • Correctly calculate tax applicable to where you ship a product
  • No additional costs for subscribing to an external tax calculation provider (for more complex tax requirements, however, we recommend using an external tax service calculator)
  • Support for an unlimited number of tax classes

Taxes

Creating a new tax configuration

Creates a new tax configuration.

Required scopes

  • tax.tax_manage
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

header Parameters
Content-Language
required
string

Language in which localized fields in the request body are provided.

  • If the Content-Language header is set to *, the localized fields should be provided as maps of translations, where the keys are language codes and values are the fields in their respective languages.
  • If the Content-Language header is set to a specific language, the localized fields should be provided as strings.
  • If the Content-Language header is empty, the endpoint will asume that the localized fields are provided in the default language defined in the Configuration Service.

Note: You can provide the localized fields only in languages defined in the Configuration Service. In case the fields are provided in languages that are not defined in the Configuration Service, the request will be rejected.

Request Body schema: application/json
required
object (location)
required
Array of objects (taxClass)

List of tax classes applicable in the specified country.

Responses
201

The request was successful. The tax configuration has been created.

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

409

Conflict

500

Internal Service Error occurred.

post/{tenant}/taxes
Request samples
application/json
{
  • "location": {
    },
  • "taxClasses": [
    ]
}
Response samples
application/json
{
  • "locationCode": "string"
}

Retrieving all tax configurations

Retrieves all tax configurations assigned to the tenant. You can filter the results with query parameters.

Required scopes

  • tax.tax_read
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

query Parameters
pageNumber
integer >= 1
Default: 1

Page number to be retrieved. The number of the first page is 1.

Note: If the pageNumber parameter is passed, size of the pages must be specified in the pageSize parameter.

pageSize
integer >= 1
Default: 60

Number of items to be retrieved per page.

sort
string

List of properties used to sort the results, separated by colons. The order of properties indicates their priority in sorting.

Possible values:

  • {fieldName}
  • {fieldName:asc
  • {fieldName}:desc

Note: If you want to sort the results by localized properties, the possible values are:

  • {fieldName}.{language}
  • {fieldName}.{language}:asc
  • {fieldName}.{language}:desc

If the sorting direction is not specified, the fields are sorted in ascending order.

Possible {fieldName} values are:

  • name
  • description
  • countryCode
  • taxClassCode
  • rate
Example: sort=name,taxClassCode:desc
name
string

Tax class names. When specified, only tax configurations containing the specified tax class names will be returned.

Important: See how the Accept-Language header influences this parameter:

  • If The Accept-Language header is set to *, you need to specify a language in this parameter.

    For example, if the Accept-Language header is set to * and you want to find English names containing the word "Reduced", this parameter should be set to "name.en=Reduced"

  • If the Accept-Language header is set to a particular language or not specified, you do not need to specify a language in this parameter.

    For example, if the Accept-Language header is set to en and you want to find names containing the word "Reduced", this parameter should be set to "name=Reduced"

Note: When filtering the results with this field, the contains operator is used. The operator is case-sensitive.

rate
string

Tax class rates, expressed as numbers. When specified, only tax configurations containing the specified tax class rates will be returned.

Note: When filtering the results with this field, the equals operator is used.

countryCode
string

Three-letter country codes, as defined in the Country Service. When specified, only tax configurations defined for the specified countries will be returned.

Note: When filtering the results with this field, the contains operator is used. The operator is case-sensitive.

taxClassCode
string

Tax class codes. When specified, only tax configurations containing the specified tax class codes will be returned.

Note: When filtering the results with this field, the contains operator is used. The operator is case-sensitive.

description
string

Tax class descriptions. When specified, only tax configurations containing the specified tax class descriptions will be returned.

Important: See how the Accept-Language header influences this parameter:

  • If The Accept-Language header is set to *, you need to specify a language in this parameter.

    For example, if the Accept-Language header is set to * and you want to find English descriptions containing the word "Fruit", this parameter should be set to "description.en=Fruit"

  • If the Accept-Language header is set to a particular language or not specified, you do not need to specify a language in this parameter.

    For example, if the Accept-Language header is set to en and you want to find descriptions containing the word "Fruit", this parameter should be set to "description=Fruit"

Note: When filtering the results with this field, the contains operator is used. The operator is case-sensitive.

header Parameters
Accept-Language
string

List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields.

  • If the header is set to a particular language or a list of languages, all localized fields are retrieved as strings.
  • If the header is set to *, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.
  • If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.
Example: fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7
X-Total-Count
boolean
Default: false

Flag indicating whether the total number of retrieved items should be returned.

Responses
200

The request was successful. A list of tax configurations is returned.

401

Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

500

Internal Service Error occurred.

get/{tenant}/taxes
Request samples 
Response samples 
application/json
[
  • {
    },
  • {
    }
]
Retrieving a tax configuration
Retrieves a tax configuration for a specified location.




Required scopes


    

  • tax.tax_read
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
locationCode
required
string
Location's country code, defined when the tax configuration is created.


 
header Parameters
Accept-Language
string
List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields.


    

  • If the header is set to a particular language or a list of languages, all localized fields are retrieved as strings.
    • 

  • If the header is set to *, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.
    • 

  • If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.
    • 



 
 Example:  fr-CH, fr;q=0.9, en;q=0.8, de;q=0.7
Responses 
200
The request was successful. The tax configuration is returned.


401
Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.


403
Given authorization scopes are not sufficient and do not match scopes required by the endpoint.


404
Resource has not been found.


500
Internal Service Error occurred.


get/{tenant}/taxes/{locationCode}
Request samples 
Response samples 
application/json
{
  • "location": {
    },
  • "taxClasses": [
    ],
  • "metadata": {
    }
}
Updating a tax configuration
Updates a tax configuration based on the specified location code.


Note: The tax configuration's identifier - the country code - is immutable and cannot be changed using this endpoint.




Required scopes


    

  • tax.tax_manage
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
locationCode
required
string
Location's country code, defined when the tax configuration is created.


 
header Parameters
Content-Language
required
string
Language in which localized fields in the request body are provided.


    

  • If the Content-Language header is set to *, the localized fields should be provided as maps of translations, where the keys are language codes and values are the fields in their respective languages.
    • 

  • If the Content-Language header is set to a specific language, the localized fields should be provided as strings.
    • 

  • If the Content-Language header is empty, the endpoint will asume that the localized fields are provided in the default language defined in the Configuration Service.
    • 



Note: You can provide the localized fields only in languages defined in the Configuration Service. In case the fields are provided in languages that are not defined in the Configuration Service, the request will be rejected.


 
Request Body schema: application/json
required
object (location) 
 
required
Array of objects (taxClass) 
List of tax classes applicable in the specified country.


 
required
object (metadata) 
 
Responses 
204
The request was successful. The tax configuration has been updated.


400
Request was syntactically incorrect. Details will be provided in the response payload.


401
Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.


403
Given authorization scopes are not sufficient and do not match scopes required by the endpoint.


404
Resource has not been found.


409
Conflict


500
Internal Service Error occurred.


put/{tenant}/taxes/{locationCode}
Request samples 
application/json
{
  • "location": {
    },
  • "taxClasses": [
    ],
  • "metadata": {
    }
}
Response samples 
application/json
{
  • "code": 400,
  • "status": "Bad Request",
  • "message": "Tenant in the header is not matching with the one provided in the URI."
}
Deleting a tax configuration
Deletes a tax configuration based on the specified location code.




Required scopes


    

  • tax.tax_manage
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
locationCode
required
string
Location's country code, defined when the tax configuration is created.


 
Responses 
204
The request was successful. The tax configuration has been deleted.


401
Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.


403
Given authorization scopes are not sufficient and do not match scopes required by the endpoint.


500
Internal Service Error occurred.


delete/{tenant}/taxes/{locationCode}
Request samples 
Response samples 
application/json
{
  • "fault": {
    }
}
Tax calculation
Calculating net and gross values for prices
Supports the following calculation operations for prices:


    

  • Net to gross values
    • 

  • Gross to net values
    • 

  • Gross values in one country to gross values in another country
    • 



Note: This endpoint calculates net and gross values for prices based on existing tax configurations. To use this endpoint, you need to create tax configurations first.


    

  • To calculate gross values beetween countries, you need to create tax configurations for both countries.
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
Your Emporix tenant's name.


Note: The tenant should always be written in lowercase.


 
Request Body schema: application/json
commandUuid
string
Calculation command's unique identifier.


Note: This field is optional. If not specified, the commandUuid will be generated by the server.


 
required
object
Information based on which the price will be calculated.


 
Responses 
200
The request was successful. The calculated value is returned.


400
Request was syntactically incorrect. Details will be provided in the response payload.


401
Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.


403
Given authorization scopes are not sufficient and do not match scopes required by the endpoint.


500
Internal Service Error occurred.


put/{tenant}/taxes/calculation-commands
Request samples 
application/json
{
  • "input": {
    }
}
Response samples 
application/json
{
  • "commandUuid": "cb0d5627-08ef-4de9-a676-a254a4311261",
  • "input": {
    },
  • "output": {
    }
}