Skip to content
License Server v1.39.0 · released 17 Nov 2026release notes →
Skip to content

Storefront auto-fulfillment ​

Connect your storefront once, and every purchase after that issues a license and emails the buyer their key — with no integration code on your side. You paste one URL into your storefront, tell License Server which product each purchase is for, and the fulfillment happens without you.

Three storefronts are supported: Stripe Payment Links (and Stripe Checkout), Lemon Squeezy (from License Server 1.7.0) and Paddle Billing (from 1.11.0). From License Server 1.8.0, a full refund revokes the license by default — see Refunds. From 1.9.0, a subscription keeps one license whose expiry follows what's been paid — see Subscriptions — and from 1.19.0, a refund of one of its payments takes back the time that payment bought — see Refunds of subscription payments. From 1.13.0, its tier, limits and seats follow the plan the customer is on — see Plan changes and seats. Gumroad, Paddle Classic and custom checkouts aren't supported.

Which path applies to you

Hosted account: set this up in the console, under Settings → Storefront webhooks: see On a hosted account.

Self-hosted: the console that ships in the self-hosted bundle doesn't include the Storefront webhooks screen (its Settings area is hosted-only), so set this up through the Storefront Auto-Fulfillment endpoints, which do everything that screen does: see Self-hosted: the same steps through the API.

The API reference documents every endpoint, for automation on either deployment and for troubleshooting a delivery.

What this replaces, and what it does not

This removes the integration work, not the decisions. You still choose what each product issues — tier, seats, limits, duration — and those choices are per product, set once. Getting one of them wrong is quiet: every purchase through that mapping inherits it, and the buyer's license is already in their inbox before you notice. The duration_days warning below is the one that has actually caught someone out.

Setting it up ​

On a hosted account, you do all of it in the console, and On a hosted account is the whole setup. Self-hosted, the console in the bundle has no Settings page, so you make the same changes through the API: see Self-hosted: the same steps through the API. The storefront side, step 2, is the same either way.

On a hosted account ​

Everything here is in the console, under Settings → Storefront webhooks.

1. Connect. Click Connect Stripe, Connect Lemon Squeezy or Connect Paddle. A webhook for that storefront appears, marked Needs setup, with its Callback URL and a Copy button. It ignores purchases until step 3 is done. Keep the console open in another tab.

Paddle asks which environment first: choose Sandbox or Live, then Connect. Paddle's events don't say which account sent them, so the webhook says it, and it can't be changed afterwards. To go live after testing in the sandbox, disable the sandbox webhook and connect a live one.

The last part of the callback URL, the webhook's ID, is not a secret. It is the routing part of a URL, exactly as a Stripe webhook endpoint URL is, and every route that accepts it checks server-side that it belongs to you.

2. Add the webhook in your storefront, and get its signing secret.

  • Stripe: Developers → Webhooks, and add a destination (an endpoint). Stripe asks for the events first, listed alphabetically (so charge.refunded comes before the checkout.session events). Select these four:

    charge.refunded
    checkout.session.async_payment_failed
    checkout.session.async_payment_succeeded
    checkout.session.completed

    charge.refunded is what revokes a license on a refund (1.8.0+). If you sell subscriptions (1.9.0+), select four more:

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

    On an endpoint at Stripe API version 2025-05-28.basil or later, also select invoice_payment.paid (1.19.0+). If you chose the latest API version when you created the endpoint, it is. The event links each subscription payment to its refunds, so a refund of a subscription payment can act on the license; older API versions are covered in Refunds of subscription payments. Select it on this endpoint, the one whose URL contains /v1/webhooks/storefront/. Selecting it on another endpoint in the same Stripe account (your own app's, or a billing webhook) doesn't count. Test mode and live mode each need it.

    Then click Continue. If Stripe asks what kind of destination, choose Webhook endpoint. Paste the callback URL from step 1 as the endpoint URL. Stripe then shows the endpoint's signing secret (whsec_...), which you can reveal again later on the endpoint's page.

    Test mode and live mode are separate in Stripe: each has its own endpoints, signing secrets and Payment Links (so its own plink_... IDs), and a test purchase made in live mode is a real charge. Set the webhook up in test mode first if you want to try it. The console takes the signing secret only while a webhook is still Needs setup, and allows one Stripe webhook that isn't disabled, so going live afterwards means disabling the test webhook, connecting Stripe again (a new callback URL, for a live-mode endpoint), and recreating the mappings with the live Payment Links' IDs. (On servers before 1.9.0, a Payment Link with a recurring price made a subscription checkout that was ignored; from 1.9.0 it issues a license — see Subscriptions.)

  • Lemon Squeezy: Settings → Webhooks → +, with the callback URL from step 1 and two events: order_created, and order_refunded for refunds (1.8.0+). If you sell subscriptions (1.9.0+), add all of these — above all the two payment events, since without them a subscription never extends:

    subscription_created
    subscription_updated
    subscription_cancelled
    subscription_resumed
    subscription_expired
    subscription_paused
    subscription_unpaused
    subscription_payment_success
    subscription_payment_recovered
    subscription_payment_refunded

    subscription_payment_refunded (1.19.0+) is what a refund of a subscription payment acts on.

    Lemon Squeezy doesn't generate a signing secret: you choose one, and type the same one in both places. It must be 16–40 characters. The console's Generate button, next to the webhook's Signing secret field, makes a suitable one. If you're testing in Lemon Squeezy's test mode, create the webhook while test mode is on: test-mode webhooks only receive test orders.

  • Paddle: Events → Notifications → New destination, the path Paddle's developer docs give (its help center still says Developer tools → Notifications for Paddle Billing, so look under whichever your dashboard shows), type URL, with the callback URL from step 1 and these events:

    transaction.completed
    adjustment.created
    adjustment.updated

    transaction.completed issues licenses and extends subscriptions; the two adjustment events are refunds and chargebacks, including (1.19.0+) refunds of subscription renewals, with nothing more to add. If you sell subscriptions, add:

    subscription.created
    subscription.activated
    subscription.updated
    subscription.trialing
    subscription.past_due
    subscription.paused
    subscription.resumed
    subscription.canceled

    Optionally add api_key.expiring, api_key.expired and api_key.revoked, so the webhook is flagged as soon as its API key (step 3) stops working. Once saved, the destination shows its secret key, starting pdl_ntfset_. Create the destination in the same environment (sandbox or live) as the webhook.

3. Save the signing secret. Back in the console, paste it into the webhook's Signing secret field and click Save secret. The webhook changes to Active, except a Paddle webhook, which also needs the API key below. The secret is the real trust boundary: every delivery is verified against it using the storefront's own signing scheme, so nobody can fake a purchase by calling the URL directly.

Paddle also needs an API key. Paddle's events name the buyer only by a customer ID, so License Server looks each buyer's email up in Paddle. In Paddle, My account → Settings → Authentication → API keys → New API key, with only the Customers: read permission, and a custom expiry one year out — Paddle's maximum — rather than the 90-day default or no expiry at all. Paste it under the webhook's API key and click Save API key. License Server checks the key with Paddle before saving it, refuses one from the other environment, stores it encrypted and never shows it again. A Paddle webhook stays Needs setup until it has both the secret and the key. Paddle can't confirm that a key has only Customers: read (a key with more passes too), so keep that part to yourself.

4. Map a product. Tell License Server what a purchase should issue: which purchase it matches, which product, which tier, and optionally seats, limits and duration. Under the webhook's Product mappings, click Add mapping and fill in Reference type, the reference itself (What a mapping matches lists them), Product ID, Tier, and optionally Max activations (optional) (blank means one machine), Duration in days (optional), Limits (optional, JSON) and Notes (optional), then click Add mapping. A price, product or variant mapping also offers Activations per unit (optional), for per-seat plans and for Lemon Squeezy or Paddle products sold per machine, and every mapping offers Free inactive machines with License Server 1.14.0 or later; both are described below. Read duration_days defaults to perpetual before leaving Duration in days blank, since a mapping can't be edited later.

5. Tell Stripe buyers their key is coming (optional). Stripe's default confirmation page after payment says nothing about a license. Set the Payment Link's custom confirmation message in its After payment settings, for example "Your license key is on its way to your email."

That's the setup. Make a test purchase and the license appears in your license list, with the email already sent, and the purchase appears under the webhook's Deliveries: see Watching it work. Licenses from test purchases keep working after you go live: see Sandbox licenses after you go live.

Self-hosted: the same steps through the API ​

Self-hosted, call your own License Server with its admin API key, which the bundle generates: see Installation. The examples use https://your-license-api.com as a stand-in for your server's address: put yours in its place (the self-hosted bundle answers on http://localhost:3001 on the machine running it).

Automating a hosted account

The same calls work on a hosted account, if you'd rather script them than use the console. Send them to https://license-cloud-api.casazium.com (not license-cloud.casazium.com, which is the console), and use your account's API key from the console's Settings → API access in place of $ADMIN_API_KEY. A hosted account never accepts ADMIN_API_KEY.

1. Connect, with "provider" set to "stripe", "lemonsqueezy" or "paddle". A Paddle webhook also needs "environment", "sandbox" or "live", which can't be changed later:

bash
curl -X POST https://your-license-api.com/v1/admin/storefront-webhooks \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "paddle", "environment": "sandbox" }'

The response's id makes the callback URL: https://your-license-api.com/v1/webhooks/storefront/{id}, with your server's address. The webhook starts out pending: it ignores purchases until step 3 is done. The callback URL must be your server's public HTTPS address (PUBLIC_BASE_URL), not localhost; see Self-hosted: the email needs configuring.

2. Add the webhook in your storefront, exactly as in step 2 above, with that callback URL. For Lemon Squeezy, choose a secret of 16–40 characters yourself.

3. Save the signing secret:

bash
curl -X POST https://your-license-api.com/v1/admin/storefront-webhooks/{id}/secret \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "secret": "whsec_..." }'

That flips a Stripe or Lemon Squeezy webhook to active (POST /admin/storefront-webhooks/{id}/secret). A Paddle webhook also needs its API key, created as in step 3 above:

bash
curl -X POST https://your-license-api.com/v1/admin/storefront-webhooks/{id}/api-key \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "api_key": "pdl_sdbx_apikey_..." }'

The same checks apply as in the console (POST /admin/storefront-webhooks/{id}/api-key). With the secret and the key both saved, the webhook switches to active.

4. Add a mapping for each thing you sell (POST /admin/storefront-webhooks/{id}/mappings):

bash
curl -X POST https://your-license-api.com/v1/admin/storefront-webhooks/{id}/mappings \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ref_kind": "payment_link",
    "external_ref": "plink_1UIaMlQu14RJmyaQ1x5Tw53t",
    "product_id": "my-app",
    "tier": "pro",
    "max_activations": 3,
    "duration_days": 365
  }'

