Addon Packs

Credit packs are one-time purchasable bundles that top up a prepaid balance. Instead of simple counters (1 API call = 1 unit), you abstract usage into credits — customers buy credit packs (e.g. $10 for 1,000 credits) and features consume credits at different rates. This guide shows how to set them up and sell them.

Set up a credit system

Credits are scoped to a credit system. A credit system groups related features that share a balance (e.g. "AI Credits").

1. In the dashboard, go to Credit Systems and create one (e.g. "AI Credits").
2. Attach features to plans with a creditCost so usage deducts from the balance:

const aiTokens = metered("ai-tokens", { name: "AI Tokens" });

plan("pro", {
  name: "Pro",
  price: 2000,
  currency: "USD",
  interval: "monthly",
  features: [
    aiTokens.limit(5000, { creditCost: 1 }),
  ],
});

Each call to track() for ai-tokens deducts 1 credit from the customer's balance in that credit system.

Create a credit pack

In the dashboard, go to Add-ons → Credit Packs and create a pack:

The pack is now available for purchase.

Let customers buy credits

Use addon() to initiate a credit pack purchase:

const result = await owo.addon({
  customer: "user_123",
  pack: "500-ai-credits", // credit pack slug
  quantity: 1,
});

if (result.requiresCheckout) {
  // Redirect to payment
  console.log(result.checkoutUrl);
} else {
  // Credits applied immediately (card on file was charged)
  console.log("New balance:", result.balance);
}

If the customer has a payment method on file, the charge happens immediately and credits are added to their balance. Otherwise, a checkout URL is returned.

Adjust quantity

Customers can buy multiple packs at once:

const result = await owo.addon({
  customer: "user_123",
  pack: "500-ai-credits",
  quantity: 3, // 1500 credits total
});

Check the balance

Use check() on a feature in the credit system to see the remaining balance:

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

console.log("Credits remaining:", access.balance);

Consume credits

track() deducts credits automatically based on the feature's creditCost:

await owo.track({
  customer: "user_123",
  feature: "ai-tokens",
  value: 1, // deducts creditCost (1) from balance
});

Variable credit costs

Different features can consume credits at different rates within the same credit system:

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

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

When you track() a feature in a credit system, Owostack deducts the calculated amount automatically:

await owo.track({
  customer: "user_123",
  feature: "gpt-4",
});
// Deducts 20 credits from the "ai-credits" balance