Connect Stripe

1. Add a webhook in Stripe

In Stripe, go to Developers → Webhooks → Add destination, and use this URL:

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

Select these four events: invoice.paid, customer.subscription.created, customer.subscription.updated, customer.subscription.deleted. Then copy the signing secret (whsec_…) and paste it in Dashboard → Payment gateway.

2. Put your Stripe Price on the paid plan

In Stripe, copy the Price id of your paid product (price_…, not the product id). In Access rules, paste it on the matching plan and Save. That is how UsageGate knows which plan a payment is for.

3. Add your user id to Checkout

When a user clicks Upgrade, create the Checkout session with their id in end_user_id, the same id you use with consume and canAccess.

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: user.id },
    // trial_period_days: 7,  // optional free trial
  },
  success_url: `${origin}/billing?ok=1`,
  cancel_url: `${origin}/billing`,
});
return Response.redirect(session.url!, 303);

4. Test it

Put Stripe in test mode, go through your Checkout and pay with the card 4242 4242 4242 4242 (any future date, any CVC). Within a few seconds the user shows on the paid plan in End users.

What happens after that

• Pays or renews: gets the paid plan's full amounts until the end of the billing period.
• Upgrades or downgrades: gets the new plan's amounts.
• Free trial: gets the paid plan during the trial; back to Free if they don't convert.
• Cancels or stops paying: goes back to your Default free plan, keeping at most what they had left. Cancelling never refills credits.

Stripe sometimes sends events twice or out of order; UsageGate handles both. More on timing in monthly refills.