From empty workspace to billed usage.

Once your account and company exist, the first stop is the Access rules table. 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 commercial package. Paste a Stripe Price id on paid columns. Mark one unpaid plan as Default free so signup and cancel fall back there.

Feature keys are what your backend calls. Pick boring, stable names — renaming later means updating every canAccess call.

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

Type a number for credits or caps. Tick on-off features. An empty cell means that plan does not include the feature. Save publishes the draft. A collapsed Graph preview shows the generated Plan → Feature → Limit links if you want to inspect them.

Navigate to API keys, press Generate key, then copy the gk_live_… value from the shown-once panel. If you lose it, revoke and issue a new one.

USAGEGATE_KEY=gk_live_…

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

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.

Dashboard → Stripe. Paste the webhook signing secret, add the acct_… account hint, then Save secret. That is the loop closed: plans sell, invoices pay, entitlements refresh.

Server-side only. The key from chapter 02 stays in your env — never ship it to the browser.

npm install @usagegate/sdk

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

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

Call grantPlan once with your existing user id. UsageGate fills every cell from the Free column and renews it each month. Free users never need a Stripe customer.

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

Ask about a feature key, do the work, then burn. canAccess returns a boolean. Empty balance → 402. Paid refills come from Stripe, not another grant call.

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

const result = await doTheWork();

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

When a Free user clicks Upgrade, start a subscription on the Price you pasted on that plan column. Tag it with your user id. The webhook from chapter 04 fills the paid cells — do not call grantPlan or grant() after Checkout.

• price_… = the Stripe price id on the paid column
• end_user_id = the same id you used in grantPlan
• Switching Price later (Starter → Pro) is the same path

import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function POST(req: Request) {
  const { userId } = await req.json();

  const session = await stripe.checkout.sessions.create({
    mode: "subscription",
    line_items: [{ price: "price_pro", quantity: 1 }],
    success_url: `${process.env.APP_URL}/billing?ok=1`,
    cancel_url: `${process.env.APP_URL}/billing?canceled=1`,
    subscription_data: {
      metadata: { end_user_id: userId },
    },
  });

  return Response.json({ url: session.url });
}

There is no Trial column in UsageGate. Use Stripe’s trial on the paid Price. While status is trialing they get the paid cells. If they convert, they stay paid. If they cancel, they return to Free.

• Same Price as the paid column — do not add a Trial plan
• Do not use grant() for this

import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function POST(req: Request) {
  const { userId } = await req.json();

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

  return Response.json({ url: session.url });
}