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.
- Receive the event. Verify the signature on the raw body, then accept
checkout.session.completedandcheckout.session.async_payment_succeeded. The mechanics are in Stripe webhooks for license fulfilment. - 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.
- Check
payment_status. It ispaid,unpaidorno_payment_required. Skipunpaid. A delayed payment method sendscheckout.session.async_payment_succeededlater. - Find the email.
customer_details.emailis the usual place. If there is none, you cannot deliver a key. - 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.
- Create one key per seat. Quantity three means three keys, with a cap.
- Record the order against the session id, with a unique constraint, in the same transaction that creates the keys.
- 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.