Skip to main content
The official billing.io SDK for JavaScript and TypeScript. Works with Node.js 18+ and has zero external dependencies.

npm

@billing-io/sdk

GitHub

billing-io/sdk-js

​
Installation

npm install @billing-io/sdk

​
Quick Start

import BillingIO from "@billing-io/sdk";

const billing = new BillingIO("sk_live_...");

const checkout = await billing.checkouts.create({
  amount_usd: 49.99,
  chain: "tron",
  token: "USDT",
  metadata: { order_id: "ord_12345" },
});

console.log(checkout.checkout_id);
console.log(checkout.deposit_address);

​
Create a Checkout

const checkout = await billing.checkouts.create({
  amount_usd: 100.0,
  chain: "arbitrum",
  token: "USDC",
  metadata: {
    customer_email: "alice@example.com",
    plan: "pro",
  },
});

​
List with Auto-Pagination

The SDK provides async iterators for automatic cursor-based pagination: 
for await (const checkout of billing.checkouts.list()) {
  console.log(checkout.checkout_id, checkout.status);
}
Or fetch a single page: 
const page = await billing.checkouts.list({ limit: 10 });
console.log(page.data);
console.log(page.cursor); // pass to next request

​
Get Checkout Status

const status = await billing.checkouts.getStatus("chk_abc123");

console.log(status.status);                // "confirming"
console.log(status.confirmations);          // 8
console.log(status.required_confirmations); // 19

​
Webhook Signature Verification

Verify incoming webhook payloads using the built-in helper: 
import { verifyWebhookSignature } from "@billing-io/sdk";

const isValid = verifyWebhookSignature(
  rawBody,                                    // raw request body string
  request.headers["x-billing-signature"],     // signature header
  "whsec_..."                                 // your webhook secret
);

if (!isValid) {
  return new Response("Invalid signature", { status: 401 });
}
The SDK uses the Web Crypto API for signature verification, so it works in Node.js, Deno, Cloudflare Workers, and any runtime that supports crypto.subtle.

​
Idempotency

Pass an idempotency key to safely retry requests: 
const checkout = await billing.checkouts.create(
  { amount_usd: 49.99, chain: "tron", token: "USDT" },
  { idempotencyKey: "order_12345" }
);

​
Error Handling

All API errors throw a typed BillingIOError: 
import BillingIO, { BillingIOError } from "@billing-io/sdk";

try {
  await billing.checkouts.create({
    amount_usd: -1,
    chain: "tron",
    token: "USDT",
  });
} catch (err) {
  if (err instanceof BillingIOError) {
    console.log(err.status);  // 422
    console.log(err.code);    // "validation_error"
    console.log(err.message); // "amount_usd must be positive"
  }
}

​
Customers

const customer = await billing.customers.create({
  email: "alice@example.com",
  name: "Alice Johnson",
  metadata: { plan: "pro" },
});

const customer = await billing.customers.get("cus_abc123");

const updated = await billing.customers.update("cus_abc123", {
  name: "Alice Smith",
});

for await (const customer of billing.customers.list()) {
  console.log(customer.email);
}

​
Payment Methods

const pm = await billing.paymentMethods.create({
  chain: "tron",
  token: "USDT",
  display_name: "Primary USDT",
});

await billing.paymentMethods.setDefault("pm_abc123");

for await (const pm of billing.paymentMethods.list()) {
  console.log(pm.display_name, pm.chain, pm.token);
}

const link = await billing.paymentLinks.create({
  amount_usd: 99.99,
  chain: "arbitrum",
  token: "USDC",
  description: "Annual subscription",
});

console.log(link.url); // shareable payment URL

​
Subscriptions

// Create a plan
const plan = await billing.subscriptionPlans.create({
  name: "Pro Monthly",
  amount_usd: 29.99,
  interval: "monthly",
  token: "USDT",
  chain: "tron",
});

// Subscribe a customer
const sub = await billing.subscriptions.create({
  customer_id: "cus_abc123",
  plan_id: plan.id,
  payment_method_id: "pm_abc123",
});

// Update subscription (cancel, pause, resume)
await billing.subscriptions.update("sub_abc123", { status: "canceled" });

// List renewals
for await (const renewal of billing.subscriptionRenewals.list({ subscription_id: "sub_abc123" })) {
  console.log(renewal.status, renewal.amount_usd);
}

​
Entitlements

const ent = await billing.entitlements.create({
  plan_id: "plan_abc123",
  feature_key: "api_calls",
  value_type: "numeric",
  value_numeric: 10000,
});

// Check entitlement for a customer
const check = await billing.entitlements.check({
  customer_id: "cus_abc123",
  feature_key: "api_calls",
});
console.log(check.has_access, check.value);

​
Payouts

const payout = await billing.payoutIntents.create({
  recipient_address: "TXyz...",
  chain: "tron",
  token: "USDT",
  amount: 500.00,
  currency: "USD",
});

// After executing externally, submit tx hash
await billing.payoutIntents.execute("po_abc123", {
  tx_hash: "0xabc...",
});

// List settlements
for await (const settlement of billing.settlements.list()) {
  console.log(settlement.tx_hash, settlement.confirmed_at);
}

​
Revenue

for await (const event of billing.revenueEvents.list()) {
  console.log(event.event_type, event.amount, event.currency);
}

// Create an adjustment
const adj = await billing.adjustments.create({
  type: "credit",
  amount_usd: 10.00,
  description: "Loyalty discount",
  customer_id: "cus_abc123",
});

​
TypeScript Support

The SDK ships with full TypeScript types. All request and response types are exported: 
import type {
  Checkout,
  Customer,
  Subscription,
  PayoutIntent,
  RevenueEvent,
} from "@billing-io/sdk";