Unified API Quick Start

What is the Unified API?

Alloy's Unified API is a way for ISVs to quickly and efficiently ingest data in a standard and consistent format. We currently support over 220+ integrations on the Alloy platform. Each integration has roughly two dozen (and oftentimes much more) individual endpoints supported. In total, Alloy supports thousands of individual APIs which can be used in millions of different permutations.

But sometimes, you just want to pull data in a consistent and standard format. Left alone, you'll have to manually map each and every field to a consistent data model – both an arduous and time consuming task. Enter Alloy's Unified API. The Unified API, also know as "Alloy One" allows ISVs to interact with standard data models (e.g. Orders, Customers, Products, etc) in a consistent, unified format without regard for the platform they're interacting with.

Real world use case

Let's assume you're in the business of underwriting loans. An individual named Joe who operates an online shoe store comes to you seeking a $50,000 loan and claims to have sales north of $20,000 each month. Joe operates his online shoe store via a dedicated Shopify site and has a sister storefront on eBay. Based on the operating margins of his business, he feels that his online sales are sufficient collateral for the loan. You want to quickly verify that Joe's claims are legitimate. Fortunately, Alloy's Unified API is here to help save the day.

How does this benefit you?

With the Unified API, an ISV’s development teams can quickly access common commerce resources without the need to build each integration to sync and transform data. Furthermore, since the Unified API standardizes these common data models from various platforms, the developers just need to implement a single code-base to access this data.

Other Key Benefits:

• Eliminates ongoing API maintenance
• Accelerates the ISV’s product roadmap
• Increases the ISV’s GTM coverage
• Taps into our industry expertise, from startups to the largest commerce platforms

Creating a Connection

To get started, you'll need to first implement Alloy's Unified API and create a connection. A connection represents each time an end user links an app to Alloy's Unified API. For example, if your end user connects to NetSuite, that would count as a single connection.

Create a End User

Alright, back to our example. To get started, we'll first need to use the POST Create User endpoint to generate a userId for the merchant, in this case, Joe. Creating a user is like creating a tenant and will be where we link all the user's future credentials and data.

Make sure to pass in your API key as bearer auth. You can find your API key in the Settings tab from the Alloy Dashboard.

 curl --request POST \
     --url https://embedded.runalloy.com/2023-06/users \
     --header 'Authorization: bearer YOUR_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{ "username": "YOUR_USERNAME" }'

Frontend Authentication

To get started with Unified API, you'll first need to connect your app to Alloy's Unified API. Fortunately, we offer a quick and painless way to do this using our frontend SDK. Our frontend SDK allows you to instantiate a modal which will prompt your users to connect their application(s) to Alloy. We call this the authenticate() method.

To install the frontend SDK, import the following file into the header of your application. You can read more about how to use the Frontend JavaScript SDK here.

<script
  src="https://cdn.runalloy.com/scripts/embedded.js"
  type="text/javascript"
></script>

For security reasons, we require generating a JSON Web Token to securely render the authenticate() method on your frontend. This token can be generated by making an API request to the GET /user/:userId/token endpoint on your backend. You must pass the userId . This endpoint will return a short lived JSON Web Token which you can pass to your frontend. Let’s take a look at that now.

curl --request GET \
     --url https://embedded.runalloy.com/2023-01/user/:userId/token \
     --header 'Accept: application/json' \
     --header 'Authorization: bearer YOUR_API_KEY'

This request will return a JSON Web Token, as discussed, that looks something like the following. You’ll want to save this on your frontend temporarily. Note that this token is only valid for an hour so you’ll need to regenerate it again if you intend to invoke the authenticate() method again and that it’s user-specific meaning that you’ll need to generate a new token for each user.

{
  "token": "XXXXXXXX.YYYYYYYYY.ZZZZZZZZ"
}

Now that you have the SDK installed, the first thing you'll need to do is to pass the frontend SDK your JWT. As mentioned earlier, a JWT is required to securely authorize the user. Once you've made a request to the Embedded APIs to retrieve your short lived token, you can set the token in the frontend SDK using the setToken method.

All frontend SDK methods require that you must first invoke setToken.

Alloy.setToken("<YOUR_TOKEN>");

With your token in hand, let’s call the frontend SDK. Invoke Alloy.authenticate() as seen below.

🚨 💡 Note: if you’re interacting with the Alloy.js SDK from a react app, you can call these methods by invoking window.Alloy.authenticate().

