Salable API v2

Rectangle with API 2.0 written in it, and the words Salable written above it. Background colours are black and blue.

We've got some awesome updates to share about our v2 API that'll make your life simpler, your data more secure, and improve your overall Salable API experience. Check out what's new:

Improved API key security

We've ramped up the security for managing API keys. Now, each key comes with more precise permissions—for example, setting expiration dates/duration for API keys to allow temporary access to specific resources. This gives you better control over what it can access so you can fine-tune what your keys can do when they interact with the API. More control = more peace of mind!

Paginated results updates

Tired of getting too much data at once and slowing things down? We've got you covered with our new cursor-based pagination system. Now, data comes in bite-sized chunks, and you can easily load more by using the first or last ID from your response as a "cursor" for the next request. This makes handling large datasets a breeze!

Example request:

{
import Salable from "@salable/node-sdk";
const salable = new Salable('{{API_KEY}}', 'v2')
const data = await salable.licenses.getAll({
  cursor: "id-2"
  take: 3
})

Example response:

{
{
  first: 'id-2',
  last: 'id-3',
  data: [
    {id: 'id-2'},
    {id: 'id-3'},
    {id: 'id-4'},
  ]
}

Endpoints using this update

Get all licenses (GET /licenses)

{
import Salable from "@salable/node-sdk";
const salable = new Salable('{{API_KEY}}', 'v2');
const data = await salable.licenses.getAll();

Get all usage records (GET /usage)

{
import Salable from "@salable/node-sdk";
const salable = new Salable('{{API_KEY}}', 'v2')
const data = await salable.usage.getAllUsageRecords({
  granteeId: '{{GRANTEE_ID}}'
});

Get all subscriptions (GET /subscriptions) [new in v2]

{
import Salable from "@salable/node-sdk";
const salable = new Salable('{{API_KEY}}', 'v2')
const data = await salable.subscriptions.getAll();

Get all invoices (GET /subscriptions/:uuid/invoices)

{
import Salable from "@salable/node-sdk";
const salable = new Salable('{{API_KEY}}', 'v2')
const data = await salable.subscriptions.getInvoices('{{SUBSCRIPTION_UUID}}');

Enhanced integration with sessions and web components 

We're rolling out new web components so you can integrate your apps with Salable faster and simpler. To keep things secure, we've introduced Sessions. 

You can now generate a temporary, secure 64-character token with specific permissions for use with our web components. These tokens are short-lived, ensuring your data stays safe.

Each web component needs specific info (metadata) when creating the session, and you’ll use the token as a Bearer header (a security token that is commonly used in authentication protocols, such as OAuth)in requests to grant temporary access.

Web components we've released so far:

  • Invoices
  • Pricing table
  • Checkout

This keeps everything secure while giving you a smooth integration experience.

Usage 

Charge your customers based on how much they use during a subscription period. At the end of each billing cycle, customers get billed for what they've used. We've introduced license usage records to help you track exactly what each customer has used, both in the current cycle and historically. This works for ad hoc licenses too!

Here's how you can manage usage with our API:

Get all usage records (GET /usage) 

Fetches all usage records for a customer (grantee) with smooth navigation using cursor-based pagination.

{
import Salable from "@salable/node-sdk";
const salable = new Salable('{{API_KEY}}', 'v2')
const data = await salable.usage.getAllUsageRecords({
  granteeId: '{{GRANTEE_ID}}'
});

Get current record (GET /usage/current) 

Returns current usage data for a grantee on a specific plan. Passes the plan and granteeID as query parameters.

{
import Salable from "@salable/node-sdk";
const salable = new Salable('{{API_KEY}}', 'v2')
const data = await salable.usage.getCurrentUsageRecord({
  granteeId: '{{GRANTEE_ID}}',
  planUuid: '{{PLAN_UUID}}'
});

Update current usage record (PUT /usage) 

Increases the current usage count and automatically updates the subscription if the license is paid.

{
import Salable from "@salable/node-sdk";
const salable = new Salable('{{API_KEY}}', 'v2')
await salable.usage.updateLicenseUsage({
  granteeId: '{{GRANTEE_ID}}',
  planUuid: '{{LICENSE_PLAN_UUID}}',
  increment: 1	
  idempotencyKey: randomUUID()
});

This makes it easier to track and bill for usage-based services accurately.

Changes to test mode 

Now, you only need one live Stripe account. Using our Stripe test mode keys, you can generate test data directly within your live account. This means you can manage both live and test mode products/plans all in one place, making life so much easier!

Full details of the API migration can be found here, which explains our recommendations for upgrading, including how to upgrade, and what the main differences between v1 and v2 are.

You can also find a full list of breaking changes on our changelog. Please note that these will only occur if you move to v2 of the API. If you decide to stay on v1, these endpoints will not change.

We’ve also had a significant upgrade to the Salable Node SDK. Use this guide to help you upgrade from older versions of the SDK to v4.0.0.

We hope all of these changes will enhance your overall Salable API experience. As always, we’re here to support you with any questions or feedback you may have, so please feel free to reach out to us. You can come and chat with us in Discord too!

Related blogs

Tweet from Neal Riley saying "Commercial freedom and flexibility is a must for any digitally enabled business. @SalableApp gives you the tools to build your SaaS business."

Tweet from Neal Riley saying "Commercial freedom and flexibility is a must for any digitally enabled business. @SalableApp gives you the tools to build your SaaS business."

#
Dev Diaries

How we are testing our Next.js API Routes (Pages Router)

We all know that testing application logic is important, and the more your application scales the more it grows in importance...

Coner Murphy
18 June 2024
#
Dev Diaries

How we are testing our Next.js API Routes (Pages Router)

We all know that testing application logic is important, and the more your application scales the more it grows in importance...

Coner Murphy
18 June 2024
#
Quick Start Guides

Salable CLI: Your Gateway to Getting Started

There are many varied ways to interact with the Salable platform, each with their own sets of functionality and recommended uses. In this guide, we’re going to be looking

Luke Glazebrook
6 Oct 2023
#
Quick Start Guides

Salable CLI: Your Gateway to Getting Started

There are many varied ways to interact with the Salable platform, each with their own sets of functionality and recommended uses. In this guide, we’re going to be looking

Luke Glazebrook
6 Oct 2023
#
Quick Start Guides

Salable Configure: Configuring Salable Made Easy

Up until now when getting started with Salable, you had two choices for configuring your account, products, plans, etc.

Coner Murphy
24 Nov 2023
#
Quick Start Guides

Salable Configure: Configuring Salable Made Easy

Up until now when getting started with Salable, you had two choices for configuring your account, products, plans, etc.

Coner Murphy
24 Nov 2023

Sign up to
our mailing list

Stay up to date with what we are currently building, plus new features, and chances to enter competitions.