How it fits together
Clavem never touches the payment. The customer pays you in Stripe, as they do today. Stripe sends events to a webhook endpoint that Clavem registers in your account. Clavem checks the signature, then issues, extends, expires or disables licenses to match. You keep Stripe as your system for money, tax and invoices.
Clavem does not process card data. It never sees card numbers, and it reads only the objects listed below.
Create a restricted key
The quickest way: open Stripe with the key already filled in, check the permissions and press Create key. To try it in test mode first, use the test mode link. The same buttons are in your dashboard under Settings.
To do it by hand, open Developers in the Stripe dashboard, then API keys, and choose Create restricted key. Name it Clavem and set exactly these permissions. Leave everything else at None.
| Resource | Access | What Clavem uses it for |
|---|---|---|
| Products | Read | Listing your products for the mapping screen, and checking that the key works. |
| Prices | Read | Showing prices in the mapping screen, so you can map one price rather than a whole product. |
| Checkout Sessions | Read | Reading the line items of a paid checkout to know what was bought, and how many. |
| Subscriptions | Read | Reading the paid period of a subscription, which sets the license's expiry. |
| Customers | Read | Reading the buyer attached to a purchase. |
| Invoices | Read | Reading the period a renewal invoice paid for. |
| Charges and Refunds | Read | Reading whether a charge was refunded. |
| Webhook Endpoints | Write | Registering Clavem's webhook endpoint in your account, and removing it when you disconnect. |
Use a test mode key first (it starts with rk_test_), then connect a live key (rk_live_) when you are ready. Clavem also accepts a full secret key, but a restricted key limits what a leaked one could do.
Connect it to Clavem
Open Settings in the dashboard, choose Stripe, and paste the key. Clavem then:
- Checks that the key can list products and Checkout Sessions. If not, nothing is saved and you are told what Stripe said.
- Creates a webhook endpoint in your Stripe account, pointing at a private URL of the form
https://clavem.io/api/stripe/hook/<a private id>, subscribed to six events. The endpoint is pinned to a fixed Stripe API version so the payloads keep the shape Clavem reads. - Stores the key and the endpoint's signing secret, encrypted, with the encryption key held outside the database.
checkout.session.completed
checkout.session.async_payment_succeeded
invoice.paid
customer.subscription.updated
customer.subscription.deleted
charge.refundedAn account has one Stripe connection. A test key makes a test connection and a live key a live one. To move from one to the other, disconnect and connect again. Stripe product ids differ between modes, so map the live products again.
Map Stripe products
A purchase issues a license only for a Stripe product you have mapped to a Clavem product. In the dashboard, open the Clavem product and add a mapping:
- A whole Stripe product, so any of its prices issues a license.
- One price of a Stripe product. A mapping to a price wins over a mapping to its product, so you can give a monthly and a lifetime price of one Stripe product different Clavem products.
- A label, optional. It becomes the variant name on the license. Without one, the price's nickname is used.
Quantity counts: three seats in one line item issue three keys, up to 100 per line item. A checkout with several mapped products issues licenses for each. Anything unmapped in the same checkout is left alone. If nothing in a checkout is mapped, no license is issued and the purchase is recorded in your event log as unmapped, so you can fix the mapping and see what you missed.
What each event does
Every event is verified against the endpoint's signing secret. Each event id is processed once, so Stripe's retries and your own replays are safe. If processing fails, Clavem releases the event and answers with an error so that Stripe retries it.
| Event | What Clavem does |
|---|---|
checkout.session.completed | If the session is paid, or needed no payment, and has an email address: creates the order and its private page, issues the licenses for each mapped line item, and emails the buyer the keys and the order link. Subscription licenses expire at the end of the paid period plus three days. One-time licenses follow the product's validity: perpetual, or a number of days. Licenses from a test-mode purchase are marked test_mode. |
checkout.session.async_payment_succeeded | The same, for payment methods that settle later, such as bank debits. When such a session completes unpaid, nothing is issued until this event arrives. |
invoice.paid | For a subscription renewal: moves the expiry of that subscription's licenses to the end of the period the invoice paid for, plus three days, and revives any that had expired. |
customer.subscription.updated | Mirrors the subscription's status. active, trialing and past_due keep the licenses valid, and past_due stays valid while Stripe retries the payment. canceled, unpaid, incomplete_expired and paused expire them. A license you disabled by hand stays disabled. |
customer.subscription.deleted | Expires the subscription's licenses. A license you disabled by hand stays disabled. |
charge.refunded | For a full refund: disables every license from the order and marks the order refunded. A partial refund changes nothing. Orders are found through the payment intent, which one-time Checkout payments have. Refunding a subscription invoice does not disable its license: cancel the subscription, which expires it, or disable the license yourself. |
Plan limits never stop these events. A paid purchase always issues its licenses, even over your plan's limit. Only manual creation and imports pause.
Subscriptions and renewals
A subscription license expires at the end of its paid period plus three days of grace, so a renewal that settles late does not lock a customer out. Clavem evaluates expiry whenever the license is read and runs no background job, which means the API reports expired the moment the date passes, and reports active again as soon as invoice.paid arrives.
A customer who cancels keeps the license until the end of the period they paid for. Stripe sends customer.subscription.deleted then, and the license expires. A license that expired because a payment failed comes back as soon as the payment succeeds: the next invoice.paid revives it. A new subscription after a cancellation is a new purchase and issues a new license.
Renewals are matched to licenses by the Stripe subscription a license was issued under. Licenses created by hand or imported have none, so Stripe events never change them.
Stripe Managed Payments
Lemon Squeezy's migration documentation names Stripe Managed Payments as its recommended destination, at 3.5% plus Stripe fees, with a promotional rate of 1.5% through 1 December 2027. The same documentation says: “Managed Payments does not offer license-key management or file and link hosting.” That is the gap Clavem fills.
Clavem reads Checkout Sessions, subscriptions, invoices and charges from your Stripe account, and Managed Payments purchases are made through Stripe Checkout, so they should produce the objects Clavem listens for. Treat that as a claim to test rather than assume: connect a test key, make one test purchase the way your customers will, and check that the license appears before you move live traffic. If something differs, tell us.
Clavem is not a merchant of record and does not handle tax for you. Whether you need one is a decision about how you sell in Stripe, and Clavem works the same either way. Read the Lemon Squeezy migration guide for the full plan.
Test it
- Connect a test mode key and map a test product.
- Run a checkout with Stripe's test card
4242 4242 4242 4242, any future expiry date and any CVC. - Open Licenses. The new license is there, marked as test, with its order page.
- In Stripe, open Developers, then Webhooks, and the Clavem endpoint. Recent deliveries should be
200. - Refund the payment in full. The license becomes
disabled.
Disconnecting and troubleshooting
Disconnecting deletes the webhook endpoint from your Stripe account and Clavem's copy of the key. If the key was already revoked, Clavem cannot remove the endpoint, so delete it in Stripe yourself. Licenses already issued stay as they are.
| Symptom | Likely cause |
|---|---|
| Stripe did not recognise this key | The key was copied incompletely or has been revoked. |
| Clavem could not register its webhook | The key lacks write access to Webhook Endpoints. |
| Stripe is already connected | An account has one connection. Disconnect it first. |
| A purchase made no license | The product is not mapped (see the unmapped entry in your event log), the checkout had no email address, or a delayed payment has not settled. |
| Deliveries fail with 400 in Stripe | The signing secret no longer matches, for example after you rolled it in Stripe. Disconnect and connect again. |
| A renewal did not extend the license | The license was created by hand or imported, so it has no Stripe subscription, or invoice.paid did not reach Clavem. Check the endpoint's deliveries in Stripe. |