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!