Clavem

How to add license keys to Stripe payments

Stripe has no license-key feature, so you add one by reacting to checkout.session.completed: read the line items, create one key per purchased seat, store the order against the Checkout Session id, and email the buyer. You can build that yourself or use a licensing service.

The short answer

Stripe takes the payment and tells you about it with a webhook. Adding license keys means writing, or renting, the code that sits between that webhook and the buyer’s inbox. For each paid Checkout Session it must create the right number of keys, remember that it did, and send them. After that, your app needs an endpoint to check the keys against.

The flow below is the same whatever you build it with. The differences between the three options are who runs the code and who is on call when it breaks.

Three ways to get a key after a Stripe payment

Build it yourself Licensing service on top of Stripe Merchant of record with built-in keys
Who takes payment Your Stripe account Your Stripe account The merchant of record
Who handles tax You You, unless you use Stripe Managed Payments The merchant of record
What you write Webhook handler, key generator, database, validation endpoint, email, rate limiting A product mapping and the calls in your app Product setup and the calls in your app
Main risk Bugs in the part customers notice most A new vendor in your launch path Your fees include a share of every sale
Keys survive a vendor shutdown Yes, you own them Only if you can export them and verify offline Only if you can export them

Polar and Dodo Payments both list license keys among their features, and they are payment platforms, so you move your whole checkout. That is a different decision from adding keys to a Stripe checkout you already have. Merchant of record vs Stripe covers it.

The fulfilment flow, step by step

Stripe’s fulfilment guide is specific about the shape. You write one function that takes a Checkout Session id, and webhooks and the success redirect both call it. The function must survive being called more than once, “possibly concurrently”, for the same session.

  1. Receive the event. Verify the signature on the raw body, then accept checkout.session.completed and checkout.session.async_payment_succeeded. The mechanics are in Stripe webhooks for license fulfilment.
  2. Retrieve the session. Call the API for the session by id. Do not trust only what the event carried. Line items are not included on the event object, so expand them or list them.
  3. Check payment_status. It is paid, unpaid or no_payment_required. Skip unpaid. A delayed payment method sends checkout.session.async_payment_succeeded later.
  4. Find the email. customer_details.email is the usual place. If there is none, you cannot deliver a key.
  5. Map each line item to a product. The line item has a Price, and the Price has a Product. Decide which of your products that grants.
  6. Create one key per seat. Quantity three means three keys, with a cap.
  7. Record the order against the session id, with a unique constraint, in the same transaction that creates the keys.
  8. Email the buyer, then answer 200.

Here is the core of it. I ran this against a stub that returns the shapes Stripe’s API returns, with one mapped item of quantity 3 and one unmapped item, and delivered the same session twice:

export async function fulfilCheckout(stripe, sessionId) {
  if (fulfilled.has(sessionId)) return { status: 'already_fulfilled' };

  const session = await stripe.checkout.sessions.retrieve(sessionId);
  if (session.payment_status === 'unpaid') return { status: 'not_paid' };
  const email = session.customer_details?.email ?? session.customer_email;
  if (!email) return { status: 'no_email' };

  const items = await stripe.checkout.sessions.listLineItems(sessionId, { limit: 100 });
  const issued = [];
  const unmapped = [];
  for (const item of items.data) {
    // A mapping for one Price wins over a mapping for the whole Product.
    const m =
      mappings.find((x) => x.stripeProduct === item.price.product && x.stripePrice === item.price.id) ??
      mappings.find((x) => x.stripeProduct === item.price.product && x.stripePrice === '');
    if (!m) { unmapped.push(item.description); continue; }
    for (let n = 0; n < Math.min(item.quantity ?? 1, 100); n++) {
      issued.push({ key: newKey(), product: m.product, email, session: sessionId });
    }
  }
  if (issued.length === 0) return { status: 'nothing_mapped', unmapped };

  fulfilled.set(sessionId, true); // a database: insert order and licenses in one transaction
  licenses.push(...issued);
  return { status: 'issued', count: issued.length, unmapped };
}

