Overview
The Tax service is used to create and manage tax codes as well as determine how taxes are to be calculated on an order. The service enables you to:
- Create a new tax code for a site.
- Retrieve tax codes.
- Delete tax codes.
- Update existing tax codes.
- Get the tax calculation for the items in the cart.
- Get VAT tax calculations to support European markets.
The Tax service calculates the tax for the items in the cart when the customer is ready to place their order. This service calculates the tax that you have previously set in the Site service and the tax codes you have set for specific products. For tax that is included in the unit price of the product, you can calculate the VAT tax. You can only set one flat rate and tax name per site for a given tenant, but you can set multiple tax codes for a single site code. If tax is not applicable for that site, leave the tax configuration empty. After the tax is calculated, the tax total is passed to the cart using the access token.
API Reference
/{tenant}/tax/quote
/{tenant}/tax/quote
Calculate the estimated tax amount for the items in the cart.
/{tenant}/tax/codes
This resourceType defines the GET, POST, DELETE methods and their responses for a collection resource.
/{tenant}/tax/codes
Retrieve all the tax codes.
Create a new tax code. The caller must have the hybris.tax_manage scope assigned.
/{tenant}/tax/codes/{id}
This resource type defines the GET, PUT, DELETE methods and their responses for a single element resource.
Retrieve the tax code information by using the tax code ID.
Update the tax code information. The caller must have the hybris.tax_manage scope assigned.
Delete the tax code. The caller must have the hybris.tax_manage scope assigned.
Tax Codes
The tax rate is typically set by configuring it in the Site service. This tax rate is associated with the site code. You can create different codes for different sites. However, there are cases in which a product may have a different tax rate than what has been set as the default tax rate. In these situations, you can create a tax code and apply it to specific products. If you have applied a tax code to a product, the tax code value overrides the tax rate that has been set for the site. You can create a tax code for a specific site and tenant.
When you create a tax code, a unique tax code ID and tax code YRN are created and returned. You can retrieve a specific tax code's detail by using the tax code ID. This returns a schema that contains the code, yrn, rate, name, and siteCode attributes.
Update a tax code
You can update the tax code schema for a specific tenant. To do this, you need the tax code ID that was created when you initially created the tax code. For a given ID, you can update these attributes:
- code
- name
- rate
- siteCode
When you are updating the tax code, you cannot complete a partial update.
The hybris-resource-version header is optional. It is only required if you have previously used it for other tax code update requests. To find the current version number, perform a request to retrieve the tax code details.
For an example of how to create, retrieve, update, and delete tax codes, see the Basics tutorial.
Sort and Pagination
After you have created all your tax codes, you can retrieve:
- All the tax codes for a specific tenant.
- The tax code(s) for a specific tax code ID or site code.
- A list of tax codes by querying multiple site codes or tax codes.
Once you have retrieved your list, you can arrange how to view the results. Sorting and paginating the tax codes allows you to view the results in an organized format and helps you find a specific code with ease.
Pagination is based on two parameters:
- page size (pageSize)
- page number (pageNumber)
The page size determines how many results are displayed on a single page, while the page number determines which page you are viewing (if the results span more than a single page). By default, if you do not specify a page size or page number, a GET request displays 1000 results per page and the results appear on page one first. If you set a page number, but no page size, it displays 16 results per page. If you set a page size, but no page number, the results of the first page are displayed.
You can also sort the results in ascending or descending order based on the following query parameters:
- tax code (code)
- site code (siteCode)
- tax code ID (id)
- tax code name (name)
- tax code rate (rate)
- tax code YRN (yrn)
If you select an attribute, but you do not specify the sort order, the results are sorted in ascending order by default.
Tax Service Configuration
Introduction
Prior to using the Tax service's calculations, you must configure the tax settings for all of the sites of a given tenant in the Site service. This tax setting is the default tax that is applied to all of your purchase orders.
Setup
The following sections show what you need to set up before you can execute any of the calls to this service.
Assertion
Define the variable assert:
assert = chai.assert;
Get an access token
To perform any operations with a specific service, you always need an access token. For this purpose, create an API Client for the oAuth2 service:
API.createClient('oAuth2Service',
'/services/oauth2/v1/api.raml');
Now, get the token:
tenant = projectIdPlaceholder;
AccessToken = oAuth2Service.token.post({
'client_id' : clientIdPlaceholder,
'client_secret':clientSecretPlaceholder,
'grant_type' : 'client_credentials',
'token_type': 'Bearer',
'scope': 'hybris.tenant='+tenant+ ' hybris.tax_manage hybris.site_manage'
});
To ensure the calls are simple and the code is clean, you need to assign the id of the returned object to a variable:
access_token = AccessToken.body.access_token;
Create an API client for the Tax service
API.createClient('taxService',
'/services/tax/v1/api.raml');
Create an API client for the Site service
API.createClient('siteService',
'/services/site/v1/api.raml');
Create a site
To configure a default tax rate, you need to first create a site. For this tutorial, create a canada site.
response = siteService.tenant(tenant).sites.post({
"code": "canada",
"name": "Canadian Site",
"active": false,
"default": false,
"defaultLanguage": "en",
"languages": [
"en",
"fr"
],
"currency": "CAD",
"homeBase": {
"address": {
"street": "Maisonneuve",
"streetNumber": "999",
"zipCode": "H3A 3L4",
"city": "Montreal",
"state": "Quebec",
"country": "CA"
}
}
}, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
});
assert.equal(response.status, 201);
response.body;
Tax configuration
To set the tax rate, you need to define the following five keys in the Site service public configuration:
- rate - Enter a tax percentage between 0 and 100, such as
19. - code - The default tax code for the given site, such as
VAT. - name - The tax name for the default tax code, such as
value added tax. - description - A custom message that describes what the default tax rate is. For example:
The standard sales tax rate in Germany is 19%.. - included - Indicates if the tax is already included in the unit price of each item provided. For countries that have VAT, you need to set this value to
true. The default value isfalse.
Use this information to configure the tax rate for the tenant's canada site. Refer to the Site documentation for additional information on how to configure the tax provider for your site.
response = siteService.tenant(tenant).sites.code('canada').tax.post({
"id": "FLATRATE",
"name": "Tax Service",
"serviceType": "urn:x-yaas:service:tax",
"serviceUrl": "https://api.beta.yaas.io/hybris/tax/v1",
"active": true,
"configuration": {
"public": {
"rate": 5,
"code": "GST",
"name": "goods and services tax",
"description": "The standard tax rate in Canada is 5%.",
"included": false
},
"restricted": null
}
},{
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
});
assert.equal(response.status, 201);
response.body;
Cleanup
Delete the site that was created for this project before you move on to another tutorial.
response = siteService.tenant(tenant).sites.code('canada').delete({}, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
}
);
assert.equal(response.status, 204);
response;
Basics
Introduction
This tutorial covers the basic operations that can be made to the Tax service tax codes: create, retrieve, update, and delete. In order to use the service, you must have the proper authorization. This can be achieved by injecting the access token into the header of the request.
Setup
The following sections show what you need to set up before you can execute any of the calls to this service.
Assertion
Define variable assert:
assert = chai.assert;
Get an access token
To perform any operations with a specific service, you always need an access token. For this purpose, create an API Client for the oAuth2 service:
API.createClient('oAuth2Service',
'/services/oauth2/v1/api.raml');
Now, get the token:
tenant = projectIdPlaceholder;
AccessToken = oAuth2Service.token.post({
'client_id' : clientIdPlaceholder,
'client_secret':clientSecretPlaceholder,
'grant_type' : 'client_credentials',
'token_type': 'Bearer',
'scope': 'hybris.tenant='+tenant+ ' hybris.tax_manage'
});
To ensure the calls are simple and the code is clean, you need to assign the id of the returned object to a variable:
access_token = AccessToken.body.access_token;
Create an API client for the Tax service
API.createClient('taxService',
'/services/tax/v1/api.raml');
Create new tax codes
Now create the tax codes to override the default tax rate.
response = taxService.tenant(tenant).tax.codes.post({
"code": "CAQC_GR_NT",
"siteCode": "CAD",
"name": "Canada Quebec No Tax on Groceries. GST/QST to 0%",
"rate": 0
},{
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
});
assert.equal(response.status, 201);
taxCodeId = response.body.id;
response.body;
response = taxService.tenant(tenant).tax.codes.post({
"code": "CAQC_LIQ_HT",
"siteCode": "CAQC2",
"name": "Canada Quebec Tax on liquor. GST/QST to 13.5% Cascading",
"rate": 13.5,
"yrn": "urn:yaas:hybris:tax:taxCode:{tenant};5405e6419a2ef90c6077bbbb"
},{
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
});
assert.equal(response.status, 201);
taxCodeId2 = response.body.id;
response.body;
Retrieve the tax codes
Retrieve all the tax codes to confirm that they were created properly.
response = taxService.tenant(tenant).tax.codes.get({}, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
});
assert.equal(response.status, 200);
response.body;
Update a tax code
If you need to update the value of the code, name, rate, or site code attribute, you can change one or all of the values by completing a full update. A partial update is not supported.
response = taxService.tenant(tenant).tax.codes.id(taxCodeId).put({
"code": "GR_NT",
"siteCode": "CAD_QC",
"name": "Groceries in Quebec",
"rate": 2
},{
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
});
assert.equal(response.status, 204);
response;
Use the tax code ID to retrieve the updated tax code and verify it was updated correctly.
response = taxService.tenant(tenant).tax.codes.id(taxCodeId).get({}, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
});
assert.equal(response.status, 200);
response.body;
Delete a tax code
Use the tax code ID to delete the tax code when it is no longer needed.
response = taxService.tenant(tenant).tax.codes.id(taxCodeId).delete({},{
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
});
assert.equal(response.status, 204);
response;
Retrieve all the tax codes to confirm that the one you deleted was removed.
response = taxService.tenant(tenant).tax.codes.get({}, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
});
assert.equal(response.status, 200);
response.body;
Cleanup
Delete the tax codes created for this project before you move on to another tutorials.
response = taxService.tenant(tenant).tax.codes.id(taxCodeId2).delete({}, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
}
);
assert.equal(response.status, 204);
response;
Querying
Introduction
You can query one or multiple parameteres to retrieve a specific tax code or a list of tax codes.
You can query all the tax codes for a specific tenant. This request is based on the hybris-tenant header and provides you with a list of all the tax codes created for that specific tentant.
You can query a specific tax code ID (which returns one tax code) or a site code (which returns all the tax codes for that site).
You can also query for one or multiple site codes and tax codes. To do this, you need the value(s) of the site code (siteCode) and tax code (code) parameters.
Setup
The following sections show what you need to set up before you can execute any of the calls to this service.
Assertion
Define the variable assert:
assert = chai.assert;
Get access token
To perform any operations with a specific service, you always need an access token. For this purpose, create an API Client for the oAuth2 service:
API.createClient('oAuth2Service',
'/services/oauth2/v1/api.raml');
Now, get the token:
tenant = projectIdPlaceholder;
AccessToken = oAuth2Service.token.post({
'client_id' : clientIdPlaceholder,
'client_secret':clientSecretPlaceholder,
'grant_type' : 'client_credentials',
'token_type': 'Bearer',
'scope': 'hybris.tenant='+tenant+ ' hybris.tax_manage'
});
To ensure the calls are simple and the code is clean, you need to assign the id of the returned object to a variable:
access_token = AccessToken.body.access_token;
Create an API client for the Tax service
API.createClient('taxService',
'/services/tax/v1/api.raml');
Create multiple tax codes
Create two tax codes for this tutorial.
response = taxService.tenant(tenant).tax.codes.post({
"code": "CAQC_GR_NT",
"siteCode": "CAQC",
"name": "Canada Quebec No Tax on Groceries. GST/QST to 0%",
"rate": 0,
"yrn": "urn:yaas:hybris:tax:taxCode:{tenant};5405e6419a2ef90c6077afdf"
},{
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
});
assert.equal(response.status, 201);
taxCodeId = response.body.id;
response.body;
response = taxService.tenant(tenant).tax.codes.post({
"code": "CAQC_LIQ_HT",
"siteCode": "CAQC2",
"name": "Canada Quebec Tax on liquor. GST/QST to 13.5% Cascading",
"rate": 13.5,
"yrn": "urn:yaas:hybris:tax:taxCode:{tenant};5405e6419a2ef90c6077bbbb"
},{
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
});
assert.equal(response.status, 201);
taxCodeId2 = response.body.id;
response.body;
Retrieve a tax code by querying multiple parameters
The following example shows you how to query for tax codes that match certain multiple site code and tax code parameters. The results show the two tax codes you previously created.
response = taxService.tenant(tenant).tax.codes.get({}, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
},
query: {
'code': 'CAQC_GR_NT'
}
});
assert.equal(response.status, 200);
response.body;
response = taxService.tenant(tenant).tax.codes.get({}, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
},
query: {
'siteCode': 'CAQC2'
}
});
assert.equal(response.status, 200);
response.body;
response = taxService.tenant(tenant).tax.codes.get({}, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
},
query: {
'code': 'CAQC_GR_NT, CAQC_LIQ_HT'
}
});
assert.equal(response.status, 200);
response.body;
Cleanup
Delete all of the tax codes before you move on to another tutorial.
response = taxService.tenant(tenant).tax.codes.id(taxCodeId).delete({}, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
}
);
assert.equal(response.status, 204);
response;
response = taxService.tenant(tenant).tax.codes.id(taxCodeId2).delete({}, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
}
);
assert.equal(response.status, 204);
response;
Pagination
Introduction
Once you have retrieved the list of tax codes from your GET request, you can paginate the results by assigning natural numbers to the query parameters pageSize and pageNumber. The page size determines how many results are displayed on a single page, while the page number determines which page you are viewing (if the results span more than a single page). Paginating lets you view a huge list of results in an organized manner. The paginate functionality can work in relation with the sort functionality.
For more information about pagination, see the Sort and Pagination page.
Setup
The following sections show what you need to set up before you can execute any of the calls to this service.
Assertion
Define variable assert:
assert = chai.assert;
Get access token
To perform any operations with a specific service, you always need an access token. For this purpose, create an API Client for the oAuth2 service:
API.createClient('oAuth2Service',
'/services/oauth2/v1/api.raml');
Now, get the token:
tenant = projectIdPlaceholder;
AccessToken = oAuth2Service.token.post({
'client_id' : clientIdPlaceholder,
'client_secret':clientSecretPlaceholder,
'grant_type' : 'client_credentials',
'token_type': 'Bearer',
'scope': 'hybris.tenant='+tenant+ ' hybris.tax_manage'
});
To ensure the calls are simple and the code is clean, you need to assign the id of the returned object to a variable:
access_token = AccessToken.body.access_token;
Create an API client for the Tax service
API.createClient('taxService',
'/services/tax/v1/api.raml');
Create multiple tax codes
To show how pagination works, you need to first create a few tax codes.
response = taxService.tenant(tenant).tax.codes.post({
"code": "CAQC_GR_NT",
"siteCode": "CAQC",
"name": "Canada Quebec No Tax on Groceries. GST/QST to 0%",
"rate": 0,
"yrn": "urn:yaas:hybris:tax:taxCode:{tenant};5405e6419a2ef90c6077afdf"
},{
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
});
assert.equal(response.status, 201);
taxCodeId = response.body.id;
response.body;
response = taxService.tenant(tenant).tax.codes.post({
"code": "CAQC_LIQ_HT",
"siteCode": "CAQC2",
"name": "Canada Quebec Tax on liquor. GST/QST to 13.5% Cascading",
"rate": 13.5,
"yrn": "urn:yaas:hybris:tax:taxCode:{tenant};5405e6419a2ef90c6077bbbb"
},{
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
});
assert.equal(response.status, 201);
taxCodeId2 = response.body.id;
response.body;
response = taxService.tenant(tenant).tax.codes.post({
"code": "CAQC_PR_TX",
"siteCode": "CAQC",
"name": "Canada Quebec Tax on merchandise. QST to 9.5%",
"rate": 9.5,
"yrn": "urn:yaas:hybris:tax:taxCode:{tenant};5405e6500a2ef90c6077bcdf"
},{
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
});
assert.equal(response.status, 201);
taxCodeId3 = response.body.id;
response.body;
response = taxService.tenant(tenant).tax.codes.post({
"code": "CAAB_MR_NT",
"siteCode": "CAAB",
"name": "Canada Alberta No Tax on Merchandise. QST to 0%",
"rate": 0,
"yrn": "urn:yaas:hybris:tax:taxCode:{tenant};5405e6419a2ef90c6078eetp"
},{
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
});
assert.equal(response.status, 201);
taxCodeId4 = response.body.id;
response.body;
response = taxService.tenant(tenant).tax.codes.post({
"code": "CABC_PR_TX",
"siteCode": "CABC",
"name": "Canada BC Tax on Merchandise. QST to 8.5%",
"rate": 8.5,
"yrn": "urn:yaas:hybris:tax:taxCode:{tenant};5405e6419a2ef90c6078nhrr"
},{
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
});
assert.equal(response.status, 201);
taxCodeId5 = response.body.id;
response.body;
Paginate the tax codes
After you retrieve a list of tax codes, you can determine how many results to view on a single page, and which page to view first. In this example, the results are organized to display two tax codes per page and to display the results of page two first.
response = taxService.tenant(tenant).tax.codes.get({}, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
},
query: {
'pageNumber': '2',
'pageSize': '2'
}
});
assert.equal(response.status, 200);
response.body;
Cleanup
Delete all the tax codes created for this project before you move on to another tutorial.
response = taxService.tenant(tenant).tax.codes.id(taxCodeId).delete({}, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
}
);
assert.equal(response.status, 204);
response;
response = taxService.tenant(tenant).tax.codes.id(taxCodeId2).delete({}, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
}
);
assert.equal(response.status, 204);
response;
response = taxService.tenant(tenant).tax.codes.id(taxCodeId3).delete({}, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
}
);
assert.equal(response.status, 204);
response;
response = taxService.tenant(tenant).tax.codes.id(taxCodeId4).delete({}, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
}
);
assert.equal(response.status, 204);
response;
response = taxService.tenant(tenant).tax.codes.id(taxCodeId5).delete({}, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
}
);
assert.equal(response.status, 204);
response;
Sorting
Introduction
The sorting feature lets you organize tax codes in alphabetical order which allows you to find a specific tax code with ease. You can sort the results in ascending (asc) or descending (desc) order based on a specified query parameter. If the sort order is not specified, the tax codes are sorted in ascending order. For more information on sorting, see the Sort and Pagination page.
Setup
The following sections show what you need to set up before you can execute any of the calls to this service.
Assertion
Define variable assert:
assert = chai.assert;
Get access token
To perform any operations with a specific service, you always need an access token. For this purpose, create an API Client for the oAuth2 service:
API.createClient('oAuth2Service',
'/services/oauth2/v1/api.raml');
Now, get the token:
tenant = projectIdPlaceholder;
AccessToken = oAuth2Service.token.post({
'client_id' : clientIdPlaceholder,
'client_secret':clientSecretPlaceholder,
'grant_type' : 'client_credentials',
'token_type': 'Bearer',
'scope': 'hybris.tenant='+tenant+ ' hybris.tax_manage'
});
To ensure the calls are simple and the code is clean, you need to assign the id of the returned object to a variable:
access_token = AccessToken.body.access_token;
Create an API client for the Tax service
API.createClient('taxService',
'/services/tax/v1/api.raml');
Create multiple tax codes
To show how sorting works, you need to first create a few tax codes.
response = taxService.tenant(tenant).tax.codes.post({
"code": "CAQC_GR_NT",
"siteCode": "CAQC",
"name": "Canada Quebec No Tax on Groceries. GST/QST to 0%",
"rate": 0,
"yrn": "urn:yaas:hybris:tax:taxCode:{tenant};5405e6419a2ef90c6077afdf"
},{
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
});
assert.equal(response.status, 201);
taxCodeId = response.body.id;
response.body;
response = taxService.tenant(tenant).tax.codes.post({
"code": "CAQC_LIQ_HT",
"siteCode": "CAQC2",
"name": "Canada Quebec Tax on Liquor. GST/QST to 13.5% Cascading",
"rate": 13.5,
"yrn": "urn:yaas:hybris:tax:taxCode:{tenant};5405e6419a2ef90c6077bbbb"
},{
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
});
assert.equal(response.status, 201);
taxCodeId2 = response.body.id;
response.body;
response = taxService.tenant(tenant).tax.codes.post({
"code": "CAQC_PR_TX",
"siteCode": "CAQC",
"name": "Canada Quebec Tax on merchandise. QST to 9.5%",
"rate": 9.5,
"yrn": "urn:yaas:hybris:tax:taxCode:{tenant};5405e6500a2ef90c6077bcdf"
},{
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
});
assert.equal(response.status, 201);
taxCodeId3 = response.body.id;
response.body;
response = taxService.tenant(tenant).tax.codes.post({
"code": "CAAB_MR_NT",
"siteCode": "CAAB",
"name": "Canada Alberta No Tax on Merchandise. QST to 0%",
"rate": 0,
"yrn": "urn:yaas:hybris:tax:taxCode:{tenant};5405e6419a2ef90c6078eetp"
},{
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
});
assert.equal(response.status, 201);
taxCodeId4 = response.body.id;
response.body;
response = taxService.tenant(tenant).tax.codes.post({
"code": "CABC_PR_TX",
"siteCode": "CABC",
"name": "Canada BC Tax on Merchandise. QST to 8.5%",
"rate": 8.5,
"yrn": "urn:yaas:hybris:tax:taxCode:{tenant};5405e6419a2ef90c6078nhrr"
},{
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
});
assert.equal(response.status, 201);
taxCodeId5 = response.body.id;
response.body;
Sort the tax codes
Sorting helps you find a specific element with ease.
In this example, the results are sorted in descending order based on the tax codes.
response = taxService.tenant(tenant).tax.codes.get({}, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
},
query: {
'sort': 'code:desc'
}
});
assert.equal(response.status, 200);
response.body;
Cleanup
Delete all the tax codes created for this project before you move on to another tutorial.
response = taxService.tenant(tenant).tax.codes.id(taxCodeId).delete({}, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
}
);
assert.equal(response.status, 204);
response;
response = taxService.tenant(tenant).tax.codes.id(taxCodeId2).delete({}, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
}
);
assert.equal(response.status, 204);
response;
response = taxService.tenant(tenant).tax.codes.id(taxCodeId3).delete({}, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
}
);
assert.equal(response.status, 204);
response;
response = taxService.tenant(tenant).tax.codes.id(taxCodeId4).delete({}, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
}
);
assert.equal(response.status, 204);
response;
response = taxService.tenant(tenant).tax.codes.id(taxCodeId5).delete({}, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
}
);
assert.equal(response.status, 204);
response;
Calculation
Introduction
This tutorial demonstrate how to use the calculation feature of tax service.
Setup
The following sections show what you need to set up before you can execute any of the calls to this service.
Assertion
Define variable assert:
assert = chai.assert;
Get access token
To perform any operations with a specific service, you always need an access token. For this purpose, create an API Client for the oAuth2 service:
API.createClient('oAuth2Service',
'/services/oauth2/v1/api.raml');
Now, get the token:
tenant = projectIdPlaceholder;
AccessToken = oAuth2Service.token.post({
'client_id' : clientIdPlaceholder,
'client_secret':clientSecretPlaceholder,
'grant_type' : 'client_credentials',
'token_type': 'Bearer',
'scope': 'hybris.tenant='+tenant+ ' hybris.tax_manage hybris.site_manage'
});
To ensure the calls are simple and the code is clean, you need to assign the id of the returned object to a variable:
access_token = AccessToken.body.access_token;
Create an API client for the Tax service
API.createClient('taxService',
'/services/tax/v1/api.raml');
Create an API client for the Site service
API.createClient('siteService',
'/services/site/v1/api.raml');
Create a site
To complete a tax calculation, you need to first create a site. For this tutorial, create a canada site.
response = siteService.tenant(tenant).sites.post({
"code": "canada",
"name": "Canadian Site",
"active": false,
"default": false,
"defaultLanguage": "en",
"languages": [
"en",
"fr"
],
"currency": "CAD",
"homeBase": {
"address": {
"street": "Maisonneuve",
"streetNumber": "999",
"zipCode": "H3A 3L4",
"city": "Montreal",
"state": "Quebec",
"country": "CA"
}
}
}, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
});
assert.equal(response.status, 201);
response.body;
Tax configuration
In order to use the calculation feature, you must configure the tax settings for the tenant's canada site. Since this is a Canadian site, the included attribute needs to be set to false (which means tax is not included in the product's price), or you can choose to exclude this attribute in the public configuraion.
response = siteService.tenant(tenant).sites.code('canada').tax.post({
"id": "FLATRATE",
"name": "Tax Service",
"serviceType": "urn:x-yaas:service:tax",
"serviceUrl": "https://api.beta.yaas.io/hybris/tax/v1",
"active": true,
"configuration": {
"public": {
"rate": 5,
"code": "FRT",
"name": "flat rate tax",
"description": "The standard sales tax rate in Quebec is 5%."
},
"restricted": null
}
},{
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
});
assert.equal(response.status, 201);
response.body;
Calculate the tax
Tax is calculated by applying the tax percentage (which is set in the Site service) to each item in the cart. If the item has a tax code associated with it, the tax is calculated by the rate assigned to the tax code. If discounts are added to the cart, you can define whether the discount is added before or after the tax. This needs to be set up using the calculationType attribute in the Cart Service. For more information on how to use this attribute, see the Discounts page in the Cart service documentation.
After the tax is calculated for each item, the totals are added together (totalTax) and passed to the cart.
response = taxService.tenant(tenant).tax.quote.post({
"date": "2015-01-11T14:00:00.000Z",
"currency": "CAD",
"siteCode": "canada",
"lineItems": [
{
"id": "id0",
"itemCode": "productA",
"quantity": 10,
"unitPrice": 15,
"productDescription": "8.5 x 11 hardcover notebook, 192 pages."
},
{
"id": "id1",
"itemCode": "productB",
"quantity": 2,
"unitPrice": 10,
"productDescription": "8.5 x 11 3-subject notebook, 300 pages."
}
]
},{
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
});
assert.equal(response.status, 200);
response.body;
This example does not show how taxes are calculated when there is an additional tax code. The following example shows a tax calculation with the tax rate and a single tax code.
Create a tax code
Before different tax rates can be calculated, you need to create a tax code to apply on a product in the cart. This tax code overrides the tax rate set in the Site service.
response = taxService.tenant(tenant).tax.codes.post({
"code": "HC_NB_NT",
"siteCode": "canada",
"name": "No Tax on hardcover notebooks.",
"rate": 0
},{
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
});
assert.equal(response.status, 201);
taxCodeId = response.body.id;
response.body;
Calculate the taxes with a tax code
Now perform the same tax calculation, except this time there is an additional tax code added to one of the items in the cart. The regular tax rate is only applied on one of the two items in this calculation.
response = taxService.tenant(tenant).tax.quote.post({
"date": "2015-01-11T14:00:00.000Z",
"currency": "CAD",
"siteCode": "canada",
"lineItems": [
{
"id": "id0",
"itemCode": "productA",
"quantity": 10,
"unitPrice": 15,
"taxCode": "HC_NB_NT",
"productDescription": "8.5 x 11 hardcover notebook, 192 pages."
},
{
"id": "id1",
"itemCode": "productB",
"quantity": 2,
"unitPrice": 10,
"productDescription": "8.5 x 11 3-subject notebook, 300 pages."
}
]
},{
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
});
assert.equal(response.status, 200);
response.body;
Cleanup
Delete the site and tax code created for this project before you move on to another tutorial.
response = siteService.tenant(tenant).sites.code('canada').delete({}, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
}
);
assert.equal(response.status, 204);
response;
response = taxService.tenant(tenant).tax.codes.id(taxCodeId).delete({}, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
}
);
assert.equal(response.status, 204);
response;
VAT Calculation
Introduction
This tutorial demonstrate how to use the VAT calculation feature of tax service.
Setup
The following sections show what you need to set up before you can execute any of the calls to this service.
Assertion
Define variable assert:
assert = chai.assert;
Get access token
To perform any operations with a specific service, you always need an access token. For this purpose, create an API Client for the oAuth2 service:
API.createClient('oAuth2Service',
'/services/oauth2/v1/api.raml');
Now, get the token:
tenant = projectIdPlaceholder;
AccessToken = oAuth2Service.token.post({
'client_id' : clientIdPlaceholder,
'client_secret':clientSecretPlaceholder,
'grant_type' : 'client_credentials',
'token_type': 'Bearer',
'scope': 'hybris.tenant='+tenant+ ' hybris.tax_manage hybris.site_manage'
});
To ensure the calls are simple and the code is clean, you need to assign the id of the returned object to a variable:
access_token = AccessToken.body.access_token;
Create an API client for the Tax service
API.createClient('taxService',
'/services/tax/v1/api.raml');
Create an API client for the Site service
API.createClient('siteService',
'/services/site/v1/api.raml');
Create a site
To complete a tax calculation, you need to first create a site. For this tutorial, create a germany site.
response = siteService.tenant(tenant).sites.post({
"code": "germany",
"name": "German Site",
"active": false,
"default": false,
"defaultLanguage": "en",
"languages": [
"en",
"de"
],
"currency": "EUR",
"homeBase": {
"address": {
"street": "Nymphenburger",
"streetNumber": "68",
"zipCode": "32587",
"city": "Munchen",
"state": "DE",
"country": "DE"
}
}
}, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
});
assert.equal(response.status, 201);
response.body;
Tax configuration
In order to use the calculation feature, you must configure the tax settings for the tenant's germany site. Since this is a VAT calculation, you must set the included attribute to true in the public configuration to ensure the taxes are included in the product's sale price.
response = siteService.tenant(tenant).sites.code('germany').tax.post({
"id": "VAT",
"name": "Tax Service",
"serviceType": "urn:x-yaas:service:tax",
"serviceUrl": "https://api.beta.yaas.io/hybris/tax/v1",
"active": true,
"configuration": {
"public": {
"rate": 19,
"code": "VAT",
"name": "VAT tax",
"description": "The standard sales tax rate in Germany is 19%.",
"included": true
},
"restricted": null
}
},{
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
});
assert.equal(response.status, 201);
response.body;
Calculate the VAT tax
VAT is a tax that is included in the sale price of the product. To calculate how much tax the customer is paying, you need to figure out how much of the sale price is actually the tax. This calculation is based on the rate that you set for a given site, or on the tax code that you created to override the site rate.
If a discount is added to the cart, you can define how the discount is applied (before or after the taxes are calculated). When a discount is added to the cart, there is the calculationType attribute in the discount schema which determines if the discount is applied before or after taxes. You can set the value to ApplyDiscountBeforeTax (the default value), or ApplyDiscountAfterTax. Since VAT taxes are included in the product's sale price, the discount can only be applied after taxes. Therefore if you try to apply the discount before the tax, it will automatically default to apply the discount after the tax. For more information on how to use this attribute, see the Discounts page in the Cart service documentation.
Once the tax is calculated for each item in the cart, the amounts are added together and the total (totalTax) is passed to the cart.
response = taxService.tenant(tenant).tax.quote.post({
"date": "2015-01-11T14:00:00.000Z",
"currency": "CAD",
"siteCode": "canada",
"lineItems": [
{
"id": "id0",
"itemCode": "productA",
"quantity": 10,
"unitPrice": 15,
"productDescription": "8.5 x 11 hardcover notebook, 192 pages."
},
{
"id": "id1",
"itemCode": "productB",
"quantity": 2,
"unitPrice": 10,
"productDescription": "8.5 x 11 3-subject notebook, 300 pages."
}
]
},{
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
});
assert.equal(response.status, 200);
response.body;
This example does not show a tax calculation when there is an additional tax code. The following example shows a tax calculation with the tax rate and a single tax code.
Create a tax code
Before different tax rates can be calculated, you need to create a tax code to apply on a product in the cart. This tax code overrides the tax rate set in the Site service.
response = taxService.tenant(tenant).tax.codes.post({
"code": "HC_NB_NT",
"siteCode": "germany",
"name": "No tax on hardcover notebooks.",
"rate": 0
},{
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
});
assert.equal(response.status, 201);
taxCodeId = response.body.id;
response.body;
Calculate the VAT tax with a tax code
Now perform the same tax calculation, except this time there is an additional tax code added to one of the items in the cart. The regular tax rate is only applied on one of the two items in this calculation.
response = taxService.tenant(tenant).tax.quote.post({
"date": "2015-01-11T14:00:00.000Z",
"currency": "EUR",
"siteCode": "germany",
"lineItems": [
{
"id": "id0",
"itemCode": "productA",
"quantity": 10,
"unitPrice": 15,
"taxCode": "HC_NB_NT",
"productDescription": "8.5 x 11 hardcover notebook, 192 pages."
},
{
"id": "id1",
"itemCode": "productB",
"quantity": 2,
"unitPrice": 10,
"productDescription": "8.5 x 11 3-subject notebook, 300 pages."
}
]
},{
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
});
assert.equal(response.status, 200);
response.body;
Cleanup
Delete the site and tax code created for this project before you move on to another tutorial.
response = siteService.tenant(tenant).sites.code('germany').delete({}, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
}
);
assert.equal(response.status, 204);
response;
response = taxService.tenant(tenant).tax.codes.id(taxCodeId).delete({}, {
headers: {
'Authorization': 'Bearer ' + access_token,
'Content-Type' : 'application/json'
}
}
);
assert.equal(response.status, 204);
response;
Error Codes
For more information about error codes, see the API Reference.
Glossary
| Term | Description |
|---|---|
| cart | A location where a customer keeps the items they want to purchase. |
| item | An object that is in the cart. |
| product | An object that belongs to the store. |
| site | A location that the store is based on. Typically the site is based on a country, for example Canada. |
| site code | A code you assign to represent a specific site, such as "US" for the United States. The site code is configured in the Site service. |
| tax | An amount that is paid to a governing body for the sale of certain goods and services. This amount is charged to the customer at the point of purchase. |
| tax code | A code created in the Tax service that is then assigned to a product. |
| VAT | A Value Added Tax added to a product"s price. This tax is included in the product"s sale price. |
If you find any information that is unclear or incorrect, please let us know so that we can improve the Dev Portal content.
Use our private help channel. Receive updates over email and contact our specialists directly.
If you need more information about this topic, visit hybris Experts to post your own question and interact with our community and experts.