Alloy.authenticate({
  appName: "shopify",
  callback: (data) => {
    console.log(data);
  },
});

The data object returns a success flag and a credentialId as seen below:

{
  "success": true,
  "connectionId": "123"
}

Note the appName argument. This represents the name of the app you want to connect to Alloy's Unified API. You can find a full list of apps by calling the GET List Apps endpoint (note that not all apps available in Alloy Embedded are offered in Unified API).

Once you invoke this method, you'll see a modal render as seen below.

Wonderful! We’re really off to the races now. Once the callback is invoked and it returns the Connection ID, your data for the authenticated app will start syncing.

👍 Behind the scenes, Alloy's Unified API subscribes to all incoming webhooks after the user has authenticated and maintains a cache where merchant data is stored. This cache allows ISVs to bypass traditional rate limits on third party services and near instantly retrieve large sums of data. Our Unified API also has built in polling reconciliation to mitigate against dropped webhooks.

Making your first API Call

Now that we've created the user and successfully authenticated our Shopify store, let's make our first API call to retrieve the list of orders in Joe's store. We can use this data to verify the volume and prices of the orders Joe claims to make.

To list all orders associated with a Shopify store, we'll call the commerce API. Alloy's Unified API offers several categories with more constantly being rolled out. To fetch e-commerce site data, we'll use the commerce API and make a request to the GET List Orders endpoint.

curl --location 'https://embedded.runalloy.com/2023-03/one/commerce/orders?connectionId=YOUR_CONNECTION_ID' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY'

Let's break this request down for a moment. Note the base URL is https://embedded.runalloy.com/2023-03 with the date stamp representing the version. At Alloy, we release regular quarterly updates to our APIs. We always advise you use the latest version which is denoted by the date closest to today.

The next path parameter, /one/ indicates you're calling the Unified API. Recall from earlier when we created the user that we did not specify the /one/ path. This is because the POST Create User endpoint can be reused to create tenants for our Embedded iPaaS product, too.

Moving on, you'll notice the /commerce/ path which denotes the type of Unified API we are invoking. The commerce path indicates we are invoking the e-commerce API. Other examples of APIs offered by Alloy include the ERP and Help Desk APIs.

Lastly, you'll notice the /orders/ path which denotes the exact endpoint on Alloy's e-commerce Unified API we intend to invoke.

Before we go any further, there's a few more things to note:

• You must pass the ID of the connection you want to retrieve orders for as part of the connectionId query parameter.
• Finally, be sure to pass along your API key in the bearer auth header.

Awesome. You're now ready to make your first API request. Fire up postman and invoke the endpoint. You should see something like the below.

Now, repeat the same process for an eBay credential. You'll notice the data is formatted the exact same way despite the fact that you're interfacing with different e-commerce providers.

Pushing data via Unified API

So far, you has only been pulling (i.e. reading) data via GET requests. If you need to push data on behalf of a user, you can invoke our write endpoints. Let's say we want to first get some data about an order.

curl --request GET \
     --url '<https://embedded.runalloy.com/2023-03/one/commerce/orders/<ORDER_ID>?connectionId=YOUR_CONNECTION_ID' \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'accept: application/json'

Now assume you wanted to update the status of that same order. To do so, invoke the PUT /orders endpoint and pass along the status in the request body.

curl --request PUT \
     --url '<https://embedded.runalloy.com/2023-03/one/commerce/orders/<ORDER_ID>?connectionId=YOUR_CONNECTION_ID' \
     --header 'Authorization: Bearer YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
     --header 'accept: application/json' \
     --data '{"status": "cancelled"}'

Excellent work! You are now ready to roll! Give it a shot and see what all possibilities you can unlock. For the complete Unified API reference, visit this link.

Wrapping Up

As you can see, it's easy to get started with Alloy's Unified API. The Unified API allows you to read and write data by making API calls to our various unified endpoints. Each endpoint returns a data in a consistent format. Behind the scenes, Alloy's Unified API subscribes to all incoming webhooks after the user has authenticated and maintains a cache where merchant data is stored. This cache allows ISVs to bypass traditional rate limits on third party services and near instantly retrieve large sums of data. Our Unified API also has built in polling reconciliation to mitigate against dropped webhooks.

Oftentimes, reading and writing data isn't the only use case. If you need to subscribe to realtime events (i.e. such as being alerted each time an order is created in your user's Shopify store), you can use our webhooks APIs.

Alloy's Unified API makes it easy and quick to retrieve, modify, and subscribe to popular applications.