ref_kind and external_ref are the reference: see What a mapping matches. Step 5, the Stripe confirmation message, is set in Stripe either way.

What a mapping matches ​

StorefrontConsole Reference typeAPI ref_kindValue
StripePayment Linkpayment_linkthe Payment Link's ID (plink_...), not its buy.stripe.com address
Lemon SqueezyVariantvariantthe variant's numeric ID
PaddlePricepricethe price's ID (pri_...)
PaddleProductproductthe product's ID (pro_...), covering all its prices
StripeMetadata (casazium_ref)metadatayour own casazium_ref value, in the Payment Link's metadata
Paddlecasazium_ref (API checkouts)metadatayour own casazium_ref value, in the transaction's custom data (API-created transactions only)
StripePrice (subscription plans)price (1.13.0+)a subscription plan's price ID (price_...): follows the plan, never issues a license at checkout
StripeProduct (subscription plans)product (1.13.0+)a subscription plan's product ID (prod_...): follows the plan, never issues a license at checkout

Finding a Stripe Payment Link's ID. Payment Links are under Payments → Checkout → Payment links in the Stripe Dashboard (Stripe moves its menus, so search the dashboard for "Payment links" if they aren't there). Open the link: its plink_... ID is at the end of the address in your browser's address bar (.../payment-links/plink_...) and in the Events list on the link's page. It is not the https://buy.stripe.com/... URL you share with buyers. From License Server 1.16.0 (and in Console 1.12.0 with any server), a mapping with that URL is refused, with where to find the ID. Before that it was accepted but never matched, so every purchase through the link was recorded as unmapped. Such a mapping made earlier is left as it is: if a Payment Link mapping's reference doesn't start with plink_, delete it and add it again with the ID. Purchases already recorded unmapped aren't issued afterwards; issue those licenses yourself.

