Reference: metered(), boolean(), entity(), creditSystem(), creditPack(), plan() — define features and plans as code

Create plans & features

Builder functions for defining features and plans declaratively. Features become handles you can use directly for .check() and .track().

Parameter	Type	Required	Description
`slug`	`string`	Yes	Unique feature identifier
`opts.name`	`string`	No	Human-readable name (auto-generated from slug if omitted)

Parameter	Type	Default	Description
`value`	`number`	—	Usage limit per period
`config.reset`	`ResetInterval`	`"monthly"`	Reset schedule
`config.usageModel`	`"included" \| "usage_based" \| "prepaid"`	`"included"`	Entitlement model for the feature
`config.pricePerUnit`	`number`	—	Package or per-unit price (minor currency)
`config.ratingModel`	`"package" \| "graduated" \| "volume"`	`"package"`	How billable usage is priced
`config.tiers`	`PricingTier[]`	—	Tier definitions for graduated or volume pricing
`config.overage`	`"block" \| "charge"`	`"block"`	What happens when limit is exceeded
`config.overagePrice`	`number`	—	Price per overage unit (minor currency)
`config.maxOverageUnits`	`number`	—	Hard cap on overage units per period
`config.billingUnits`	`number`	`1`	Package size for billing
`config.creditCost`	`number`	—	Cost in credits per unit

Parameter	Type	Required	Description
`value`	`number`	Yes	Trial usage limit (null = unlimited)

`boolean(slug, opts?)`

Create a boolean feature handle. Boolean features are either enabled or disabled per plan — no usage tracking.

import { boolean } from "owostack";

const analytics = boolean("analytics", { name: "Analytics Dashboard" });

Methods

`.on()`

Feature is included in this plan.

analytics.on();

`.off()`

Feature is NOT included in this plan.

analytics.off();

`.check(customer, opts?)`

Check if a customer has access to this feature.

const { allowed } = await analytics.check("user_123");

Returns Promise<CheckResult>.

Boolean features have no .track() method — the type system enforces this.

Create a non-consumable feature handle. Entity features represent persistent resources like seats, projects, or workspaces — things you add and remove to consume capacity, not counters that reset.

import { entity } from "owostack";

const seats = entity("seats", { name: "Team Seats" });
const projects = entity("projects", { name: "Projects" });

Parameters

Same as metered().

Plan methods

`.limit(value, config?)`

Set the maximum number of entities allowed.

seats.limit(5);
seats.limit(5, { overage: "charge", overagePrice: 500 });

Parameter	Type	Default	Description
`value`	`number`	—	Maximum entities allowed
`config.overage`	`"block" \| "charge"`	`"block"`	What happens when limit is exceeded
`config.overagePrice`	`number`	—	Price per extra entity (minor currency)

Entity features default to reset: "never" — the count reflects current state, not periodic usage.

`.unlimited()`

No limit on the number of entities.

seats.unlimited();

Runtime methods

`.add(customer, opts)`

Add an entity (e.g., a seat). Validates against the plan limit.

const result = await seats.add("org@acme.com", {
  entity: "user_123",
  name: "John Doe",
  email: "john@acme.com",
  metadata: { role: "admin" },
});

console.log(result.count); // 3
console.log(result.remaining); // 2

Parameter	Type	Required	Description
`customer`	`string`	Yes	Customer ID or email
`opts.entity`	`string`	Yes	Unique entity ID
`opts.name`	`string`	No	Display name
`opts.email`	`string`	No	Email address
`opts.metadata`	`Record<string, unknown>`	No	Custom metadata

Returns Promise<AddEntityResult>.

`.remove(customer, entity)`

Remove an entity. Frees the slot immediately.

await seats.remove("org@acme.com", "user_123");

Returns Promise<RemoveEntityResult>.

`.list(customer)`

List all active entities for this feature.

const { entities, total } = await seats.list("org@acme.com");

for (const seat of entities) {
  console.log(seat.id, seat.name, seat.status);
}

Returns Promise<ListEntitiesResult>.

`.check(customer, opts?)`

Check how many entities exist and if more can be added.

const result = await seats.check("org@acme.com");
console.log(result.allowed); // true if under limit
console.log(result.balance); // remaining slots

Returns Promise<CheckResult>.

Entity features have no .track() method — entities are managed via .add() and .remove(). The type system enforces this.

`creditSystem(slug, config)`

Create a credit system definition. A credit system abstracts usage across multiple features into a single "credit" balance.

import { creditSystem, metered } from "owostack";

const gpt4 = metered("gpt-4");
const dallE = metered("dall-e");

const aiCredits = creditSystem("ai-credits", {
  name: "AI Credits",
  features: [
    gpt4(20), // GPT-4 costs 20 credits per track()
    dallE(50), // Dall-E costs 50 credits per track()
  ],
});

Parameters

Parameter	Type	Required	Description
`slug`	`string`	Yes	Unique credit system identifier
`config.name`	`string`	No	Human-readable name
`config.description`	`string`	No	Description
`config.features`	`FeatureHandle[]`	Yes	Array of features that consume from this system

Methods

`.credits(amount, config?)`

Include a specific amount of credits for this system in a plan.

