Getting started Cin7 Inventory Management System API with Postman and Node

Introduction

Cin7 is popular IMS system for many companies with a breath of modules that cover almost every use case for management of inventory with flexibility in integrations with other software tools to streamline operations.

Like most IMS, there are API endpoints which we can tap into do create automated processes such as updating the inventory when a customer checkouts on a ecommerce website or creating a new customer in a CMS (Hubspot, Saleforce).

The use case I’m covering here is to interact with the Serial Number module of Cin7 for customer sign up by checking if the serial number exists and is valid. Aside from this use case, the process I will be outlining is applicable to interacting with any of the Cin7 API endpoints.

As developer interacting with the Cin7 API for the first time, there may be a bit of trial and error or confusion trying to get started. Cin7 does provide a high level description in the docs, but won’t hold your hand to get started.

From my experience with interacting with Cin7 API, I’ll like to share my process of getting up and running (mini tutorial) using Postman and how I formulated my solution to do serial key queries with firebase cloud functions. I won’t present the entire solution in code since this article is mainly just to explain Cin7 API interactions.

Getting Started with Cin7 API

To get started, you need a Cin7 account, otherwise you won’t be able to interact with any of the modules. From your account, a API key and API username is necessary for authorisation when interacting with the endpoints.

To create a API key and username, go to Settings & Options (cog icon) -> Integrations & API -> API v1. Create a new API key and save it somewhere safe, then customise the preferences for the read, create, update and delete permissions for your required modules. In this use case, only read from serial numbers and products module is necessary.

Cin7 Dashboard — Integrations & API section

The Process for Serial Key Signups

Before moving on to the technicalities of interacting with the Cin7 endpoints, framing the problem for the context of this article is necessary, particular to serial key sign ups.

There needs to be a check for whether a serial key exists in Cin7, and because serial number module does not indicate whether a serial has been redeemed or not, a secondary database is required to store that parameter. Therefore, a second check is conducted to determine if the status of the key has been used.

If serial key exists and is not utilised, then the user is allowed to sign up. After confirmation of sign up, the product related to the serial key is added to the user’s account and the serial key status is updated to “used”.

The diagram below demonstrates my thought process of how the solution process may look like.

Flowcart for serial key sign up for platform

Testing with Postman

To first get a hang of interacting with the API, Postman is used to make API requests to Cin7 endpoints.

The endpoint is https://api.cin7.com/api/ followed by additional url respective to the module you’re trying to access. For example, to access the serial number list end point, this will be the entire endpoint url: https://api.cin7.com/api/v1/SerialNumbers/

Cin7 uses basic authentication (passing along a username and password in Base64 format) as part of each request, therefore in the Auth tab for Postman, choose type -> Basic Auth, and for the username and password this refers to API username and API key found in the Cin7 API settings, respectively.

Try send a GET request to any of the modules which you have data populated already to see if you’re able to get a response. In the figure below, I made a request to the serial number endpoint and got back an array of serial numbers.

Postman GET API Cin7

Additionally, you can pass query parameters if you want to filter the request based on certain attributes. More information on this can be found on the Cin7 docs API .

For example, for my use case, I need to check if a serial exists. Instead of returning the entire list and filtering the array for the matching serial number, I passed a ‘where’ clause to only return results where serialNumber attribute equals desired ID string. Below indicates how the query param is passed.

Fetching serial number ID by passing where key

Interacting with Node JS

Now that the request structure is understood, it’s time to code the API request in Javascript.

The easiest way is to do it client side, however there’s difficulty in safely storing important information such as the API key and username on the client. Therefore, adopting for a server side request is probably more ideal as the variables can be stored in an environmental variables file (.env).

In saying so, the implementation is very similar for both client and server side. In this example, I used firebase cloud functions, but you can also set up an express server with a route or fetch it from client side.

First install isomorphic fetch for node. The installation of isomorphic fetch can be omitted if you’re fetching from the client.

npm i isomorphic-fetch

import isomorphic fetch and firebase modules.

const fetch = require("isomorphic-fetch");
const functions = require("firebase-functions");

Create a function to retrieve the serial number form Cin7.

const fetchSerialCin7 = (data) => {
  const username = functions.config().cin7.username; // refer to setting environmental variables in firebase functions - API username
  const password = functions.config().cin7.password; // API key

  const url =
    "https://api.cin7.com/api/v1/SerialNumbers/?where=serialNumber=" +
    "'" +
    data.serial +
    "'";

  const auth =
    "Basic " + Buffer.from(username + ":" + password).toString("base64"); // base64 encode username and password
   
  return new Promise((resolve, reject) => {
    fetch(url, {
      method: "GET",
      headers: {
        Authorization: auth,
      },
    })
      .then((response) => {
        if (response.status >= 400) {
          reject("Bad response from server");
        }

        return response.json();
      })
      .then((data) => {
        resolve(data);
      })
      .catch((error) => {
        reject(error);
      });
  });
};

Create firebase callable cloud function which the client side will call.

exports.fetchSerialCin7 = functions.https.onCall((data, context) => {
    return 
      fetchSerialCin7(data)
      .then((data) => {
        return data; //returns serial json
      })
      .catch((error) => {
        throw new functions.https.HttpsError("internal", error);
      });
  });

Deploy cloud functions using CLI — Must have installed globally firebase CLI.

firebase deploy --only functions:fetchSerialCin7

Interacting with the cloud function on the client. You will need to have initialised firebase functions scripts in your application. Refer to firebase docs for more information.

const fetchSerialCin7 = async () =>
        firebase
        .app()
        .functions()
        .httpsCallable("fetchSerialCin7");

      try {
        const result = await fetchSerialCin7({ serial: serial }); 
        // serial variable is bind to an input text box value

        if (!result.data || result.data.length === 0) {
          // if serial does not exists do something...
          console.log('serial does not exist');
          return;
        }
        // if serial exists do something...
        console.log('serial exists');
      } catch (error) {
        console.log(error);
      }
}

I have a left out quite of bit of initialisation setup for firebase as that’s not the focus here. You can use any cloud function provider such as AWS Lambda or run your own server which will change your code setup.

In a similar way to reading API endpoints, doing POST request is also the same except you also need to pass along body information.

I hope this provide you a starting point with interacting with Cin7 API endpoints.