product_id (the console's Product ID) is your License Server product, the software the key unlocks, not the storefront's product. A mapping you leave without max_activations issues licenses for one machine.

Selling subscriptions on Stripe? Map each Payment Link (it issues the license) and each price (it keeps the license in step with the plan and seat count), with the same product_id. See Plan changes and seats.

casazium_ref goes in Stripe Checkout Session metadata, which comes from your Payment Link (or your own API call), not from the buyer. When a purchase matches both kinds of Stripe mapping, the casazium_ref one wins.

Lemon Squeezy mappings match by variant only. A buyer can add custom data to any Lemon Squeezy checkout link, so a casazium_ref there can't be trusted to say what was bought.

Per-seat pricing (1.13.0+). For "$8 per seat per month", give a price, product or variant mapping activations per unit instead of max_activations: the machines for each seat or unit bought. On a subscription it follows the seat count as it changes; on a one-time Lemon Squeezy or Paddle purchase it multiplies the quantity bought. A mapping takes one or the other, and a Payment Link or casazium_ref mapping can't take it, so a one-time Stripe checkout can't be sold per unit. See Plan changes and seats and Per unit on one-time purchases.

Freeing inactive machines (1.14.0+). A mapping can also give its licenses a lease (lease_seconds; Free inactive machines in the console), so a machine that stops checking in gives up its seat when another machine needs one. See Seats that free themselves.

Paddle mappings try the price first, then the product, so a monthly and a yearly price of one product can share a mapping. A casazium_ref counts only on a transaction created through Paddle's API, which needs your API key: Paddle.js lets the buyer's browser set custom data on a checkout, and hosted checkout links can't carry it at all. Map by price or product unless you create transactions yourself.

You can have one active webhook per provider, so Stripe, Lemon Squeezy and Paddle can run side by side. Connecting a second webhook for the same provider returns 409: disable the first if you are replacing it.

Sandbox licenses after you go live ​

From License Server 1.20.0, each license from a storefront purchase records whether the purchase was live or a sandbox (test-mode) one: livemode is true or false in verify-license, the license list and the offline license file. Licenses you issue by hand or through the API have no mode (null).

Licenses from your sandbox purchases keep working after you go live, until you refuse them. If you tested on the product you sell, refuse them once you're live, per product:

bash
curl -X PATCH https://your-license-api.com/v1/admin/products/<id> \
  -H "Authorization: Bearer your-tenant-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "test_licenses": "refuse" }'

<id> is the product's id from GET /v1/admin/products (self-hosted, use ADMIN_API_KEY). That product's sandbox licenses then answer as a revoked license does, everywhere a buyer uses one. Licenses with no mode are never affected. "test_licenses": "allow" turns them back on.

Most licenses issued before 1.20.0 have no mode, so the switch doesn't reach test purchases made before 1.20.0 reached your server or account: revoke those by hand. GET /v1/list-licenses?livemode=unknown lists them, along with licenses issued by hand.

Offline license files exported before the switch keep verifying offline until they expire, since the check runs on the buyer's computer. The file signs livemode, so your app can reject livemode: false itself: see What the file signs.

In console 1.15.0 it's Accept licenses from sandbox purchases in a product's Edit, and Licenses shows which licenses came from sandbox purchases. Details are in Refusing sandbox licenses once you go live.

What a purchase does ​

A buyer completes checkout. Your storefront posts the event to your callback URL. License Server verifies the signature, finds the mapping that matches, and issues the license through the same internal path POST /issue-license uses — not a parallel implementation. The buyer gets an email with their key and, if the end-user portal is enabled, a link to manage it themselves. The email and the portal name your product as What the buyer sees describes. From License Server 1.17.0 you can instead deliver the key yourself: the license is issued, and nobody is emailed.

Retries are safe in both directions. The storefront retrying the same purchase never issues a second license — issuance is idempotent per purchase — and if the license was issued but the email failed, the retry redelivers the email without re-issuing the key.

How long a storefront keeps retrying differs. Stripe retries a failed delivery for days. Lemon Squeezy retries only three times, over about two and a half minutes, so after an outage on your side, resend the webhook yourself (see below). Paddle makes up to 60 attempts over about two days on a live account; in the sandbox, 3 attempts within about two minutes.

Paddle: the buyer's email comes from the API key. License Server issues the license, then looks the buyer up with the webhook's API key. If Paddle is briefly unreachable or rate limiting, it answers Paddle with a retry status (the license is already issued) and Paddle's retry sends the email. If the key itself is dead (revoked, expired, or from the other environment), retrying won't help: the license is issued, the email waits, and the webhook is flagged with the problem. Save a working key, then use Send pending deliveries (below). Paddle sends the buyer its own receipt as well; the license email is separate.

Lemon Squeezy: orders older than 7 days are ignored. Lemon Squeezy's signature has no timestamp, so a captured request would stay valid forever. License Server ignores any order whose signed creation time is more than 7 days old, which stops a replayed request from issuing a second license later. A resend within 7 days of the order works normally.

Lemon Squeezy order statuses: paid and partially refunded orders issue a license; failed and fraudulent orders are recorded as error; pending and refunded orders are logged and ignored.

What the buyer sees ​

From License Server 1.17.0 and Console 1.13.0, each product has two settings for its buyers, on the console's Products page (hosted accounts and the self-hosted bundle's console alike) or through PATCH /v1/admin/products/:id. A product appears there once a license or a release names it, as a storefront purchase's license does; Add product (POST /v1/admin/products) sets one up before its first sale.

Display name. The name buyers see: the license email's subject (Your Acme Pro license) and text, and the license portal's title and heading. Leave it empty to use the product ID. It must pass these rules, which the console and the API both check, with the reason when one fails:

  • 1 to 80 characters: letters, numbers, spaces and . , & ' - ( ) + : / ! # ® ™;
  • no mixed alphabets or look-alike characters, and no invisible characters;
  • no web or email address, which includes a dotted word ending in a real top-level domain: acme.shop and Foo.app are refused, while Node.js, license.lic and setup.dmg pass. If your product's real name ends in a real domain, ask support to approve it.

A product ID is shown to buyers only if it passes the same rules. Otherwise it's left out: the email's subject reads "Your license", and so does the portal's title. A product ID like com.acme.pro (.pro is a real top-level domain), or one with _ or @ in it, falls into this. The Products page marks such a product, "Buyers see 'your purchase' - set a display name" (the console's wording; the email reads "Your license" and "the app"); set one.

License file. Offer the license file in the buyer portal (offline_file through the API) is on by default. Turn it off if your app only takes the license key: the portal hides its Download license file button, and the download link answers "This product doesn't use a license file. Enter your license key in the app instead." Your own exports through the API (/v1/license-export/file and /offline, or their deprecated GET forms) are unaffected.

Refunds ​

From License Server 1.8.0, a full refund revokes the license the purchase issued. This is the default for every webhook, including ones connected before 1.8.0. It needs the refund event enabled in your storefront (step 2): Stripe charge.refunded, Lemon Squeezy order_refunded, Paddle adjustment.created and adjustment.updated. From 1.19.0, a refund of a subscription payment acts too, by its own rules: see Refunds of subscription payments.

To keep licenses after refunds instead, set the webhook to record only: in the console, When a purchase is fully refunded → Keep it (record only) (the webhook's row then shows Refunds: record only), or PATCH /admin/storefront-webhooks/{id} with { "refund_policy": "record" } self-hosted. That covers refunds of subscription payments too. Whichever you choose:

  • Partial refunds are only recorded. A partial refund is usually a goodwill discount, not a return.
  • A purchase refunded before its license is issued never gets one (for example, a refund that arrives before a delayed payment settles). It shows as Refunded first (refunded_before_issue).
  • A refunded purchase is never emailed its key, even if the email hadn't gone out yet.
  • A full refund is final. If you reinstate a revoked license (POST /revoke-license with "revoked": false), a storefront retry or resend of the refund won't revoke it again.

Things to know:

  • Offline license files can't learn about a revocation. A file the buyer already downloaded keeps verifying offline until it expires — for a perpetual license, forever. Apps that check the key online (the SDK's verifyKey) see the revocation straight away. If refunds must stick offline, issue time-limited licenses (duration_days) or have your app re-check online from time to time.
  • Stripe purchases made before 1.8.0 can't be matched to a refund: Stripe's refund event names only the payment, which License Server records from 1.8.0 on. Revoke those by hand.
  • Lemon Squeezy: a full refund more than 7 days old (by its refunded_at) is ignored, for the same replay reason as orders. To test a refund in test mode, send it through Lemon Squeezy's refund API (for example with curl): in our testing, refunding a test order from the Lemon Squeezy dashboard failed, while the API refund worked.
  • Paddle: a refund counts once Paddle approves it. Live refunds usually start as pending approval, and the license is revoked when the approval arrives; in the sandbox, Paddle approves them automatically within about ten minutes. A refund is full when it reaches what the purchase was charged, even though Paddle's dashboard labels a refund of every line item "partial" (1.12.2+, for purchases recorded on 1.12.2 or later; an older purchase is judged by Paddle's label alone). A chargeback, or an early chargeback warning, counts as a full or partial refund the same way. If you win a chargeback, the license is not restored automatically: reinstate it by hand. Credits aren't refunds and change nothing.
  • Refunds of purchases older than the retention period (400 days by default) find no purchase record; revoke those by hand too.

The deliveries list shows what each refund did (below).

Refunds of subscription payments ​

From License Server 1.19.0, a refund of a subscription payment acts under the webhook's refund policy, on Stripe, Lemon Squeezy and Paddle. Under revoke, the default, a full refund takes back what that payment paid for, and nothing more:

The refunded paymentThe license
The subscription's only paid payment that hasn't been refunded (usually its first)Is revoked. A free trial's or a 100% coupon's $0 invoice doesn't count as paid.
The latest payment, with paid ones before it that haven't been refunded (a renewal)Rolls back to the end of what's still paid for, with no grace. If that date has passed, the license is expired, not revoked, and a later renewal extends it again. A license you set to never expire by hand isn't changed.
An older payment, while a later payment hasn't been refundedDoesn't change: the refund is recorded only.

