Hanzo AI
ProjectsHanzoaiIamSdk

Billing

Subscription management, plans, pricing, and payment APIs with the IAM billing client.

Billing

The IamBillingClient provides access to IAM's subscription, plan, pricing, and payment APIs.

Setup

import { IamBillingClient } from "@hanzo/iam/billing";

const billing = new IamBillingClient({
  serverUrl: "https://iam.hanzo.ai",
  clientId: "my-app",
  clientSecret: process.env.IAM_CLIENT_SECRET, // for server-side
  orgName: "my-org",
});

Subscriptions

// List all subscriptions for the configured org
const subs = await billing.getSubscriptions(token);

// Get a specific subscription
const sub = await billing.getSubscription("my-org/sub-name", token);

// Get subscription for a specific user
const userSub = await billing.getUserSubscription("my-org/username", token);

// Check if an org has an active subscription
const status = await billing.isSubscriptionActive("my-org", token);
// status.active — boolean
// status.subscription — IamSubscription | null
// status.plan — IamPlan | null

Plans

// List all plans
const plans = await billing.getPlans(token);

// Get a specific plan
const plan = await billing.getPlan("my-org/pro-plan", token);

Pricing

// List pricing configurations
const pricings = await billing.getPricings(token);

// Get specific pricing
const pricing = await billing.getPricing("my-org/standard-pricing", token);

Payments & Orders

// List payments
const payments = await billing.getPayments(token);
const payment = await billing.getPayment("my-org/payment-id", token);

// List orders
const orders = await billing.getOrders(token);
const order = await billing.getOrder("my-org/order-id", token);

Subscription Status Check

A common pattern for gating features based on subscription:

import { IamBillingClient } from "@hanzo/iam/billing";

async function checkAccess(orgName: string, token: string): Promise<boolean> {
  const billing = new IamBillingClient({
    serverUrl: "https://iam.hanzo.ai",
    clientId: "my-app",
  });

  const { active, subscription, plan } = await billing.isSubscriptionActive(
    orgName,
    token,
  );

  if (!active) {
    console.log("No active subscription");
    return false;
  }

  console.log(`Plan: ${plan?.displayName}, State: ${subscription?.state}`);
  return true;
}

Types

type IamSubscription = {
  owner: string;
  name: string;
  displayName?: string;
  user?: string;
  plan?: string;
  pricing?: string;
  startTime?: string;
  endTime?: string;
  duration?: number;
  state?: "Active" | "Inactive" | "Expired" | "Cancelled" | string;
};

type IamPlan = {
  owner: string;
  name: string;
  displayName?: string;
  description?: string;
  pricePerMonth?: number;
  pricePerYear?: number;
  currency?: string;
  options?: string[];
  isEnabled?: boolean;
  role?: string;
};

type IamPricing = {
  owner: string;
  name: string;
  displayName?: string;
  description?: string;
  plans?: string[];
  isEnabled?: boolean;
  application?: string;
  trialDuration?: number;
};

How is this guide?