Integrate TaxJar
Add tax to items in your cart and calculate taxes by integrating Elastic Path Commerce Cloud with TaxJar. TaxJar provides a sales tax API for developers to get calculations for products.
This guide shows you how to calculate sales tax through TaxJar and integrate it with your cart.
Prerequisites
If you want to follow along, you need the following items:
- A Commerce Cloud account and the Client ID and Client Secret of your store
- A TaxJar account
- Products with the
includes_taxsetting set totrue - An access token
Tax scenario overview
The guide uses clothing as an example, as the tax rules differ based on the state, city, and item (pretax) cost, so it allows us to demonstrate different use cases.
If you are selling in New York City, then the following tax rules apply:
- No sales tax on an item of clothing or footwear that costs less than $110.
- An item of clothing or footwear that costs more than $110 is subject to the full 8.875% tax rate.
- Sales tax is calculated per item. If you buy two or more items that are worth more than $110 in total, you pay tax only on the items that individually cost more than $110.
To illustrate the previously-specified rules and show how taxes change, we create three products:
- Product that costs exactly $110.00.
- Product that costs $110.01.
- Product that that costs $200.
Step-by-step walkthrough
Before integrating the TaxJar API, familiarize yourself with core sales tax concepts you need for integration. If you want to store nexus locations with Commerce Cloud, take a look at the "Store data from third-party integration" guide.
| Tax concept | TaxJar API endpoint | Commerce Cloud API integration |
|---|---|---|
| Tax codes | categories | Product custom data (Flows) to store TaxJar category code. |
| Nexus | nexus | Use the region object to pass a nexus location needed for tax calculation. |
Integrate TaxJar in three steps:
- Create Products Flow and add a tax_code Field to it.
- Create Cart Item Flow and add a tax_code Field to it.
- Apply appropriate tax codes to your Products. For example, use 20010 for clothes.
Create a Product data Flow
As tax can differ based on the type of product you are selling, the categories from that endpoint need to be married with the product stored in Commerce Cloud.
Create custom data for Products you added for your project to store the TaxJar Category code. When adding Products to Commerce Cloud, be explicit about the tax that should be applied.
curl -X POST "https://api.moltin.com/v2/flows" \
-H "Authorization: XXXX" \
-H "Content-Type: application/json" \
-d $'{
"data": {
"type": "flow",
"name": "Products",
"slug": "products",
"description": "Extends the default product object",
"enabled": true
}
}'
Add a tax code field
Add the tax_code field. This would be the tax code for the Product as a TaxJar category. Make sure to substitute the PRODUCT_FLOW_ID that was returned from the preceding request.
curl -X "POST" "https://api.moltin.com/v2/fields" \
-H "Authorization: XXXX" \
-H "Content-Type: application/json" \
-d $'{
"data": {
"type": "field",
"name": "Tax Code",
"slug": "tax_code",
"field_type": "string",
"validation_rules": [
{
"type": "enum",
"options": [...]
}
],
"description": "The tax code for this product as a TaxJar category",
"required": true,
"default": "",
"enabled": true,
"order": 1,
"omit_null": false,
"relationships": {
"flow": {
"data": {
"type": "flow",
"id": "PRODUCT-FLOW-ID"
}
}
}
}
}'
Create a cart item data flow
curl -X POST "https://api.moltin.com/v2/flows" \
-H "Authorization: XXXX" \
-H "Content-Type: application/json" \
-d $'{
"data": {
"type": "flow",
"name": "Cart Items",
"slug": "cart_items",
"description": "Extends the default cart item object",
"enabled": true
}
}'
Add a tax code field
Repeat the Add a tax code field step. This would be the tax code for the cart item as a TaxJar category. Make sure to substitute the PRODUCT_FLOW_ID with the response value you got from step 1.
Create Products and allocate tax codes
In the case of our Products (which come under tax category of clothes), the tax_code value is 20010.
Product that costs exactly $110.00
curl -X POST https://api.moltin.com/v2/products \
-H "Authorization: Bearer XXXX" \
-H "Content-Type: application/json" \
-d $'{
"data": {
"type": "product",
"name": "Hat",
"slug": "hat",
"sku": "hats.1",
"description": "A hat",
"manage_stock": false,
"price": [
{
"amount": 11000,
"currency": "USD",
"includes_tax": false
}
],
"status": "live",
"commodity_type": "physical",
"tax_code": "20010"
}
}'
Product that costs $110.01
curl -X POST https://api.moltin.com/v2/products \
-H "Authorization: Bearer XXXX" \
-H "Content-Type: application/json" \
-d $'{
"data": {
"type": "product",
"name": "Sweater",
"slug": "sweater",
"sku": "sweaters.1",
"description": "A sweater",
"manage_stock": false,
"price":
[
{
"amount": 11001,
"currency": "USD",
"includes_tax": false
}
],
"status": "live",
"commodity_type": "physical",
"tax_code": "20010"
}
}'
Product that that costs $200
curl -X POST https://api.moltin.com/v2/products \
-H "Authorization: Bearer XXXX" \
-H "Content-Type: application/json" \
-d $'{
"data": {
"type": "product",
"name": "Socks",
"slug": "socks",
"sku": "socks.1",
"description": "A pair of socks",
"manage_stock": false,
"price":
[
{
"amount": 20000,
"currency": "USD",
"includes_tax": false
}
],
"status": "live",
"commodity_type": "physical",
"tax_code": "20010"
}
}'
As soon as the Product converts into a cart item, the appropriate tax-code is applied to it.
Run the demo site
For demonstration site, visit our GitHub repo. The demo is a basic web page built using React and bootstrap. To run it locally, clone the GitHub repo and run:
yarn install
yarn dev
This starts the server locally on localhost:3000, and you can see server side operations in your terminal window.
Further reading
- Taxes
- Carts API - Tax Items
- Create tax rates
- TaxJar (External site)