Blog • Flows | Integrations

Store data form third party integration with Flows

Last updated: 05 Jul 2019

Store nexus locations from a tax calculation service using Flows.

Prerequisites

  • Moltin account (you'll need Client ID and Client Secret of your store).
  • At least one product added to the store.
  • Integrated tax calculation service, e.g. TaxJar.

Scenario overview

This guide covers the scenario in which you have integrated a tax calculation service with Moltin, and would like to store nexus locations that would be then added to a cart to calculate the correct tax rate.

The scenario does not cover tax categories which you may be required to add to your products. For more information, refer to the TaxJar integration guide.

Summary of steps required

  1. Create a custom Flow to store nexus location.
  2. Add Flow Fields to store location details like country, state, zip code, etc.
  3. Create Entries for nexus locations you need for your store.
  4. Extend the carts resource with the core Flow carts.
  5. Create a nexus relationship field that links to the carts Flow.

Update checkout flow:

  1. Get a cart.
  2. Add a cart item.
  3. Add checkout logic to call nexus Flow and select the appropriate nexus.
  4. Send nexus details to tax calculator API like TaxJar. The API will send back the tax rate.
  5. Add a tax item that includes the tax rate.
  6. Update the cart with nexus location.

Get your access token

You will need to get a client_credentials access token to follow along making the API requests outlined below.

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

Create a custom Flow to store nexus

We'll start with creating a custom Flow that will store nexus locations.

curl -X POST https://api.moltin.com/v2/flows \ 
     -H "Authorization:XXXX" \ 
     -H "Content-Type:application/json" \ 
     -d $'{  
        "data":{  
          "type":"flow",
          "name":"Nexus",
          "slug":"nexus",
          "description":"Creates a new object",
          "enabled":true
        }
     }'

Create Fields to store nexus location details

The Fields will be returned when you call the object you've created. ReplaceFLOW-ID with the ID that was generated for the Flow. In this scenario we will create three fields:Country, State and Zip which are required to be passed to TaxJar API. Repeat the request for the State and Zip field, changing the details accordingly.

curl -X POST https://api.moltin.com/v2/fields \
     -H "Authorization: XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
      "data": {
        "type": "field",
        "name": "Country",
        "slug": "country",
        "field_type": "string",
        "description": "Country name",
        "required": false,
        "unique": false,
        "default": 0,
        "enabled": true,
        "order": 1,
        "relationships": {
            "flow": {
                "data": {
                    "type": "flow",
                    "id": "NEXUS-FLOW-ID"
                }
            }
        }
      }
    }'

Create nexus locations Entries

Entries represent the actual content each Field will contain. Create an Entry for every Field added. In this example, we will add Entries to the Nexus Flow Fields we created above. These were Country, State and Zip.

curl -X POST https://api.moltin.com/v2/flows/:flowSlug/entries \
     -H "Authorization: XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
       "data": {
         "type": "entry",
         "country": "Canada",
         "state": "Indiana",
         "zip": "46077"
       }
     }'

Create a core Flow for carts

Create a new core Flow that will extend your carts resource. Note that slug must match the plural name of the resource you're extending, i.e.carts.

If you already have a Flow for your existing resource, skip this step. You'll need the ID of the carts Flow to continue.

curl -X POST https://api.moltin.com/v2/flows \
     -H "Authorization: XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
        "data": {
          "type": "flow",
          "name": "carts",
          "slug": "carts",
          "description": "flow description",
          "enabled": true
        }
     }'

Create a nexus relationship Field

Now it's time to create a relationship between the Nexus Flow and the carts Flow. To do this, we need to add a relationship type of a field_type.

curl -X POST https://api.moltin.com/v2/flows \
     -H "Authorization: XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
     	"data":{  
   	  "type":"field",
   	  "name":"Nexus",
   	  "slug":"nexus",
   	  "description":"Nexus location",
   	  "required":false,
   	  "unique":false,
   	  "field_type":"relationship",
   	  "relationships":{  
      	    "flow":{  
              "data":{  
            	 "type":"flow",
            	 "id":"CARTS-FLOW-ID"
                       }
      		     }
   		   },
   	   "validation_rules": [{  
             "type":"one-to-one",
             "to":"nexus"
      }]
   }'

Update the checkout flow

You've just created custom fields to store your nexus locations. Now it's time to update your checkout flow so that you can add it to your cart to apply the correct state tax.

Get a cart

curl -X POST https://api.moltin.com/v2/carts/:carts-reference \
     -H "Authorization: XXXX" 

Add a cart item

This scenario assumes that you have already set up at least one product, so that you can add it to the cart. You'll need the PRODUCT_ID and the :cart-reference from previous step.

curl -X POST https://api.moltin.com/v2/carts/:cart-reference/items \
     -H "Authorization: Bearer XXXX" \
     -H "Content-Type: application/json" \
     -d $'{
      "data": {
          "id": "PRODUCT-ID",
          "type": "cart_item",
          "quantity": 1
        }
      }'

Add checkout logic to communicate with a tax calculator API

Add checkout logic to call nexus Flow and select the appropriate nexus. Then, send nexus details to the tax calculator API like TaxJar, so that the API sends you back the tax rate.

Take a look at this GitHub example on how the logic was resolved in React.

Add a tax item

This is the part where you apply the rate returned by the tax calculator API to your cart item.

curl -X POST https://api.moltin.com/v2/carts/:cart-reference/items/:item-id/taxes \
    -H "Content-Type: application/json" \
    -H "Authorization: XXXX" \
    -d $'{
        "data": {
            "type": "tax_item",
            "name": "TaxJar tax rate",
            "jurisdiction" : "US",
            "code": "MYTAX01",
            "rate": 0.2
        }
    }'

Update the cart with nexus location

Opitonally, you can update your cart so that it displays which nexus location was used for transaction, should you require this type of informaiton for reporting purposes. You'll need the ENTRY-ID of the nexus location you used. In this case we only had one entry for the state of Indiana.

curl -X POST https://api.moltin.com/v2/carts/:cart-reference/relationship/nexus \
    -H "Content-Type: application/json" \
    -H "Authorization: XXXX" \
    -d $'{
        "data": {
            "id": "NEXUS-ENTRY-ID",
            "type": "nexus"
        }
    }'

The response will now include the details of the nexus location applied to the cart.

Further reading