Skip to content
Guapocado

Guapocado Docs

Billing logic your app can actually understand.
Start the quickstart Learn the primitives Install the Agent Skill

Guapocado is a billing layer for developers who want Stripe-backed products without scattering Stripe logic through the app.

Stripe is very good at money movement: customers, prices, checkout, subscriptions, invoices, and webhooks. Your product still needs to answer application questions:

  • Can this workspace use SSO?
  • How many seats can this organization invite?
  • How many AI credits are left this month?
  • Should this API request be blocked, consumed, or allowed as overage?
  • Which plan should the app show on the settings page?

Guapocado lets you define those answers in billing.config.ts, push that config to sandbox or production, and use small SDK calls at runtime:

await guap.has("advanced-analytics");
await guap.limit("seats");
await guap.usage.consume("ai-credits", 250);

The Shape of the System

Section titled “The Shape of the System”

Your app owns the product model:

import { defineBilling } from "@guapocado/sdk";


export default defineBilling({
  entitlements: {
    "advanced-analytics": { type: "feature" },
    "ai-credits": { type: "meter", reset: "monthly" },
    seats: { type: "limit" },
  },
  products: [
    {
      key: "pro",
      pricing: {
        mode: "recurring",
        type: "flat",
        amount: 4900,
        currency: "usd",
        frequency: "month",
      },
      entitlements: {
        "advanced-analytics": true,
        "ai-credits": { included: 40000 },
        seats: { included: 10 },
      },
    },
  ],
});

Guapocado owns the billing projection:

  • Sync config into sandbox or production.
  • Create Stripe products and prices from the config.
  • Receive Stripe webhook events.
  • Project subscriptions, purchases, usage, invoices, and entitlements.
  • Serve a simple runtime API for your app.

Your app owns enforcement:

  • Check features before showing gated UI.
  • Check limits before creating app-owned records.
  • Consume meters when work happens.
  • Decide which app identity becomes the Guapocado customerId.

Who This Is For

Section titled “Who This Is For”

Guapocado is built for product developers who know their app needs billing but do not want to become Stripe infrastructure specialists before shipping.

If your team already has a mature Stripe integration, custom invoice logic, custom metering, subscription item management, and a tested entitlement system, you may prefer to keep using Stripe directly.

If you are trying to ship a SaaS product, AI app, API product, developer tool, or team workspace and need billing checks inside product code, Guapocado gives you a smaller set of primitives to learn first.

Section titled “What to Read Next”

Start with the Quickstart to get a sandbox config pushed.

If you want a coding agent to inspect your app and implement the integration, install the Guapocado Agent Skill.

Then read Billing Primitives before jumping into a framework guide. The primitives are the part that matters most: features, meters, limits, products, customers, checkout, and webhooks.

When you are ready to wire an app:

  • Hono for edge/server APIs.
  • Express for Node servers.
  • Next.js for route handlers and server actions.
  • React for browser-safe feature and usage reads.
  • Better Auth for auth-aware customer mapping.