Managed Edge API

Managed edge API mode is the simplest way to use Guapocado.

Your app keeps normal product data in its own database. Guapocado stores and serves billing state through the hosted API.

Architecture

Request flow:

1. User makes a request to your app.
2. Your app resolves the billing customerId.
3. Your app creates a Guapocado SDK client.
4. Your app checks a feature, limit, usage balance, or context.
5. Your app allows, blocks, redirects to checkout, or consumes usage.

const guap = createGuapocadoClient({
  apiKey: process.env.GUAPOCADO_API_KEY!,
  customerId,
});

if (!(await guap.has("advanced-analytics"))) {
  return Response.json({ error: "Upgrade required" }, { status: 403 });
}

What You Deploy

You deploy:

• your app
• billing.config.ts
• environment variables with Guapocado keys

You do not deploy:

• Guapocado database tables
• Stripe webhook projection workers
• billing migrations

Framework Fit

Managed edge API mode works well with:

• Hono on Cloudflare Workers
• Express on Node
• Next.js route handlers and server actions
• serverless functions
• background workers

Use a server key in server-side code:

GUAPOCADO_API_KEY=sk_guap_test_...

Use a client key only for browser-safe reads:

NEXT_PUBLIC_GUAPOCADO_CLIENT_KEY=ck_guap_test_...

Checkout

Checkout is a server-side action because it requires a server key:

const checkout = await guap.checkout.create({
  productKey: "pro",
  successUrl: `${origin}/billing/success`,
  cancelUrl: `${origin}/billing`,
});

return Response.redirect(checkout.url);

Usage Writes

Consume usage on the server after you know the work should count:

await guap.usage.consume("api-calls", 1);

For work that can fail, consume after success or refund on failure:

await guap.usage.consume("exports", 1);

try {
  await runExport();
} catch (error) {
  await guap.usage.refund("exports", 1);
  throw error;
}

Operational Checklist

Before live:

• Push config to test.
• Test checkout in test.
• Test feature, meter, and limit checks.
• Push config to live.
• Use live server keys in live runtime.
• Use live client keys only in browser-safe reads.
• Confirm Stripe webhooks are connected for the live environment.