Step-by-step guide for getting up and running with the Trackstar API. If you get stuck or have trouble, email us at support@trackstarhq.com.

Fully setting up Trackstar will require updates to both your frontend (FE) and backend (BE) code. We will denote which steps are for the frontend and which are for the backend.

Your frontend will make calls to your backend, which will in turn make calls to the Trackstar API. This gets the authorization necessary for your user to authenticate with Trackstar and the underlying APIs.

1. Get an API key

Request an API key by emailing support@trackstarhq.com.

Test it by making an API call to the POST /link/token endpoint to get a link token.

curl -X POST https://production.trackstarhq.com/link/token \
    -H 'x-trackstar-api-key: YOUR_API_KEY'

If successful, you should get a response like this:

{
  "link_token": "some_link_token"
}

Store this API key somewhere safe! This will be the API key for your whole organization.

2. Implement Token Exchange Endpoints (BE)

There are two backend API endpoints that you need to implement. (Note: you can name these endpoints whatever you want, but we will use the names /get-link-token and /store-token in this guide).

  • POST /get-link-token - Returns a temporary link token that is used to initialize the react-trackstar-link component.
  • POST /store-token - Exchanges a temporary auth code for a permanent access token and saves it to a database. This access token is associated with a customer and an integration (ShipBob, Extensiv, etc).

We will use a combination of Python + Flask or Node.js + Express + Axios in this guide, but you can use any language and framework you want.

Link tokens are temporary access keys granted to your frontend to make API calls on behalf of your organization. Your frontend will call this endpoint to get a link token. You will see this being called in step 4.

from flask import Flask
import requests

TRACKSTAR_API_KEY = ""

@app.route("/get-link-token", methods=["POST"])
def link_token():
    response = requests.post(
        "https://production.trackstarhq.com/link/token",
        headers={
            "x-trackstar-api-key": TRACKSTAR_API_KEY,
            "Content-Type": "application/json"
        },
    )
    response.raise_for_status()
    response = response.json()
    link_token = response["link_token"]
    return {"linkToken": link_token}

2.2 /store-token

After a user installs an integration, the frontend will send an auth code to the backend, along with any relevant customer data. The auth code is a temporary token that you must exchange via Trackstar’s /link/exchange endpoint to get a long-lived access_token.

Additionally, a connection_id and integration_name will be returned. Connection IDs are unique identifiers for each connected integration. You should store these in your database along with the access_token if you plan on utilizing Trackstar Webhooks.

from flask import Flask, request
import requests

TRACKSTAR_API_KEY = ""

@app.route("/store-token", methods=["POST"])
def store_token():
    body = request.get_json()
    customer_id = body.get("customer_id") # and any other relevant info from your FE
    auth_code = body.get("auth_code")

    # Call Trackstar API to get access_token (and integration_name)
    response = requests.post(
        "https://production.trackstarhq.com/link/exchange",
        data={"auth_code": auth_code},
        headers={
            "x-trackstar-api-key": TRACKSTAR_API_KEY,
            "Content-Type": "application/json"
        },
    )
    response.raise_for_status()
    response = response.json()
    access_token, connection_id, integration_name, available_endpoints = (
        response["access_token"],
        response["connection_id"],
        response["integration_name"],
        response["available_endpoints"],
    )
    # Store customer_id, access_token, connection_id, integration_name in your database
    access_tokens_table = ...
    row = {
      "customer_id": customer_id,
      "access_token": access_token,
      "connection_id": connection_id,
      "integration_name": integration_name,
      "available_endpoints": available_endpoints,
    }
    access_tokens_table.put(row)
    return "Success!" # back to your frontend

In your frontend code, install the official react-trackstar-link package.

npm
npm install @trackstar/react-trackstar-link

or

yarn
yarn add @trackstar/react-trackstar-link

In your frontend code, import the TrackstarConnectButton component and render it in your app.

import { TrackstarConnectButton } from '@trackstar/react-trackstar-link';

function App() {

  const someCustomerId = "12345";
  return (
    <TrackstarConnectButton
      getLinkToken={async () => {
        // the endpoint you implemented in step 2.1
        const response = await fetch('https://my-company.backend.com/get-link-token',
          {
            method: 'POST',
          }
        );
        const { linkToken } = await response.json();
        return linkToken;
      }}
      onSuccess={async (authCode, integrationName) =>
        // the endpoint you implemented in step 2.2
        await fetch('https://my-company.backend.com/store-token',
          {
            method: 'POST',
            body: JSON.stringify({
              customer_id: someCustomerId,
              auth_code: authCode,
              integration_name: integrationName,
            }),
          }
        )
      }
      onClose={() => console.log('closed')}
      onLoad={() => console.log('loaded')}
      // sandbox={true} // Set to true to include a "Sandbox" WMS in the list of integrations
    >
      Connect your WMS
    </TrackstarConnectButton>
  );
}

More documentation, including additional properties, can be found here.

5. Make API calls (BE)

Now you can use the access token to make API calls to Trackstar!

import requests

TRACKSTAR_API_KEY = ""
ACCESS_TOKEN = ""

url = "https://production.trackstarhq.com/wms/inventory"
headers = {
 "x-trackstar-api-key": TRACKSTAR_API_KEY,
 "x-trackstar-access-token": ACCESS_TOKEN, # from your database that you stored in step 2.2
 "Content-Type": "application/json"
}
response = requests.get(url, headers=headers)
response.raise_for_status()
response = response.json()
# Make magic happen

You can read the API reference for all supported operations.

6. Feedback

If this process took you a long time, or you got stuck, we want to know! Please email us at support@trackstarhq.com and let us know how we can improve this guide.