A partial refund, or any refund under record, is recorded only. Several partial refunds of one payment that add up to the whole of it count as a full refund.

This can end a license you meant to keep. A goodwill refund of a renewal ends the time that renewal paid for. To keep subscription refunds manual, set the webhook to Keep it (record only), as above, and change licenses by hand.

What each storefront needs (step 2):

  • Stripe depends on the endpoint's API version:
    • 2025-05-28.basil or later: add invoice_payment.paid, which links each payment to its refunds. Keep charge.refunded: it's the refund itself.
    • From 2025-03-31.basil to before 2025-05-28.basil: refunds of subscription payments can't be matched, because at these versions no event links a refund to its invoice. Move to a new endpoint at the latest API version (below).
    • Before 2025-03-31.basil: nothing new. The refund's charge already names its invoice.
  • Lemon Squeezy: add subscription_payment_refunded. As with order_refunded, a full refund more than 7 days old (by its refunded_at) is ignored.
  • Paddle: nothing new. The adjustment events you already have carry these refunds.

Checking a Stripe webhook: once an event has arrived, GET /admin/storefront-webhooks shows its api_version and refund_matching: ok (no problem found); needs_api_upgrade (move to a new endpoint, below); or needs_event (this webhook's latest paid subscription invoice arrived more than 10 minutes ago, and its invoice_payment.paid hasn't). Only invoices charged automatically for more than $0 count (a free trial, a 100% coupon, or an invoice Stripe emails to the customer to pay instead doesn't count), so ok before the first such payment doesn't prove the event is there. Before 1.19.1, needs_event showed only a day after a subscription invoice, and looked at every Stripe webhook you'd connected, test and live, so a test-mode subscription could flag a live webhook. After the upgrade to 1.19.1, every webhook shows ok until its next paid subscription invoice. If you saw needs_event under 1.19.0, or sell subscriptions, check invoice_payment.paid is on the storefront endpoint now.

To fix needs_event:

  1. Add invoice_payment.paid to the storefront endpoint in Stripe.

  2. Resend that payment's invoice_payment.paid with the Stripe CLI:

    stripe events resend <evt_id> --webhook-endpoint=<we_id>

    The event's ID (evt_…) is on its page in Workbench → Events; the endpoint's ID (we_…) is on the endpoint's page. Add --live for a live-mode payment; Stripe resends events up to 30 days old. The CLI can resend an event to an endpoint that didn't get it the first time.

A refund from the last 7 days that was waiting then applies. For an older one, resend its latest charge.refunded the same way once invoice_payment.paid has arrived (for several partial refunds of one payment, the latest carries the total). If either event is more than 30 days old, Stripe can't resend it: change that license by hand. A refund of any other payment whose invoice_payment.paid never arrived isn't matched unless you resend that event too, and after you move the endpoint, a refund of a payment made before the move isn't matched either: change those licenses by hand. On a hosted account, console 1.15.0 shows refund_matching as Refunds not matched on the webhook, with steps to fix it, and each purchase shows the latest refund on its subscription.

Things to know:

  • Subscriptions that started before 1.19.0 are never revoked by a refund, not even a refund of their first order, which earlier versions revoked on Lemon Squeezy and Paddle. Revoke those by hand if you need to. A refund of a renewal rolls them back, but never below the paid time they had before you upgraded to 1.19.0.
  • Lemon Squeezy and Paddle: a refund of the first order after renewals no longer revokes outright. It follows the table above, so it's recorded only while a later payment hasn't been refunded.
  • A refunded upgrade rolls the expiry back, but keeps the new plan and seats until the subscription changes plan again.
  • A refund that arrives before its payment's event waits for it for a limited time, and is applied if the payment arrives.
  • Offline license files exported before the refund stay valid to the expiry they were signed with. Have your app treat an online "License has expired" answer as a reason to fetch a fresh file.
  • Stripe disputes aren't refunds here, and change nothing.

Moving a Stripe endpoint to a newer API version ​

Stripe can't change an existing endpoint's API version. Instead:

  1. In Stripe, create a new endpoint with the same callback URL and the same events, choose the latest API version, and add invoice_payment.paid.
  2. Straight away, save the new endpoint's signing secret on your webhook. On a hosted account, use Replace signing secret on the webhook's panel (console 1.15.0; shown while the endpoint's API version can't link refunds, needs_api_upgrade). Self-hosted, or on an older console, use POST /v1/admin/storefront-webhooks/{id}/secret with { "secret": "whsec_..." } (see Self-hosted: the same steps through the API for where to send it). From then on, only events signed with the new secret are accepted.
  3. In Stripe, check the old endpoint for failed deliveries still being retried, and resend each to the new endpoint; for a failed invoice.paid, resend its invoice_payment.paid too.
  4. Delete the old endpoint in Stripe.

Until then the old endpoint's deliveries are refused; that's harmless, as the new endpoint carries the same events. From 1.21.2, refund_matching reads ok once the new endpoint's first event arrives; before 1.21.2 it could read needs_event until the next subscription payment. The webhook keeps its callback URL, mappings and subscriptions. This covers payments made after the change. A refund of an earlier subscription payment still isn't matched: change that license by hand.

Subscriptions ​

From License Server 1.9.0, a subscription keeps one license whose expiry follows what's been paid. The buyer gets their key once, at the first purchase, and keeps it: each renewal moves the expiry forward, and when the subscription ends, the license does too. Renewals send no email.

Map the subscription's Payment Link, variant, or Paddle price or product like any other product, and enable the subscription events (step 2). A subscription's license doesn't use the mapping's duration_days: its expiry comes from the subscription.

Only a payment extends a license. A subscription's status never does on its own: Stripe and Paddle report the next period before they charge for it, and Lemon Squeezy moves the renewal date for changes that charge nothing. So a license is never extended for a period that wasn't paid for. On Paddle, the payment is the renewal's transaction.completed.

WhenThe license
The first purchaseIs issued and emailed. Stripe: valid for the grace period (at least a day) until the first payment arrives, usually seconds later. Lemon Squeezy: keeps the mapping's terms until then. Paddle: the purchase is the first payment, so it runs to the end of the first period, plus the grace, straight away.
A payment (the first, or a renewal)Runs to the end of the period paid for, plus the grace.
A payment failsUnchanged: it runs to the end of what's paid, plus the grace, while the storefront retries. A retry that succeeds extends it again.
The retries run out (unpaid)Expires. It comes back if the customer pays later.
A cancellation (at the end of the period)Runs to the end of what was paid, with no grace. Withdrawing the cancellation restores the grace.
The subscription ends (Stripe and Paddle canceled, Lemon Squeezy expired)Expires at the end, and nothing changes it afterwards. A customer who resubscribes gets a new license.
A payment is fully refunded (1.19.0+)Loses the time that payment paid for, or is revoked if it was the only paid payment that hadn't been refunded: see Refunds of subscription payments.
A trialRuns to the trial's end, plus the grace.
A Paddle pauseLike a failed payment: it runs to the end of what's paid, plus the grace. Resuming charges, and that payment extends it.
A free pause (Lemon Squeezy), or a Stripe paused collection with a resume dateRuns to the resume date, plus the grace. Ending the pause early takes back the unused time, never paid time. A pause with no resume date extends nothing.
A pause that charges nothing and gives nothing (Lemon Squeezy void)Like a failed payment: nothing extends until the next payment.

The grace period is 7 days by default, settable from 0 to 30 per webhook: in the console, Subscriptions: grace period, or PATCH /admin/storefront-webhooks/{id} with { "subscription_grace_days": 14 } self-hosted. It covers the time between a period ending and the renewal's payment event arriving. It is also how long a customer keeps access while the storefront retries a failed payment, and Stripe can retry for weeks: raise it if customers should keep access through the whole retry schedule. Paddle's own guidance is to keep access while it retries, and its retries can also outlast the default: a buyer who pays late lapses, then comes back when the recovered payment arrives. A change applies from each subscription's next event.

Things to know:

  • Offline license files carry the expiry from when they were exported. After a renewal, have your app fetch a fresh file (the SDK's exportLicense) before the old one expires. A license that has already lapsed can't be exported until a payment extends it.
  • The first payment sets the expiry. An expiry you change by hand before a subscription's first payment is replaced by it. After that, a cancellation also overrides an expiry you extended by hand.
  • Refunds. From 1.19.0, a full refund of a subscription payment takes back the time that payment bought, on all three storefronts: see Refunds of subscription payments. Before 1.19.0, Stripe matched no refund of a subscription payment, Lemon Squeezy and Paddle acted only on a refund of the first order, and no storefront acted on a refund of a renewal. License Server doesn't cancel the subscription: unless the license was revoked, the next renewal extends it again, so to end access for good, cancel the subscription in your storefront.
  • Paddle plan changes billed straight away (prorated or in full) count as a payment: a change from monthly to yearly extends the license to the new period's end. A change made with "do not bill" extends it only at the next paid charge. (The tier and seats follow the plan from 1.13.0, whether or not the change is billed — see Plan changes and seats.)
  • Stripe plan changes to a longer period, such as monthly to yearly, extend the license once their invoice is paid, from 1.13.0. Under Stripe's flexible billing (its default for new subscriptions), the switch keeps the billing date and invoices the rest of the year as prorations; when that invoice is paid, the license extends to the new period's end. A same-period upgrade or seat change extends nothing: the time it charges for was already paid. A change that isn't invoiced straight away (prorations left for the next invoice, create_prorations) extends the license only when that next invoice is paid, which for a switch to yearly is a year later. Before 1.13.0, a switch to yearly under flexible billing never extended the license past the old period.
  • Paddle imported subscriptions (for example, migrated from Paddle Classic) have no purchase to issue from, so they never get a license. Issue those by hand.
  • Replacing a webhook keeps subscriptions working: they're tracked by test or live mode, not by webhook. The new webhook starts at the default grace.
  • Lemon Squeezy subscription licenses issued before 1.9.0 aren't linked to their subscriptions and never change; set their expiry by hand. Subscription and payment events more than 7 days old are ignored for a subscription License Server doesn't already know, for the same replay reason as orders.
  • Stripe invoices sent by email (send_invoice): the subscription stays active while the invoice is unpaid, but the license lapses at the end of the paid period plus the grace, until the invoice is paid.
  • Lemon Squeezy plan changes move the expiry only at the next renewal; the tier and machines change at once, from 1.13.0.

Plan changes and seats ​

From License Server 1.13.0 (console 1.9.0), a subscription's license follows the plan the customer is on. When they upgrade, downgrade, switch to yearly, or buy more or fewer seats, the license changes to match, on the same key. Nothing is emailed.

WhatFollowsWhen
Tier, limits and number of machinesthe plan and seat countas soon as the storefront reports the change, paid or not
Expirypaymentsonly when a payment arrives (Subscriptions)

So a customer who upgrades gets the higher tier straight away. If they then don't pay, the license still ends at the end of what they'd paid for, plus the grace.

Terms used here ​

  • Plan: what the subscription is on in your storefront: a Stripe price or product, a Lemon Squeezy variant, or a Paddle price or product. Monthly and yearly are different plans.
  • Seats: the subscription's quantity, the number the customer buys or changes ("5 seats").
  • Machines: the license's max_activations, how many machines it can be activated on.
  • Product: in a mapping, product_id is your License Server product, the software the key unlocks. It's not the storefront's product (Stripe's prod_..., Paddle's pro_...), and every plan of the same app must use the same one.
  • Tier: a name you choose (basic, pro, team), which your app reads from the license.

Setting up plans ​

  1. Map every plan a customer can be on, including both monthly and yearly, all with the same product_id. A plan with no mapping changes nothing (below). Map by:

    StorefrontMap each plan byNotes
    Stripeits price (price_...), console: Price (subscription plans)or its product (prod_...); a price mapping is tried first. Keep the Payment Link mapping as well (step 3)
    Lemon Squeezyits variantthe same mapping issues the license and follows the plan
    Paddleits price (pri_...)or its product (pro_...), which covers all its prices; a price mapping is tried first. Map by price if a product also has recurring add-ons (below)
  2. Choose how many machines each plan gives, on its mapping:

    • a fixed number: max activations (left empty, it's 1);
    • per seat: activations per unit, the machines for each seat bought. With 2 per unit, 5 seats give 10 machines, and the license follows the seat count as it changes.

    A mapping takes one or the other, never both.

  3. Stripe only: keep the Payment Link mapping. A Stripe checkout names only its Payment Link, so the Payment Link (or casazium_ref) mapping issues the license. Seconds later, when the subscription's own event arrives, the price mapping's terms replace the Payment Link mapping's. Give the two the same product_id. Until then a per-seat license has the Payment Link mapping's machines (1 unless you set more).

  4. Already have subscribers? See Existing subscribers.

  5. Check it in Deliveries. Each subscription shows its plan, seat count, and whether a mapping matches it, with the license's tier and machines in use.

An example ​

You sell Basic (3 machines) and Team ($8 per seat per month, 1 machine per seat), each monthly and yearly. Map all four plans with product_id my-app:

PlantierMachines
Basic monthly, Basic yearlybasicmax activations 3
Team monthly, Team yearlyteamactivations per unit 1

On Stripe, also map each of the four Payment Links with product_idmy-app and the plan's tier (a Payment Link mapping can't take activations per unit, so give Team's links max activations 1): eight mappings in all.

What a customer's license does:

The customerTheir license
Buys Basic monthlybasic, 3 machines, expiry at the end of the month plus the grace
Upgrades to Team monthly, 5 seatsteam, 5 machines at once. Expiry unchanged: the month was already paid
Adds 2 seatsteam, 7 machines. Expiry unchanged
Switches to Team yearlyteam, 7 machines at once. The expiry moves to the end of the year when the switch is paid: on Stripe straight away, if the portal invoices immediately; on Paddle, if the change is billed straight away; on Lemon Squeezy, at the next renewal
Downgrades to Basic yearly with 7 machines activebasic, 3 machines. All 7 keep working; no new machine can be activated until at most 2 remain
Cancels at the end of the periodKeeps its tier and machines until the end of what was paid (with no grace), then the license ends

On Lemon Squeezy, a new subscription starts at 1 seat (no quantity picker at checkout); set the seats afterwards (below).

Buying and changing seats and plans, per storefront ​

Stripe

Set the portal to invoice prorations immediately

Under Stripe's flexible billing (its default for new subscriptions), a switch from monthly to yearly keeps the billing date. Unless the portal invoices prorations immediately (always_invoice), the switch isn't paid for until a year later (the portal's default, none, never charges for it; create_prorations leaves it for the next invoice). The expiry stays at the end of the old month, and the customer loses access after the grace while their subscription is active.

  • At checkout: turn on the Payment Link's option to let customers adjust the quantity, or every purchase is 1 seat.
  • In the customer portal, plan switches and seat changes reach the license. In the portal's settings:
    • list each product with the prices customers may switch between, and allow quantity changes for per-seat plans;
    • turn on payment-method updates (Stripe requires it for plan changes);
    • invoice prorations immediately (proration_behavior: always_invoice), or, through the API, reset the billing date (billing_cycle_anchor: now). See the warning below.
    • The portal offers one price per billing interval for each Stripe product, so two monthly plans on one Stripe product can't be switched there. Make them separate Stripe products, or offer them as monthly and yearly. Decide this before you create them.
  • Through the API or dashboard, any change to the subscription's items or quantity reaches the license the same way.
  • Scheduled changes: a downgrade scheduled for the end of the period (a subscription schedule, as the portal creates when set to downgrade at period end) reaches the license when it takes effect. An update held until payment (pending_if_incomplete) reaches it once it's paid.

Lemon Squeezy

  • At checkout: the hosted checkout shows no quantity picker on a store's default settings, so a purchase usually starts at 1 seat.
  • Change seats through Lemon Squeezy's API: PATCH /v1/subscription-items/{id} with the new quantity. The item's ID is first_subscription_item.id on the subscription (GET /v1/subscriptions/{id}).
  • Change plans through the API (PATCH /v1/subscriptions/{id} with the new variant_id) or the dashboard.
  • The customer portal should send the same subscription_updated event for a plan change, which the license follows, but it couldn't be tested: Lemon Squeezy shows it only once a store is activated, even in test mode.

Paddle

  • At checkout, the seats are the item's quantity; the price's quantity range limits what can be bought.
  • The customer portal doesn't change plans or seats. Make those changes through Paddle's API (PATCH /subscriptions/{id} with the new items and a proration_billing_mode) or the dashboard. A change billed straight away (prorated_immediately or full_immediately) counts as a payment, so a switch to yearly extends the expiry at once; do_not_bill or a *_next_billing_period mode extends it only at the next paid charge.
  • Recurring add-ons: with several recurring items, the plan is the first one a mapping matches, in Paddle's item order. Map plans by price, not by product, if a product also has add-ons: an add-on listed first would otherwise match the product mapping and become the plan.

Existing subscribers ​

Upgrading to 1.13.0 changes nothing for subscriptions you already have. Their licenses keep their terms until you act:

  1. Map every plan (above).
  2. Let each subscription report its plan. A subscription from before 1.13.0 has no plan recorded until its next subscription event, which records the plan it's on without changing the license, even when that event is itself a plan change. Most get one at their next renewal. To have one sent now, make a small change the storefront reports, such as editing the subscription's metadata (Stripe) or custom data (Paddle). On Lemon Squeezy there's no change that does this; wait for the renewal.
  3. Apply each mapping (below) to give those licenses its terms. Apply finds only subscriptions whose plan is recorded, so do this after step 2, and Apply again later for subscriptions that report after you did: a yearly subscription may not report until its renewal.

Until a subscription's license has been reached by Apply, a plan change by that customer leaves their terms as they were. Deliveries shows which subscriptions have reported a plan. Licenses from subscriptions bought before 1.9.0 aren't linked to their subscriptions, so Apply never reaches them; set their terms by hand.

Adding or editing a mapping later ​

Adding a mapping, or changing one, affects new purchases and future plan changes. It never rewrites licenses already issued on its own. To give its terms to the customers already on that plan, use Apply to existing subscribers… in the mapping's ⋯ menu in the console (self-hosted: POST /admin/storefront-webhooks/{id}/mappings/{mapping_id}/apply). It shows what would change first, each license's tier and machines now and after, and which subscriptions it skips (ended, refunded, another product), and changes nothing until you confirm. Applying replaces terms set on those licenses by hand.

  • Mappings can't be edited, only deleted and created again. In between, a purchase it would have issued isn't issued, subscriptions on its plan show Plan not mapped, and changes to that plan aren't followed, so create the new mapping straight after deleting the old one, then Apply it.
  • Apply a price or variant mapping to reach a plan straight away. A product mapping reaches only subscriptions whose last event matched it (for example, after you delete and create it again); subscriptions on its prices that were recorded while unmapped are reached after their next event.

When a plan can't be followed ​

  • No mapping matches the plan: the license keeps the terms it has, and Deliveries marks the subscription Plan not mapped, showing the plan's price or variant. Add a mapping for it, then Apply it.
  • The plan's mapping has a different product_id than the license: the change is refused, because the key would start unlocking different software. Deliveries marks it Other product. If it's a mistake, delete the mapping, create it again with the right product_id, and Apply it.

Things to know ​

  • What doesn't change the terms: renewals, card changes, a pause, and any other event while the plan and seat count stay the same; and a seat-count change on a plan with a fixed number of machines.
  • Terms set by hand (POST /admin/update-license-terms), including a lease (1.14.0+), last until the customer's next plan change (or seat change, on a per-seat plan), or until you Apply a mapping to them.
  • Fewer seats than machines deactivates nothing: every machine keeps working, and new activations are refused until enough are removed. The console flags these licenses ("More machines than seats").
  • Limits aren't scaled by seats. Only the number of machines follows the seat count; if a limit should grow with seats, have your app read max_activations.
  • Offline license files carry the tier and limits from when they were exported. After an upgrade, have your app fetch a fresh file; a file exported before a downgrade keeps the old tier until it expires (at most the paid period plus the grace).
  • The subscription events must be enabled (step 2): plan changes arrive with them. On Paddle, check that the notification destination sends the subscription.* events; the console warns "Subscription events not received" an hour after a purchase with none.
  • Seat counts are capped at 10,000 per subscription.
  • Moving subscribers to another storefront doesn't carry their licenses: an imported subscription isn't issued one, and the old license ends when the old subscription does. Issue those by hand.

Per unit on one-time purchases (1.13.0+) ​

Activations per unit works on one-time purchases too, on Lemon Squeezy and Paddle: the license is issued with that many machines for each unit bought. A mapping with 1 per unit, bought with a quantity of 25, issues one license for 25 machines; with 2 per unit, a quantity of 3 gives 6. The quantity is the order's on Lemon Squeezy, and the first item's on Paddle.

Stripe one-time checkouts can't use it. A Stripe checkout names only its Payment Link (or casazium_ref) and carries no quantity, and those mappings take a fixed max activations: a one-time Stripe purchase gets the mapping's count whatever was bought. A Stripe price or product mapping never issues a license at checkout.

Things to know:

  • On Paddle, a one-time cart is matched by its first item only. Put the licensed item first. If the first item has no price or product mapping, no license is issued, even when a mapped item comes after it: the purchase is recorded as unmapped (unless it's a transaction you created through Paddle's API with a casazium_ref, which issues from that mapping).
  • The quantity is capped at 10,000. A missing or zero quantity counts as one unit.
  • Lemon Squeezy's hosted checkout may not offer a quantity picker, depending on your store's settings; an order without one is 1 unit.
  • A fixed max activations ignores the quantity: buying 5 still issues one license with the mapping's count.

duration_days defaults to perpetual ​

Omitting duration_days issues a license that never expires

This is the one default worth reading twice. A mapping with no duration_days issues perpetual licenses — no expiration, forever, for every purchase through it. There is no separate "make it expire" step later.

If you are selling a time-limited license as a one-time purchase (an annual license, say), set duration_days on the mapping before the first purchase goes through it. Subscriptions don't use it: their licenses follow the subscription (above).

Mappings cannot be edited after creation — only created and deleted. To change a duration, delete the mapping and recreate it with the same reference. That affects future purchases only; licenses already issued keep the terms they were issued with. To correct one of those, set an expiry on the license directly with POST /admin/update-license-terms. (For a subscription's tier and seats, 1.13.0 can apply a mapping to existing subscribers.)

Watching it work ​

Your record of what each purchase did is the deliveries list — the console's Deliveries table on a hosted account, GET /admin/storefront-webhooks/{id}/deliveries self-hosted. Either way it separates what happened to the purchase from what happened to the email, which fail independently. In the console, a refund's and a subscription's state appear as extra badges in the Outcome column, beneath the outcome itself:

  • Outcome — what happened to issuance: issued, processing, awaiting_payment (a delayed payment method that settles after checkout; not terminal, a later event can still resolve it), unmapped (nothing matched that reference), over_quota, invalid_input, error, or (1.8.0+) refunded_before_issue.
  • Refund (1.8.0+) — what a refund did. In the console: Refunded · revoked, Refunded · kept (the webhook records refunds only), Partly refunded (with the percentage), Revoke by hand (the license couldn't be revoked automatically), Refunded · shortened (the license now ends when its paid time does), Refunded · no license and Refunded first, with the refund's date. Through the API, refund_kind, refund_action, refunded_at and the amounts. From 1.19.0, refund_action can also be rolled_back, and subscription_refund shows the latest refund on any of a subscription's payments, renewals included. From console 1.15.0 a purchase also shows that refund; with License Server 1.21.2 it says whether it was the first payment or a renewal (with its invoice), and a first-payment refund already shown on the purchase isn't repeated.
  • Subscription (1.9.0+) — for a purchase that started one, its state: Subscribed, Trial, Payment due, Canceled, Lapsed (retries ran out) or Ended, with the date it's paid to, ends or ended. A plain Subscription badge means the purchase is linked to a subscription but no subscription event has arrived yet — if it stays, check that the subscription events are enabled. A subscription purchase more than a day old with nothing paid or granted yet is marked No payments yet (on Lemon Squeezy, once a subscription event has linked it to the order), under a warning naming the events to enable: its license is running on the short first expiry (Stripe) or won't extend (Lemon Squeezy). Through the API, subscription_state, subscription_paid_through, subscription_ends_at and subscription_events_missing.
  • Plan (1.13.0+) — for a subscription, the plan it's on (its price or variant, and the seat count), and Plan not mapped or Other product when its license can't follow it (Plan changes and seats). The License column adds the license's tier and machines in use against its seats. A subscription purchase with no event from its subscription an hour after the purchase is marked No events yet (after a day with nothing paid, No payments yet replaces it). Through the API, subscription_plan_item, subscription_quantity, subscription_plan_status, license_tier, license_max_activations and activations_count.
  • Delivery status — what happened to the email. A license can be issued with the email still pending, and the key is valid either way. In the console, Issued & sent means the buyer was emailed — for purchases from License Server 1.15.1 on, and on a hosted account from about 17:40 UTC on 20 October 2026 (before then, the hosted service only logged these emails; see the v1.15.1 release note). Issued · email not sent (License Server 1.15.1+, console 1.11.0+; logged through the API) means the server has no email provider, so the email was only logged and the buyer doesn't have their key yet: see Self-hosted: the email needs configuring. Issued · you deliver (License Server 1.17.0+, console 1.13.0+; vendor through the API) means the webhook is set to deliver the key yourself, so nothing was emailed and nothing will be; it never counts as needing attention.

Held emails (License Server 1.17.0+, console 1.13.0+). When License Server holds a license email back, the purchase stays waiting, shows why under its badges, and counts in Needs attention:

  • Held: daily limit - resend tomorrow: the account has sent its daily limit of 200 license emails in the last 24 hours. Every license email counts, whether a first send, Send pending deliveries or a resend.
  • Held: buyer emails paused: Casazium has paused the account's buyer emails (hosted accounts; for example after spam complaints or bounced addresses). Licenses are still issued. Contact support.

Stripe and Lemon Squeezy don't redeliver a purchase once License Server has answered it, so a held purchase there needs Resend email (below) once the limit allows; on Paddle, Send pending deliveries sends it too. Through the API, the deliveries row's delivery_held is daily_cap or suspended, cleared once the email goes out.

Resend email (License Server 1.16.0+, console 1.12.0+). If a buyer lost their email or never got it, open the purchase's menu (⋯) in Deliveries and choose Resend email… (self-hosted without the console: POST /admin/storefront-webhooks/{id}/deliveries/{checkout_session_id}/resend). It works for every storefront, on any issued purchase that wasn't fully refunded, whether its email was sent, is stuck, was only logged or (1.17.0+) was left to you to deliver:

  • It goes to the buyer's email from the purchase, the license's issued_to, and nowhere else.
  • The buyer gets a new portal link, and the one in their earlier email stops working once the new email has been sent.
  • A purchase can be resent 3 times a day, at least 10 minutes apart, and each resend sent counts toward the account's daily limit of 200 license emails. A resend that fails counts toward nothing.
  • It's refused for a revoked or deleted license, while the server has no email provider, and (1.17.0+) while the account's buyer emails are paused. A Paddle purchase whose buyer email hasn't been fetched yet is refused too: use Send pending deliveries (below), which fetches it. A Paddle purchase whose buyer email couldn't be fetched when it was issued, and was then sent by Send pending deliveries or Paddle's redelivery before 1.16.0, still has a placeholder instead of the email and can't be resent: send that buyer their key yourself. From 1.29.0, so is a purchase whose buyer email isn't a single plain email address (a list, a display name or a domain with no dot, for example): its license was issued, but no email is ever sent to it.
  • A replaced webhook's purchases can be resent from its own Deliveries.

On an older server, redeliver the event from your storefront instead: Stripe's dashboard (Developers → Webhooks → your endpoint), or Lemon Squeezy's webhook page (Settings → Webhooks), within 7 days of the order for Lemon Squeezy. That still works on 1.16.0, since it is the storefront doing the redelivering, and never issues a second license. Past that, send the buyer their key yourself.

Paddle: Send pending deliveries. Paddle doesn't redeliver an event it was answered, and License Server answers once the license is issued, so a purchase issued while the API key was dead waits. Paddle keeps the buyer's email, and License Server can look it up again: once the key works, click Send pending deliveries on the webhook (self-hosted: POST /admin/storefront-webhooks/{id}/send-pending). It emails up to 25 waiting licenses a run and says how many it sent, how many Paddle couldn't find, and how many still wait; run it again until none do. It also covers purchases that reached a webhook you've since replaced, including one set up in the wrong environment. A webhook whose key has a problem shows it on its row, with what to do.

Resolved rows in this table are retained for 400 days by default (see the API reference for the exact rule) before they're pruned — this never affects the license itself, only the row in this list.

A purchase that never reaches the list. A request whose signature doesn't verify is refused before it becomes a delivery, so it isn't in this table. From License Server 1.31.0, GET /admin/storefront-webhooks counts them per webhook (signature_failures_24h) and says when the latest arrived and why (last_signature_failure_at, last_signature_failure_reason); from Console 1.18.0 the webhook's panel shows them too. mismatch or stripe_rejected usually means an old endpoint at the storefront still sends to this URL with its own secret (delete it there), or the signing secret saved here isn't the storefront's current one. Anyone who knows the webhook's URL can cause failures, so if your purchases are arriving you can ignore them.

Delivering the key yourself ​

From License Server 1.17.0 and Console 1.13.0, a webhook can issue licenses without emailing them, for a storefront or app that already emails your customers. You send each key from your own system.

1. Turn it on. On a hosted account, under Settings → Storefront webhooks, set the webhook's Sending the buyer their license to I deliver it myself. Self-hosted, through the API:

bash
curl -X PATCH {your-api-url}/v1/admin/storefront-webhooks/{id} \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "buyer_delivery": "vendor" }'

The console asks first, and says how many of the purchases loaded under Deliveries are still waiting to be emailed: switching leaves those to you too. Every purchase of the webhook not yet emailed moves (still processing, awaiting payment, or issued but not sent), except a fully refunded one; the API's answer counts them in pending_moved_to_vendor. Switching back to Casazium emails the buyer ("email") moves nothing back. Each purchase keeps the setting it arrived under.

2. Find each key. Purchases on such a webhook are issued as usual and recorded as Issued · you deliver (delivery_status vendor). To find one, enter its ID in the purchase lookup above the webhook's Deliveries, whose placeholder names the ID per storefront from Console 1.14.0 — "Find a purchase by its Checkout Session ID (cs_…)", "Find a purchase by its ID (ls_order_…)" and "Find a purchase by its ID (paddle_txn_…)". It shows the purchase's outcome, its license key (with Copy) and the buyer's email. Self-hosted, look it up with GET /v1/admin/storefront-webhooks/{id}/deliveries/{checkout_session_id}, which returns the deliveries row with license_key and buyer_email (license_key is null if that license has since been deleted). Either way, the ID is written as Deliveries shows it:

  • Stripe: the Checkout Session ID (cs_...);
  • Lemon Squeezy: ls_order_ followed by the order's identifier (not its order number);
  • Paddle: paddle_txn_ followed by the transaction ID.

Paddle purchases still fetch the buyer's email from Paddle; if Paddle was unreachable, buyer_email is null until Paddle's retry fetches it. From 1.29.0 it is also null, for any storefront, when the storefront sent something other than a single plain email address as the buyer's email. You can also page the deliveries list or search the licenses list.

3. Send it. From your own system. To include a link to the buyer's license portal, mint one with POST /v1/admin/reissue-portal-token and link to {your-api-url}/portal/{portal_token}. Each call makes a new link, and the previous one stops working.

Good to know:

  • Nothing counts toward the daily limit of license emails, since nothing is sent.
  • Resend email still works. If a buyer says your email never arrived, Resend email on the purchase has Casazium email them anyway, and the purchase becomes Issued & sent.
  • Send pending deliveries has nothing to send on a Paddle webhook set this way, and the console doesn't offer it there.
  • Use Console 1.13.0 or later with it. Older consoles show these purchases as needing attention.

Quotas and plans ​

There is no plan gate on this feature. It works on self-hosted and on every hosted plan, and it is not an add-on.

On a hosted account, the only ceiling is the license quota you already have — 50 active licenses on Free, 1,000 on Pro, 10,000 on Business — which is the same quota every other way of issuing a license counts against. A purchase that would exceed it is recorded as over_quota rather than silently dropped. Self-hosted has no Casazium-imposed license limit.

Self-hosted: the email needs configuring ​

On a hosted account this is already done. Self-hosted, the confirmation email is only logged until you configure a mail provider:

EMAIL_PROVIDER=resend
RESEND_API_KEY=...
EMAIL_FROM="Your Product <licenses@yourdomain.com>"
PORTAL_ENABLED=true
PUBLIC_BASE_URL=https://your-license-api.com

EMAIL_FROM is the sender, on a domain you've verified with Resend. From License Server 1.17.0 it must be a bare address (licenses@yourdomain.com) or a name and an address (Your Product <licenses@yourdomain.com>, the name optionally in double quotes, as above). Anything else, such as a list of addresses or a stray character, stops the server from starting, with a message naming EMAIL_FROM.

EMAIL_REPLY_TO is optional: the address a buyer's reply goes to. From License Server 1.15.2, on a single-tenant server, setting it also adds a line to the email inviting the buyer to reply (not with MULTI_TENANT=true). The other two are not optional:

  • PORTAL_ENABLED=true is required whenever EMAIL_PROVIDER is set to a real provider — License Server refuses to start otherwise, because every email links to the end-user portal and a disabled portal would make each link a 404.
  • PUBLIC_BASE_URL must be the server's public https address: the callback URL and the portal link in each email are built from it. From 1.10.0, License Server refuses to start with a real provider and no PUBLIC_BASE_URL, rather than email buyers a broken link.

If you run the self-hosted bundle, the portal is already on, and you set LICENSE_PUBLIC_URL in its .env instead of PUBLIC_BASE_URL — required once you set EMAIL_PROVIDER there, since that setting reaches License Server too. Otherwise, see .env.example in your release archive.

Two more settings arrived in License Server 1.17.0. Neither is needed on a single-tenant server:

  • RESEND_WEBHOOK_SECRET (optional) records Resend's bounce and complaint reports for license emails. In Resend, add a webhook to {your-api-url}/v1/webhooks/resend with the email.bounced and email.complained events, and set this to its signing secret (whsec_...). Unset, that route answers 404; a value that isn't a whsec_ secret stops the server from starting.
  • RECIPIENT_HASH_KEY keys the hashes of buyer addresses the server keeps for counting bounces and complaints. Single-tenant, leave it unset if you like: the server then uses a random key held in memory, and a restart only resets those counts. It is required with MULTI_TENANT=true, where the server won't start without it; when set, it must be at least 32 characters (openssl rand -hex 32).

Until you do, buyers aren't emailed. Each start of the server logs Buyer license emails are off (EMAIL_PROVIDER=stub), and from 1.15.1 each such purchase shows as Issued · email not sent in Deliveries (delivery_status logged). Once email is configured, redeliver those purchases from the storefront as in Watching it work — Stripe, or Lemon Squeezy within 7 days of the order — or, for Paddle, click Send pending deliveries; each emails the buyer the key they were issued. From 1.16.0, Resend email on the purchase does the same for any storefront, with no time limit. Send pending deliveries and Resend email refuse (409) until email is configured. A purchase from before 1.15.1 was recorded as sent even when its email was only logged, so a redelivery won't send it: find those by the log line Storefront license email (EMAIL_PROVIDER=stub, not actually sent), then use Resend email on each (1.16.0+), or send the buyers their keys yourself. A Paddle purchase whose buyer email couldn't be fetched when it was issued, and was then sent by Send pending deliveries or Paddle's redelivery before 1.16.0, still has the placeholder and can't be resent: send that buyer their key yourself.

Known gaps ​

Worth knowing before you build a storefront around this:

  • Stripe, Lemon Squeezy and Paddle Billing only. Gumroad, Paddle Classic and custom checkouts aren't supported.
  • One license per purchase, from one item. On a Paddle transaction with a subscription, that's the first recurring item a mapping matches (from 1.13.0; before it, the first recurring item); otherwise the first item.
  • Subscriptions need License Server 1.9.0, and the subscription events enabled; plan and seat changes need 1.13.0. Refunds of subscription payments need 1.19.0 and, on Lemon Squeezy and on recent Stripe endpoints, one more event; a Stripe endpoint from 2025-03-31.basil to before 2025-05-28.basil can't match them, and needs replacing with a new endpoint (Moving a Stripe endpoint to a newer API version).
  • No bulk import. Mappings are added one at a time — fine for a few products, tedious for a large catalog.
  • Replacing a webhook means recreating its mappings. Disabling a webhook is one-way (a disabled webhook refuses a new secret, refund setting or mapping with 409), and mappings aren't migrated: add the same ones to the new webhook. From 1.10.0 the disabled webhook's mapping for the same Payment Link or variant gives way; before it, it blocked the new one with 409. Subscriptions carry over to the new webhook.

Next steps ​