Paylio Node.js SDK

The Paylio Node.js SDK provides convenient access to the Paylio API from applications written in server-side JavaScript and TypeScript.

Documentation

See the Paylio API docs.

Requirements

• Node.js 18+

Installation

npm install paylio

Usage

TypeScript

import { PaylioClient } from "paylio";

const client = new PaylioClient("sk_live_xxx");

// Retrieve current subscription
const sub = await client.subscription.retrieve("user_123");
console.log(sub.status);       // "active"
console.log(sub.plan.name);    // "Pro Plan"
console.log(sub.plan.amount);  // 999

client.close();

JavaScript (CommonJS)

const { PaylioClient } = require("paylio");

const client = new PaylioClient("sk_live_xxx");
const sub = await client.subscription.retrieve("user_123");
console.log(sub.status);
client.close();

List subscription history

const history = await client.subscription.list("user_123", {
  page: 1,
  pageSize: 10,
});

for (const item of history.items) {
  console.log(item.plan_name, item.status);
}

console.log(history.hasMore);

Cancel a subscription

// Cancel at end of billing period (safe default)
const result = await client.subscription.cancel("sub_uuid");
console.log(result.success);

// Cancel immediately
await client.subscription.cancel("sub_uuid", { cancelNow: true });

Configuration

const client = new PaylioClient("sk_live_xxx", {
  baseUrl: "https://custom-api.example.com/v1",
  timeout: 60_000, // 60 seconds
});

Error handling

import {
  PaylioClient,
  AuthenticationError,
  NotFoundError,
  RateLimitError,
  PaylioError,
} from "paylio";

const client = new PaylioClient("sk_live_xxx");

try {
  await client.subscription.retrieve("user_123");
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error("Invalid API key:", error.message);
  } else if (error instanceof NotFoundError) {
    console.error("Subscription not found:", error.message);
  } else if (error instanceof RateLimitError) {
    console.error("Rate limited, try again later");
  } else if (error instanceof PaylioError) {
    console.error(`API error ${error.httpStatus}: ${error.message}`);
  }
}

client.close();

Error types

Error	HTTP Status	Description
AuthenticationError	401	Invalid or missing API key
InvalidRequestError	400	Bad request parameters
NotFoundError	404	Resource not found
RateLimitError	429	Rate limit exceeded
APIError	5xx	Server error
APIConnectionError	—	Network or connection failure

All errors extend PaylioError, which extends Error.

Development

npm install
npm test
npm run typecheck
npm run lint

License

MIT