Get started with UsageGate

New workspaces already have Free, Starter and Pro filled in. Edit the numbers, or add your own plans and features.

• Plans — Free, Starter, Pro (columns)
• Features — ai_credits, export_pdf, seat_limit (rows)
• Cells — type 10, leave empty, or tick on-off

Use + Plan for each thing you sell. Click the id under a plan name to copy it. Mark one free plan as Default free: that is where customers land when they cancel.

Feature keys are the names your code asks about. Keep them short and stable: renaming one later means changing your code.

await gate.canAccess(userId, "generate_videos");
await gate.consume(userId, "ai_credits", 1);

Type a number for credits or limits, tick on/off features, leave a cell empty for "not included". Then Save.

Open API keys, press Generate key, and copy the gk_live_… value. Lost it? Revoke it and create a new one.

USAGEGATE_KEY=gk_live_…

// server only — never expose this to the browser
const gate = new GateClient(process.env.USAGEGATE_KEY!);

Pick one here, then choose the same one in Dashboard → Payment gateway and Save.

In the Stripe dashboard open Product catalog and press Create product.

Name: Starter. Pricing: Recurring → Monthly → €10.00. Add product.

The product page shows the default price row and the product ID.

Open the price and copy the price_… identifier. That is the value UsageGate stores, not the product ID.

Back in Access rules, paste the price ID into the plan’s Stripe price id field and Save.

Stripe → Webhooks → Add destination. Listen to: Your account.

Search and check exactly these — nothing else is needed.

• invoice.paid
• customer.subscription.created
• customer.subscription.updated
• customer.subscription.deleted

Destination type → Webhook endpoint → Continue.

Endpoint URL, then create the destination.

https://www.usagegate.io/api/webhooks/stripe

On the destination details page, reveal and copy the whsec_… signing secret.

In Dashboard → Payment gateway, paste the signing secret and Save. Stripe and UsageGate are now connected.

On your server only; the key never goes in browser code.

npm install @usagegate/sdk

import { GateClient } from "@usagegate/sdk";

const gate = new GateClient(process.env.USAGEGATE_KEY!);

New users have no plan until you give them one. Call this after sign-up; it is safe to repeat on every login. Free credits refill monthly on their own.

await gate.grantPlan(userId, "plan_free");

Spend a credit first; only do the work if it succeeded. For an on/off feature, use canAccess instead. A "no" is a normal answer: return 402 and offer an upgrade.

const spent = await gate.consume(userId, "ai_credits", 1);
if (!spent.success) {
  return Response.json({ error: "upgrade" }, { status: 402 });
}

const result = await doTheWork();

// On/off feature:
// if (!(await gate.canAccess(userId, "export_pdf"))) return 402;

Create the Checkout session on your paid Price, with your user's id in end_user_id. The webhook from chapter 04 applies the paid plan; don't call grantPlan or grant after it.

const session = await stripe.checkout.sessions.create({
  mode: "subscription",
  line_items: [{ price: process.env.STRIPE_PRICE_PRO!, quantity: 1 }],
  subscription_data: {
    metadata: { end_user_id: userId },
    // trial_period_days: 7,  // optional free trial
  },
  success_url: `${origin}/billing?ok=1`,
  cancel_url: `${origin}/billing`,
});

return Response.redirect(session.url!, 303);