Licenzy
Usage & credits

Full Licenzy and Stripe integration example

Build the full backend flow from frontend checkout to Stripe payment, webhook processing, Licenzy entitlements, access checks, and optional usage consumption.

Introduction

This guide puts the full Licenzy integration together: a frontend starts checkout through your backend, Stripe collects payment, Stripe sends the tenant webhook to Licenzy, Licenzy updates entitlements, and your backend checks access or consumes usage from the resulting runtime state.

The important boundary is that your app does not treat the browser redirect or raw Stripe payment object as runtime truth. Webhook-processed entitlement state is the source used by access decisions.

Architecture overview

  1. 01Your frontend asks your backend to start checkout.
  2. 02Your backend calls Licenzy with a server-side runtime API key.
  3. 03Licenzy uses the stored Stripe connection to create Checkout.
  4. 04Stripe sends the inbound tenant webhook directly to Licenzy.
  5. 05Licenzy updates entitlements and can emit outbound events.
  6. 06Your backend reads access and optionally consumes usage.

What you'll build

  • A backend checkout endpoint.
  • A browser redirect to the returned checkout_url.
  • A Stripe tenant webhook configured for the required events.
  • A server-side access check after webhook processing.
  • Optional usage consumption with a stable idempotency key.

Step-by-step implementation

  • Create the checkout session.
  • Redirect the customer.
  • Wait for webhook finalization.
  • Read entitlement-backed access.
  • Consume usage when protected work happens.

What you need

  • A Licenzy project and mode.
  • A stored Stripe connection and tenant webhook signing secret.
  • A Licenzy product mapped to a Stripe Price.
  • A server-side Licenzy API key.
  • A stable subject_ref for the customer or workspace.

Step 1 — Create a checkout session

Checkout request
HTTP
POST /v1/checkout/session
Authorization: Bearer lz_test_...
Idempotency-Key: checkout-user_123-pro_monthly-001
Content-Type: application/json

{
  "subject_ref": "user_123",
  "product_code": "PRO_MONTHLY"
}

Use a stable idempotency key for the business checkout attempt.

Step 2 — Redirect the user

Your frontend should redirect to the checkout_url returned by your backend. The frontend should not create Stripe Checkout directly.

Step 3 — Handle payment via Stripe inbound webhook

After payment, Stripe sends the inbound webhook to Licenzy directly. Licenzy verifies the Stripe signature, processes the event idempotently, and updates entitlements.

Do not proxy or replay the inbound Stripe event from your application.

Step 4 — Access is granted via entitlements

Access becomes available only after webhook processing updates entitlement state. Your app reads that state through the runtime API.

Step 5 — Check access from your backend

Use POST /v1/access/check for the smallest decision, or read GET /v1/customer/access/:subject_ref and GET /v1/entitlements/:subject_ref for richer state.

Access check
HTTP
POST /v1/access/check
Authorization: Bearer lz_test_...
Content-Type: application/json

{
  "subject_ref": "user_123"
}

Step 6 — Consume usage (optional)

For usage packs, consume units with POST /v1/usage/consume after the protected work is accepted or completed.

Usage consume
HTTP
POST /v1/usage/consume
Authorization: Bearer lz_test_...
Idempotency-Key: usage-user_123-req_987
Content-Type: application/json

{
  "subject_ref": "user_123",
  "units": 100
}

What not to do

  • Do not grant access from the browser success page.
  • Do not call the tenant Stripe webhook from your app.
  • Do not expose Licenzy API keys or Stripe credentials to the browser.
  • Do not consume usage without a stable idempotency key.
  • Do not reconstruct entitlement state from Stripe objects in frontend code.

Why this matters

The sequence keeps payment, runtime authorization, usage, retries, and operational evidence connected through one backend-owned state model.

Production validation checklist

  • Use customer access and entitlements reads for backend investigation, and use the portal support tooling for operator workflows.
  • Confirm mode alignment across API key, Stripe connection, products, prices, and tenant webhook.
  • Test duplicate webhook delivery and idempotent runtime writes.
  • Confirm outbound receivers verify signatures and deduplicate events.