React Quickstart

This page will help you get started with Rutter.

Getting started with Rutter

In this guide, we'll go through the steps necessary to add Rutter to any React app. If you don't use React, see the JavaScript Quickstart.

Here are the main steps:

  1. Setup Rutter Link in your frontend
  2. Exchange a public_token for an access_token from Rutter in your backend
  3. Make requests to Rutter's API with your access_token

Clone this NextJS sample repo for a working example.

Install Rutter Link

First, we'll need to setup Rutter Link in your frontend. Rutter Link handles the heavy-lifting of allowing a merchant to share data with your app.

npm install react-rutter-link
# Or, using yarn
yarn add react-rutter-link

Then, use our React Hook to trigger the authentication flow in your code. You will need to pass in your public_key as part of the Link configuration. You can find it in your Rutter Dashboard.

Don't have a Rutter account? Click here to get started!

import { useRutterLink } from 'react-rutter-link';

function Component() {
  
 function onSuccess(publicToken) {
   console.log(publicToken);
 }
  
 const rutterConfig = {
   publicKey: "YOUR_RUTTER_PUBLIC_KEY",
   onSuccess: onSuccess
 }
  
 const { open } = useRutterLink(rutterConfig);
  
 return (
    <div>
    <Button onClick={() => open()}></Button> 
  </div>
 )
}

Now, if you run the app and click the Button, the Rutter Link flow will appear. Once a merchant completes the flow, a publicToken, representing a successful authentication, will be passed to your onSuccess callback.

You can also pre-supply a commerce platform enum or accounting platform enum in Rutter Link to direct the merchant through a specific platform authentication.

import { useRutterLink } from 'react-rutter-link';

function Component() {
  
 function onSuccess(publicToken) {
   console.log(publicToken);
 }
  
 const rutterConfig = {
   publicKey: "YOUR_RUTTER_PUBLIC_KEY",
   onSuccess: onSuccess
 }
  
 const { open } = useRutterLink(rutterConfig);
  
 return (
    <div>
    <Button onClick={() => open({ platform: "SHOPIFY" })}></Button> 
  </div>
 )
}

Exchange public_token for access_token

However, for security reasons, the publicToken cannot be used to access the Rutter API directly. The publicToken must be exchanged for an access_token using the Exchange Tokens endpoint.

We'll need to pass the public_token to our backend, exchange it for an access_token, and then we can start accessing data. Let's modify the frontend code a bit:

import { useRutterLink } from 'react-rutter-link';

function Component() {
  
 function onSuccess(publicToken) {
   // Send publicToken to your backend, which will call the
   // Rutter API to get an access_token
   callBackendAPI(publicToken)
 }
  
 const rutterConfig = {
   publicKey: "YOUR_RUTTER_PUBLIC_KEY",
   onSuccess: onSuccess
 }
  
 const { open } = useRutterLink(rutterConfig);
  
 return (
    <div>
    <Button onClick={() => open()}></Button> 
  </div>
 )
}

We assume that callBackendAPI hits one of your backend endpoints.

Now, let's write a function on the backend that takes the publicToken and exchanges it for an access_token. To do this you can use your favorite HTTP request library. Here, we use Axios.

const axios = require('axios');

async function backendHandler(publicToken, userId) {
    const res = await axios.post("https://sandbox.rutterapi.com/item/public_token/exchange",
             {
                         client_id: "YOUR_RUTTER_CLIENT_ID",
                       secret: "YOUR_RUTTER_SECRET",
                         public_token: publicToken
                     })
 const access_token = res.data.access_token;
 // Save the access_token and associated userId in your DB 
 saveAccessTokenForUser(access_token, userId);
}

The snippet above exchanges a publicToken for an access_token, and saves the access_token for the corresponding user. Now, you can fetch data for this user at any time by retrieving the access_token in your database, and calling the Rutter API.

Make your first API call

Now, let's make a request to the Fetch All Orders endpoint:

axios.get("https://sandbox.rutterapi.com/orders", {
 params: {
   access_token: "RUTTER_ACCESS_TOKEN",
   limit: 1
 },
 auth: {
   username: "RUTTER_CLIENT_ID",
   password: "RUTTER_SECRET"
 }
})

Rutter uses HTTP Basic Authentication to verify your identity. For more information, see Authorization. Rutter uses the access_token query parameter to determine which Connection to fetch data for.

The response will be a Fetch All Orders response.

Congratulations, you successfully set up Rutter with your React app!

📘

Are we missing anything?

Do you have questions or want a Quickstart in another language? We're very responsive to documentation requests, so please email us at [email protected] anytime.


What’s Next