Using Gater with Stripe billing

If you're using Stripe to manage subscriptions and gater for entitlement management, integrating the two can unlock powerful billing and access control flows.

This guide walks through how to utilise Stripe webhooks to:

• Automatically assign entitlements when a user subscribes to a plan
• Revoke access when a subscription is canceled or fails
• Report usage-based consumption back to Stripe for metered billing

By connecting Stripe's billing logic to gater's entitlement engine, you can create a robust, automated system that tracks user access, seats, tokens, or features—all based on their subscription status.

Set entitlement when subscription is created

When a customer.subscription.created or invoice.payment_succeeded webhook event is received from Stripe, you can set the user's entitlement in gater based on the plan they've subscribed to.

// setup logic
// import axios, { AxiosInstance } from "axios";
// import { Stripe } from "stripe";
 
// const gater = axios.create({
//   baseURL: "https://api.gater.dev",
//   headers: { "X-Api-Key": process.env.GATER_SECRET },
// });
 
async function handleSubscriptionCreated(
  subscription: Stripe.Subscription,
  gater: AxiosInstance
) {
  const user = subscription.metadata.user_id; // assuming you attached this during checkout
  const macro = subscription.items.data[0].plan.id; // price maps to gater macro
 
  const payload = { user, macro };
 
  await gater.post("/set", payload);
}

Reset entitlement to 0 when subscription is canceled

When a customer.subscription.deleted or invoice.payment_failed webhook event is received, set the relevant entitlement to quota 0 with no reset, effectively disabling access.

async function handleSubscriptionCanceled(
  subscription: Stripe.Subscription,
  gater: AxiosInstance
) {
  const user = subscription.metadata.user_id;
 
  const payload = { user, macro: "cancel_tokens" };
 
  await gater.post("/set", payload);
}

Report usage to Stripe for usage-based billing

If you use Stripe metered billing, you can report the current usage tracked in gater before an invoice is finalized (i.e. when Stripe sends the invoice.upcoming webhook).

Workflow:

• On invoice.upcoming, query the user's usage from gater
• Report that usage to Stripe using the Billing Meter Events API

async function handleUpcomingInvoice(
  invoice: Stripe.Invoice,
  gater: AxiosInstance,
  stripe: Stripe
) {
  const user = invoice.metadata!.user_id;
  const customerId = invoice.customer as string;
 
  const params = { user, feature: "tokens" };
  const meter = "api_tokens"; // Stripe meter event name
 
  const entitlement = await gater.get("/check", { params });
 
  const usage = entitlement.data.usage as number;
 
  // Send meter event to Stripe
  await stripe.billing.meterEvents.create({
    event_name: meter,
    payload: {
      stripe_customer_id: customerId,
      value: usage.toString(),
    },
  });
}

Summary

With just a few webhook handlers, you can build a seamless integration between Stripe and gater that handles:

• Provisioning entitlements based on the Stripe plan purchased
• Automatically revoking access when subscriptions are canceled or unpaid
• Real-time usage reporting for metered features like tokens or API calls

This ensures users always have the right level of access, and your billing is kept in sync with actual usage—without manual intervention

Whether you're building SaaS, dev tools, or API-based products, this integration gives you the power and flexibility to scale confidently.