owostack

Core SDK for the Owostack billing infrastructure. Build a working billing flow for your AI SaaS or platform in minutes.

Installation

npm install owostack

Quickstart

Initialize the SDK with your API key from the Owostack dashboard:

import { Owostack } from "owostack";

const owo = new Owostack({
  secretKey: process.env.OWOSTACK_SECRET_KEY,
  mode: "sandbox", // use "live" for production
});

1. Attach a customer to a plan

Create a checkout session or manage an existing subscription:

const attach = await owo.attach({
  customer: "user_123",
  product: "starter_plan",
  customerData: { email: "[email protected]" },
});

if (attach.checkoutUrl) {
  // Redirect your user to checkout
  window.location.href = attach.checkoutUrl;
}

2. Check feature access

Verify if a customer has access to a feature based on their plan:

const access = await owo.check({
  customer: "user_123",
  feature: "api-calls",
});

if (access.allowed) {
  // Allow request
}

if (access.credits?.source === "credit_system") {
  console.log(access.credits.addonBalance);
  console.log(access.credits.plan.balance);
}

3. Track usage

Record usage for metered features:

await owo.track({
  customer: "user_123",
  feature: "api-calls",
  value: 1,
});

4. Manage customer billing controls

Inspect and update customer-specific overage behavior through the same customer namespace:

const customer = await owo.customer({
  email: "[email protected]",
  name: "Acme Corporation",
});

await owo.customer.setFeatureConfig({
  customer: customer.id,
  feature: "api-calls",
  overage: "block",
  maxOverageUnits: 1000,
});

await owo.customer.setOverageLimit({
  customer: customer.id,
  maxOverageAmount: 500_000,
  onLimitReached: "block",
});

Features

• Feature Gating: Instant access control for boolean and metered features.
• Usage Metering: Record usage and enforce limits automatically.
• Checkout Flows: Generate checkout sessions for new subscriptions or plan upgrades.
• Catalog Synchronization: Define plans and features declaratively in your codebase and sync to the cloud.
• Multi-Provider Support: Built-in support for Paystack and Dodo Payments.
• Full TypeScript Support: Comprehensive type definitions for all methods and responses.

Related Packages

• owosk - CLI for catalog sync and project initialization.
• @owostack/types - Shared type definitions.

Documentation

For full documentation and guides, visit docs.owostack.com.

License

Apache-2.0