Clavem

Documentation

Connecting Stripe

Clavem listens to your Stripe account and turns paid checkouts, renewals, cancellations and refunds into license changes.

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.

ResourceAccessWhat Clavem uses it for
ProductsReadListing your products for the mapping screen, and checking that the key works.
PricesReadShowing prices in the mapping screen, so you can map one price rather than a whole product.
Checkout SessionsReadReading the line items of a paid checkout to know what was bought, and how many.
SubscriptionsReadReading the paid period of a subscription, which sets the license's expiry.
CustomersReadReading the buyer attached to a purchase.
InvoicesReadReading the period a renewal invoice paid for.
Charges and RefundsReadReading whether a charge was refunded.
Webhook EndpointsWriteRegistering 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:

  1. Checks that the key can list products and Checkout Sessions. If not, nothing is saved and you are told what Stripe said.
  2. 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.
  3. Stores the key and the endpoint's signing secret, encrypted, with the encryption key held outside the database.
Events subscribed
checkout.session.completed
checkout.session.async_payment_succeeded
invoice.paid
customer.subscription.updated
customer.subscription.deleted
charge.refunded

An 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.

EventWhat Clavem does
checkout.session.completedIf 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_succeededThe 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.paidFor 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.updatedMirrors 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.deletedExpires the subscription's licenses. A license you disabled by hand stays disabled.
charge.refundedFor 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

  1. Connect a test mode key and map a test product.
  2. Run a checkout with Stripe's test card 4242 4242 4242 4242, any future expiry date and any CVC.
  3. Open Licenses. The new license is there, marked as test, with its order page.
  4. In Stripe, open Developers, then Webhooks, and the Clavem endpoint. Recent deliveries should be 200.
  5. 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.

SymptomLikely cause
Stripe did not recognise this keyThe key was copied incompletely or has been revoked.
Clavem could not register its webhookThe key lacks write access to Webhook Endpoints.
Stripe is already connectedAn account has one connection. Disconnect it first.
A purchase made no licenseThe 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 StripeThe signing secret no longer matches, for example after you rolled it in Stripe. Disconnect and connect again.
A renewal did not extend the licenseThe 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.