The output was { status: 'issued', count: 3, unmapped: [ 'Inkwell sticker pack' ] } the first time and { status: 'already_fulfilled' } the second. In a real system fulfilled is a unique column, because two deliveries can arrive at the same moment and an in-memory check does not stop both.

Failure modes to design for

Situation What happens if you ignore it What to do
Delayed payment method (bank debit) The session completes as unpaid. You issue a key for money you do not have yet. Skip unpaid. Issue on checkout.session.async_payment_succeeded.
No email on the session Key created, nobody to send it to Log it as skipped and surface it in an admin list. Ask Checkout to collect an email.
Same event delivered twice Two sets of keys, two emails Unique order per session id. Stripe retries for up to three days in live mode.
Price not mapped Silent: the buyer paid and got nothing Record it as unmapped and alert yourself. This is the most common launch bug.
Quantity above your cap A loop that creates thousands of keys Cap it, and decide what a quantity of 500 means for your business.
More line items than one page Keys missing for items after the first page Page through line items. Stripe’s guide says to use auto-pagination when a session has many.
Test-mode purchase Test keys mixed with real ones Store livemode on every license and filter on it.
Partial refund Nothing should happen, but your code may revoke Decide the rule before it happens. See refunds for software.

Metadata or a mapping table

You must tell your code which Stripe Price grants which product. There are two common ways.

Metadata on the Price or Product. Put a key such as product_slug in Stripe’s metadata. The handler reads it from the line item’s Price. The benefit is that the mapping lives next to the price in Stripe. The cost is that it is easy to forget on a new Price, and nothing tells you when you did.

A mapping table on your side. A row per Stripe Product or Price pointing at your product, with an optional label. Adding a Price without a row produces the “unmapped” case above, which you can detect. Clavem works this way: a mapping to a whole Stripe Product covers all its prices, and a mapping to one Price wins over it, so a monthly and a lifetime Price of one Stripe Product can grant different Clavem products.

Either way, store the mapping outcome (product, variant label) on the license. Do not recompute it later from the current Stripe Price, which you may have edited since.

Subscriptions change the expiry, not the key

For a subscription, the key should stay the same across renewals and only its expiry should move. The first checkout.session.completed creates the key with an expiry at the end of the paid period. Each invoice.paid moves the expiry to the end of the next period. When the subscription ends, customer.subscription.deleted ends the key. Add a few days of grace, because a card retry can land after the period end. Clavem adds three days.

Doing this with Clavem

Clavem is the second column of the table: it listens to your Stripe account and does the flow above. You create a restricted Stripe key, paste it in, and Clavem registers a webhook for six events. You map a Stripe Product, or one Price, to a Clavem product. A paid session then creates the order, the keys (up to 100 per line item), an order page with the download, and the email. Each Checkout Session is processed once, and an unmapped purchase is recorded in your event log rather than dropped.

Your app calls POST /v1/licenses/activate and /validate with no secret. The Stripe connection guide lists the permissions the key needs and what each event does, and the API reference documents the three calls. Clavem does not take payments or handle tax, and it has no outbound webhooks, so you cannot yet trigger your own system from a Clavem event.

Questions

Can I add license keys to a Stripe Payment Link?

Yes. Payment Links use Checkout, so they produce the same checkout.session.completed event. Your webhook handler cannot tell, and does not need to tell, whether the session came from a link, a hosted Checkout page or an embedded form.

How do I issue three keys when a customer buys three seats?

Read the line item quantity from the Checkout Session and create that many keys. Clavem does this for quantities up to 100 per line item. A hand-built handler needs a loop and a cap.

Where should the license key be stored?

In your own database or a licensing service, never only in Stripe metadata. Metadata is useful for saying which product a Price grants, but it gives you no validation endpoint, no device counting and no revocation.

Sources

  1. Stripe docs, fulfil orders after Checkout (as of November 2026)
  2. Stripe docs, webhooks (as of November 2026)
  3. Stripe API reference, Checkout Session object (as of November 2026)
  4. Polar docs, license keys benefit (as of November 2026)
  5. Dodo Payments pricing page, feature list (as of November 2026)