Overview



This guide describes how to integrate Route into your platform so you can provide Route as an insurance option to your merchants. After integrating Route, you will be able to:

 

  • Offer Route shipping protection as an option 

  • Process Route charges in your order management system

  • Display Route promotional messaging



Integration Steps
 
  1. Obtain your Route API Key

  2. Load up Stores

  3. Order Processing Setup 

  4. Embed Route.js

  5. Test Integration

  6. Deploy to Production



1. Obtain your Route API Key



A. Create an Account

You can create an account by clicking here




RouteDesktopGraphMockup.png







Screen Shot 2018-10-11 at 4.25.26 PM.png






B. Grab your API Key

On the top of your screen, go to your Admin, then Account Details. 




DashAccountDetails.png




You can access your API Key on the top right. Copy your API Key for use in requests.




RouteGetAPIKey.png




B. Get your Platform Identifier

Before the ability to move forward with Route, you will need to contact our development team to receive the "platform identifier". We can be reached at tech@routeapp.io



2. Load Up Store(s)



You will need to add your existing test store(s), current live stores, and write a script for new stores who will join your platform.



A. Add Test/Existing Stores

In order for Route to provide correct reporting, we will need to load up at least 1 test store you use on your platform. We will also need you to load in your live stores for production (we will use this info so that stores are already loaded when moving to production). To do this, please send us a CSV file with the following: 

  • Test Store URL's (need at least 1 for testing)

  • Live Store URL's - This includes all stores that will use route when pushed to production

 

Alternatively, you can write a script to send us this information

Iterate through existing merchants and post them to our store endpoint.

POST https://public.test.routeapp.io/v1.3/custom/store

Keep the response you receive from this endpoint  






{
  "api_key": {
    "key": "string",
    "platform_identifier": "string"
  },
  "merchant_create_request": {
    "address": {Optional},
    "name": "{Name of the Merchant}",
    "owner": {
      "email": "{Email for merchant/admin}",
      "first_name": "{Contact/admin first name}",
      "last_name": "{Contact/admin last name}",
      "phone": "{Phone number -- optional}",
    },
    "url": "{Must be included for routing}"
  }
}





B. Add New Stores

In order for Route to work on all future merchants who become active on your platform, you will have to add them. You will use the same POST request as above. 



3. Order Processing Setup



There are 3 universal requests that are made upon each checkout. 

A. Request a quote

B. Send in an order

C. Update order with tracking



A. Request a quote

POST https://public.test.routeapp.io/v1.3/custom/quote

Keep the response you receive from this endpoint for the next endpoint.





{
  "api_key": {
    "key": "{your route api key goes here}",
    "platform_identifier": "{your unique route generated platform identifier}",
    "store_identifier": "{your unique route generated store's identifier}"
  },
  "transaction": {
    "currency": "USD",
    "line_items": [
      {
        "discount": "SPECIAL",
        "price": 19.99,
        "price_before_discount": 21.99,
        "product": {
          "desc": "A wonderful Black T shirt. Egyptian cotton. ...",
          "insurable": true,
          "name": "Black T shirt",
          "picture_uri": "https://example.com/assets/",
          "sku": "123 456 789",
          "url": "https://example.com/products/black t shirt"
        }
      }
    ],
    "payment": {
      "customer": {
        "email": "bob.brown@generic email.com",
        "first_name": "Bob",
        "last_name": "Brown",
        "phone": "888 323 5283"
      },
      "amount_covered": 0,
      "payment_method_type": "CARD",
      "subtotal": 19.99
    },
    "platform_transaction_id": "{a unique identifier that you produce for this order}"
  }
}





B. Send in an order

POST https://public.test.routeapp.io/v1.3/custom/order

Keep the response you receive from this endpoint for the next endpoint.