aiCredits.credits(1000, { reset: "monthly", overage: "charge" });

`creditPack(slug, config)`

Create a credit pack definition. Credit packs are one-time purchasable bundles of credits that top up a customer's prepaid balance. They're ideal for letting customers buy additional usage beyond their plan limits.

import { creditPack, creditSystem } from "owostack";

const apiCredits = creditSystem("api-credits", {
  name: "API Credits",
  features: [apiCalls(1)],
});

const starterPack = creditPack("starter-pack", {
  name: "Starter Pack",
  description: "500 API credits",
  credits: 500,
  price: 1000, // $10.00
  currency: "USD",
  creditSystem: "api-credits", // Must match a credit system slug
});

const proPack = creditPack("pro-pack", {
  name: "Pro Pack",
  description: "2500 API credits",
  credits: 2500,
  price: 3500, // $35.00
  currency: "USD",
  creditSystem: "api-credits",
});

export const owo = new Owostack({
  secretKey: process.env.OWOSTACK_SECRET_KEY!,
  catalog: [
    apiCredits,
    starterPack,
    proPack,
    // ... your plans
  ],
});

Parameters

Parameter	Type	Required	Description
`slug`	`string`	Yes	Unique credit pack identifier
`config.name`	`string`	Yes	Human-readable pack name
`config.description`	`string`	No	Pack description shown to customers
`config.credits`	`number`	Yes	Number of credits in the pack
`config.price`	`number`	Yes	Price in minor currency units (e.g. 1000 = $10.00)
`config.currency`	`Currency`	Yes	Currency code (`"NGN"`, `"USD"`, etc.)
`config.creditSystem`	`string`	Yes	Slug of the credit system this pack is tied to
`config.provider`	`string`	No	Override the default payment provider
`config.metadata`	`Record<string, unknown>`	No	Custom metadata

Methods

Credit packs don't have methods like features do. Instead, they're purchased using the addon() method:

// Customer buys a credit pack
const result = await owo.addon({
  customer: "user_123",
  pack: "starter-pack",
});

if (result.requiresCheckout) {
  // Redirect to payment
  res.redirect(result.checkoutUrl!);
} else {
  console.log(`Added ${result.credits} credits`);
  console.log(`New balance: ${result.balance}`);
}

`plan(slug, config)`

Create a plan definition for the catalog.

import { plan } from "owostack";

plan("pro", {
  name: "Pro",
  price: 500000,
  currency: "NGN",
  interval: "monthly",
  features: [
    apiCalls.limit(50000, { overage: "charge", overagePrice: 100 }),
    aiCredits.credits(1000),
    analytics.on(),
    seats.limit(20),
  ],
});

Parameters

Parameter	Type	Required	Description
`slug`	`string`	Yes	Unique plan identifier
`config.name`	`string`	Yes	Human-readable plan name
`config.price`	`number`	Yes	Price in minor currency units (e.g. kobo)
`config.currency`	`Currency`	Yes	Currency code (`"NGN"`, `"GHS"`, `"ZAR"`, `"KES"`, `"USD"`)
`config.interval`	`PlanInterval`	Yes	Billing interval (`"monthly"`, `"yearly"`, etc.)
`config.features`	`PlanFeatureEntry[]`	Yes	Array of feature entries from `.limit()`, `.credits()`, etc.
`config.description`	`string`	No	Plan description
`config.planGroup`	`string`	No	Group for upgrade/downgrade logic
`config.trialDays`	`number`	No	Trial period in days
`config.autoEnable`	`boolean`	No	Auto-assign this plan to new customers (default: `false`)
`config.metadata`	`Record<string, unknown>`	No	Custom metadata

`owo.sync()`

Push the catalog to the API. Creates and updates features, credit systems, and plans.

const result = await owo.sync();

Returns `Promise<SyncResult>`

interface SyncResult {
  success: boolean;
  features: { created: string[]; updated: string[]; unchanged: string[] };
  creditSystems: { created: string[]; updated: string[]; unchanged: string[] };
  plans: { created: string[]; updated: string[]; unchanged: string[] };
  warnings: string[];
}

CLI: `owo sync`

Push a catalog from the command line.

npx owosk sync [options]

Option	Description
`--config <path>`	Path to config file (default: `./owo.config.ts`)
`--dry-run`	Show what would change without applying
`--key <api-key>`	API secret key (or set `OWOSTACK_SECRET_KEY` env var)
`--url <api-url>`	API URL override

Example config file

// owo.config.ts
import {
  Owostack,
  metered,
  boolean,
  entity,
  creditSystem,
  plan,
} from "owostack";

const apiCalls = metered("api-calls");
const aiCredits = creditSystem("ai-credits", {
  features: [apiCalls(1)],
});

export default new Owostack({
  secretKey: process.env.OWOSTACK_SECRET_KEY!,
  catalog: [
    plan("starter", {
      name: "Starter",
      price: 0,
      currency: "NGN",
      interval: "monthly",
      features: [aiCredits.credits(1000)],
    }),
    plan("pro", {
      name: "Pro",
      price: 500000,
      currency: "NGN",
      interval: "monthly",
      features: [aiCredits.credits(50000)],
    }),
  ],
});

Create plans & features

On this page

AI Chat