Moltin < You > TaxJar



Andrew Waters profile picture
Last updated: 25 Jan 2019

Why TaxJar and Moltin are a perfect match?

Moltin provides a flexible commerce API that allows you to add tax to items in your cart, whereas TaxJar provides a sales tax API for developers to get calculations for products.

 By integrating Moltin with TaxJar, you get a straightforward yet powerful tax calculation service.

For the purpose of demonstrating TaxJar and Moltin in action, this post will demonstrate how you can leverage both services to build a simple, flexible commerce experience with accurate tax accounting in no time.



Prerequisites



Before following along with building our tax solution, ensure you have the following:

  • A Moltin account (a 14 day trial is available).

  • A TaxJar account (a 30 day trial is available).

  • Some products for demo purposes (we will expand on this in the next section).



Demonstration Scenario


In this example, we will demonstrate how to calculate sales tax via TaxJar and integrate it with your Moltin cart.



We will use clothing as an example because the tax rules differ based on the state, city and item (pretax) cost, so it would allow us to explore different scenarios.



For example, if you are selling in New York City, then the following applies (in addition to others):



  • There is 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, so even if you buy two or more items that are worth more than $110 in total, you only pay tax on the items that individually cost more than $110.



In this example, we will create three products - one that costs exactly $110.00, one that costs $110.01 and one that costs $200 to see how taxes change.



At the end of the guide, you will have integrated sales tax properly, so every time your customer adds a product to the cart, the product shows a properly calculated tax applied on each cart item individually.

Tax Codes


TaxJars API has an endpoint that describes different tax categories. 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 Moltin.



To do this, we will use Moltin's custom data feature (Flows) which allows us to add an additional field to our products where we can store the TaxJar Category code. Then, when adding products to Moltin, you can be explicit about the tax that should be applied.



Nexus


The TaxJar API has an endpoint that returns nexus information which is crucial for calculating taxes correctly in the US. To learn more about how sales tax nexus rules work, I suggest you familiarize yourself with the TaxJar blog post on sales tax nexus.

  {
  
  "regions": [

    
    {

"country_code": "US",

"country": "United States",

"region_code": "NY",

"region": "New York"
    
    }
  ]

}



Setup

So, we need three products - one that costs $110.00, one that costs $110.11 and one that costs $200. They should have the same tax code - 20010 ("Clothing"). You can add these products to your Moltin store via the dashboard or via the API.



Using the API to create your custom flow and products


1. Get an access token:


  curl -X "POST" "https://api.moltin.com/oauth/access_token" \
     
     -d "client_id=XXXX" \
     
     -d "client_secret=XXXX" \
     
     -d "grant_type=client_credentials"


2. Create a product data flow:

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


3. Add the tax_code field (substitute the PRODUCT_FLOW_ID from the response in the previous call):

  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": [
"10040",
"19000",
"19001",
"19002",
"19003",
"19004",
"19005",
"19006",
"19007",
"19008",
"19009",
"20010",
"20041","30070",
"31000",
"40010",
"40020",
"40030",
"40050",
"40060",
"41000",
"51010",
"81100",
"81110",
"81120","81300","81310",
"99999"
]
      
         }
 
       ],
  
       "description": "The tax code for this product as a TaxJar category",
  
       "required": true,
  
       "unique": false,
  
       "default": "",
  
       "enabled": true,
  
       "order": 1,
  
       "omit_null": false,
  
       "relationships": {
      
         "flow": {
          
         "data": {
              
           "type": "flow",
              
           "id": "{PRODUCT_FLOW_ID}"
          
         }
      
       }
  
     }

   }
    
     }'

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


5. Add the tax_code field (substitute the CART_FLOW_ID from the response in the previous call):

  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": [
"10040",
"19000",
"19001",
"19002",
"19003",
"19004",
"19005",
"19006",
"19007",
"19008",
"19009",
"20010",
"20041","30070",
"31000",
"40010",
"40020",
"40030",
"40050",
"40060",
"41000",
"51010",
"81100",
"81110",
"81120","81300","81310",
"99999"
]
      
           }
 
           ],
  
           "description": "The tax code for this cart item as a TaxJar category",
  
           "required": true,
  
           "unique": false,
  
           "default": "",
  
           "enabled": true,
  
           "order": 1,
  
           "omit_null": false,
  
           "relationships": {
      
               "flow": {
          
               "data": {
              
                   "type": "flow",
              
                   "id": "{PRODUCT_FLOW_ID}"
          
               }
      
           }
  
       }

   }
    
     }'

6. Create your first product (with a price of $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"
  
  }
    
    }'


6. Create your second product (with a price of $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"
  
  }

    }'


8. Create your third product (with a price of $200.00):

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

    }'


9. (optionally) add some images to the products via the dashboard or the API.


As soon as the Product converts into a cart item, the appropriate tax-code will then be applied to it. The sample cart below shows you how tax is calculated for each cart item in the cart.

Running the demo site

For demonstration site, visit our GitHub repo. The demo is a basic webpage built using React and bootstrap. To run it locally, clone the GitHub repo and run:

  yarn install

yarn dev


This will start the server locally on localhost:3000, and you can see server side operations in your terminal window.




Let's build something amazing with Moltin