{
  "api_key": {
    "key": "{your route api key goes here}",
    "platform_identifier": "{your unique route generated platform identifier}",
    "store_identifier": "{your unique route generated store's identifier}"
  },
  "quote": {
    "route_quote_amount": 0.98,
    "route_quote_private_token": "{your unique route quote private token for this order}",
    "route_quote_public_token": "{your unique route quote public token for this order}",
    "timestamp": "2018-08-11T17:08:46.648Z"
  },
  "transaction": {
    "currency": "USD",
    "line_items": [
      {
        "discount": "SPECIAL",
        "price": 19.99,
        "price_before_discount": 21.99,
        "product": {
          "desc": "A wonderful Black T shirt. Egyptian cotton. ...",
          "insurable": true,
          "name": "Black T shirt",
          "picture_uri": "https://example.com/assets/",
          "sku": "123 456 789",
          "url": "https://example.com/products/black t shirt"
        }
      }
    ],
    "payment": {
      "customer": {
        "email": "bob.brown@generic email.com",
        "first_name": "Bob",
        "last_name": "Brown",
        "phone": "888 323 5283"
      },
      "amount_covered": 19.99,
      "paid_to_insure": 0.98,
      "payment_method_type": "CARD",
      "subtotal": 19.99,       /* Route charges before route */
      "taxes": 0 /* Route is not taxable */
    },
    "platform_transaction_id": "{a unique identifier that you produce for this order}"
  }
}





C. Update order with tracking

PUT https://public.test.routeapp.io/v1.3/custom/order

Make sure that you get a 200. 





{
  "api_key": {
    "key": "{your route api key goes here}",
    "platform_identifier": "{your unique route generated platform identifier}",
    "store_identifier": "{your unique route generated store's identifier}"
  },
  "quote": {
    "route_quote_amount": 0.98,
    "route_quote_private_token": "{your unique route quote private token for this order}",
    "route_quote_public_token": "{your unique route quote public token for this order}",
    "timestamp": "2018 08 11T17:08:46.648Z"
  },
  "transaction": {
    "currency": "USD",
    "line_items": [
      {
        "discount": "SPECIAL",
        "price": 19.99,
        "price_before_discount": 21.99,
        "product": {
          "desc": "A wonderful Black T shirt. Egyptian cotton. ...",
          "insurable": true,
          "name": "Black T shirt",
          "picture_uri": "https://example.com/assets/",
          "sku": "123456789",
          "url": "https://example.com/products/black t shirt"
        }
      }
    ],
    "payment": {
      "customer": {
        "email": "bob.brown@generic email.com",
        "first_name": "Bob",
        "last_name": "Brown",
        "phone": "888 323 5283"
      },
      "amount_covered": 19.99,
      "paid_to_insure": 0.98,
      "payment_method_type": "CARD",
      "subtotal": 19.99,       /* Route charges before route */
      "taxes": 0 /* Route is not taxable */
    },
    "platform_transaction_id": "{a unique identifier that you produce for this order}",
    "tracking_number": "{tracking number from courier}",
    "courier": "{courier}"
  }
}





4. Embed Route.js



Use this code to embed Route into your checkout page. 





<div id=“route-widget” data-routepublictoken={YOUR-ROUTE-QUOTE-PUBLIC-TOKEN} data-routequoteamt={ROUTE-QUOTE-AMOUNT}

data-routestyle=‘false’ data-routeischecked=‘true’></div>

 

<script src=’https://js.test.routeapp.io/RouteWidget.js' type=‘text/javascript’></script>





You can put this div anywhere in the checkout flow where your customers will most effectively see it (the cart page, the checkout page etc.) Most will put the div in the checkout page on the user info section (we recommend putting this at the bottom of your current fields). Put the script at the bottom of the body on any page you choose to implement Route. You will not be able to change the size or style of Route.js. 



*Use the div attribute "data-routeischecked" to verify that Route has visibly been added. This ensures that the action can be seen by the customer when Route is ordered.



5. Test Integration 



After completing your integration, do a thorough testing of both your front-end and order management functions to ensure that everything works as expected.




6. Deploy To Production



Before deploying the Route integration to your production site, Route team members will need to test it in your development or staging environment connected to our live environment.

 

A. Contact Route Representative

Contact your Route representative to coordinate this test. After we test, we will send you login info to your live production dashboard.



B. Login

After receiving live credentials, log into the Route live dashboard. 



C. Grab Live API Keys

On the top of your screen, go to your Admin, then Account Details. 




DashAccountDetails.png




You can access your API Key on the top right. Copy your API Key for use in requests.




RouteGetAPIKey.png




D. Connect Billing

On the top of your screen, go to your Admin, then Billing. 




Route.png




Click on Add Billing Type.




Route.png




Click on Setup Payment With Stripe




Route.png





Route.png




You are Now Ready to Launch to Production

After you’ve connected to our live environment and we’ve tested your integration, you’re ready to deploy to your production environment and offer Route to customers