Your first billing flow

In this tutorial you will wire up a complete subscription flow from scratch. By the end you will have:

A plan with a metered feature and a boolean feature
A customer subscribed to that plan via a real checkout
Working access control that blocks requests when the quota runs out

You will build everything in a single Node.js script so you can see results immediately.

Before you start

You need:

A free Owostack account — sign up at app.owostack.com
A payment provider account (Paystack or Dodo Payments)
Node.js 18+

1. Create your organization and generate an API key

Log in to the dashboard at app.owostack.com and click Create Organization.
Name it anything you like (e.g. "My Tutorial App").
Go to API Keys → Create New Key. Name it "Tutorial" and copy the key.
Save it in a .env file:

OWOSTACK_API_KEY=owo_sk_xxxxxxxxxxxxxxxx

2. Connect a provider and set up webhooks

Go to Settings → Payment Providers and add your provider's secret key. You should see a green Connected badge.
Copy the webhook URL shown in the dashboard. It looks like this:

https://api.owostack.com/webhooks/<your-org-id>/<provider-id>

Paste it into your provider's webhook settings page. If your provider asks for events, select all events.

Without webhooks, Owostack cannot confirm payments. Every step after this depends on webhooks working.

3. Create your catalog

Instead of clicking around a dashboard, Owostack lets you define your features and plans in code.

Create owo.config.mjs:

import { Owostack, metered, boolean, plan } from "owostack";

// 1. Define features
export const apiCalls = metered("api-calls", { name: "API Calls" });
export const analytics = boolean("analytics", { name: "Analytics Dashboard" });

// 2. Define the client and catalog
export const owo = new Owostack({
  secretKey: process.env.OWOSTACK_API_KEY,
  catalog: [
    plan("starter", {
      name: "Starter",
      price: 500, // minor units
      currency: "NGN",
      interval: "monthly",
      planGroup: "main",
      features: [apiCalls.limit(100, { reset: "monthly" }), analytics.on()],
    }),
  ],
});

Now, push this configuration to your Owostack account:

npx owosk sync --config ./owo.config.mjs

You should see output confirming that your features and plans were created.

4. Write your first script

mkdir owostack-tutorial && cd owostack-tutorial
npm init -y
npm install owostack dotenv

Create index.mjs:

import "dotenv/config";
import { owo } from "./owo.config.mjs";

// --- Step A: Subscribe a customer ---
const attach = await owo.attach({
  customer: "tutorial_user",
  product: "starter",
});

console.log("Attach result:", attach);

if (attach.checkoutUrl) {
  console.log("\n→ Open this URL to complete payment:\n", attach.checkoutUrl);
  console.log("\nAfter paying, re-run this script.");
  process.exit(0);
}

Run it:

node index.mjs

You should see a checkout URL. Open it in your browser, complete the test payment, and come back.

6. Check feature access

After payment, add this below the attach block:

// --- Step B: Check boolean feature ---
const analyticsAccess = await owo.check({
  customer: "tutorial_user",
  feature: "analytics",
});

console.log("Analytics allowed?", analyticsAccess.allowed);
// → true

// --- Step C: Check metered feature ---
const apiAccess = await owo.check({
  customer: "tutorial_user",
  feature: "api-calls",
});

console.log("API calls remaining:", apiAccess.balance, "/", apiAccess.limit);
// → 100 / 100

Run it again. You should see allowed: true and balance: 100.

7. Track usage and hit the limit

Add this to consume some quota:

// --- Step D: Track usage ---
for (let i = 0; i < 5; i++) {
  await owo.track({
    customer: "tutorial_user",
    feature: "api-calls",
    value: 1,
  });
}

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

console.log("After 5 calls — remaining:", afterTracking.balance);
// → 95

Run it. Notice the remaining count drops by 5 each time you run the script.

8. See what happens at the limit

Replace the loop with a bulk track to exhaust the quota:

// --- Step E: Exhaust quota ---
const exhaust = await owo.track({
  customer: "tutorial_user",
  feature: "api-calls",
  value: 200, // more than the 100 limit
});

console.log("Track result:", exhaust.code);
// → "limit_exceeded"
console.log("Allowed?", exhaust.allowed);
// → false

Run it. The SDK returns allowed: false and code: "limit_exceeded". This is the signal you would use in a real app to block the request or show an upgrade prompt.

What you built

You now have a working billing flow:

Define your plans and features in code, syncing them with npx owosk sync.
attach() creates a checkout or returns an existing subscription.
check() tells you whether a customer can use a feature right now.
track() records usage and enforces limits.

Everything else — webhook processing, entitlement provisioning, period resets — happens automatically.

Your first billing flow

Your first billing flow

Before you start

1. Create your organization and generate an API key

2. Connect a provider and set up webhooks

3. Create your catalog

4. Write your first script

6. Check feature access

7. Track usage and hit the limit

8. See what happens at the limit

What you built

Next steps

How to set up checkout

How to switch plans

How it works

SDK Reference

On this page

AI Chat