Selling with Stripe
Connect Stripe and Keygate issues a license on payment, sells per-seat plans, and follows plan and seat changes, renewals, trials, failed payments and refunds.
With Stripe connected, selling needs no code of your own. A customer pays on Stripe Checkout, Keygate creates the license and emails the key, and from then on the license follows the subscription: renewals extend it, plan and seat changes carry over, failed payments trigger reminders, and cancellations end it at the right time.
Connect Stripe
Copy your secret key from the Stripe dashboard into .env and restart Keygate:
STRIPE_SECRET_KEY=sk_live_...On startup Keygate registers its own webhook endpoint in Stripe at BASE_URL/api/v1/webhook/stripe and stores the signing secret. You do not create the webhook yourself. Stripe has to reach that address, so BASE_URL must be your public HTTPS address; for testing on your own machine see local development below.
A test key (sk_test_...) puts the install in test mode, and it then accepts test events only. Use a separate install, or switch the key, when you go live.
Link plans to prices
Create the product and its prices in Stripe as usual. Then open each plan in Keygate and paste the matching price ID (price_...) into its Stripe price field.
- A subscription plan needs a recurring price, monthly or yearly.
- A plan sold per seat needs a recurring price for one seat. The subscription's quantity is the number of seats.
- A perpetual plan needs a one time price.
- A perpetual plan with an update period can add a second one time price for renewing it. See update periods.
Selling per-seat subscriptions
A subscription plan can be sold per seat: the buyer chooses how many seats to pay for, and the license holds what those seats buy. Turn on Sell per seat when you create the plan. It cannot be switched later, so to sell the other way, create a new plan.
- Minimum seats and Maximum seats set the range a buyer can choose from. The maximum can be up to 10,000.
- On a SaaS or hybrid product, the seats are the people on the license, the owner included: five seats are the owner and four members. See teams and seats.
- Max activations becomes Devices per seat, or concurrent sessions per seat on a floating plan, and is multiplied by the seats. On a hybrid product those devices are shared by everyone on the license. On a desktop product the seats only multiply the devices.
- Only subscription plans can be sold per seat.
The license records how many seats it is paid for, shown as Seats bought on the license in the dashboard. For a license billed by Stripe, that number always comes from the subscription: Keygate reads it back from Stripe after every change, and it cannot be edited in the dashboard. On a per-seat license that nothing bills, such as one you issued in the dashboard, you set the seats on the license yourself. The per-seat pricing guide covers the plan settings in more detail.
Send customers to checkout
Every plan has a checkout link, shown on the plan in the dashboard. Put it behind the Buy button on your pricing page:
https://licenses.example.com/pay/k3x9q2mfThe link opens a fresh Stripe Checkout session for that plan and brings the customer back to a confirmation page on your Keygate address when they finish.
A free plan has no Stripe price, so its link has nothing to sell. If the plan has Self sign-up turned on, the link opens a sign up form instead, where a visitor claims a free license by confirming their email. See self sign up.
You can also sell through Stripe Payment Links or a Checkout integration of your own. Keygate looks at the price that was bought and finds the plan that uses it, so those purchases create licenses too.
Choosing the number of seats at checkout
For a plan sold per seat, Stripe Checkout opens with the plan's minimum number of seats, and the buyer can change the number on Stripe's page within the plan's range. To start at another number, for example the team size a visitor picked on your pricing page, add quantity to the link:
https://licenses.example.com/pay/k3x9q2mf?quantity=5- A number outside the plan's range answers with an error instead of opening checkout.
- When the minimum and maximum are the same, the buyer cannot change the number.
- On a plan not sold per seat,
quantityabove 1 is refused, and checkout always sells one license.
After the payment
- Stripe reports the completed checkout to Keygate.
- Keygate creates the license on the plan that was bought, for the customer's email, with the number of seats the subscription bills.
- The customer receives an email with the key, and a download button if the product has a download link.
- Your webhooks receive a license.created event, if you subscribed to it.
A missed webhook does not cost you a sale. Stripe sends it again, Keygate also confirms the purchase when the customer lands on the confirmation page, and every five minutes it checks Stripe for recent checkouts it has not seen. Each checkout creates exactly one license, however many of these paths report it.
The customer portal
Customers sign in to the portal at BASE_URL/portal with their email. They see their licenses and keys, and they can:
- free a device they no longer use;
- switch a subscription to another plan, for example from monthly to yearly, and change the number of seats on a plan sold per seat (see changing plans and seats);
- upgrade a license on a free plan to a paid one and keep its key (see upgrading a free license);
- cancel a subscription, at the end of the period or at once;
- download invoices and update their card through Stripe's billing portal;
- renew the update period of a perpetual license.
The billing actions are for the owner of the license only, not for its members. Most of what would otherwise reach your inbox as a support request happens here. The customer portal page covers the rest of the portal.
Changing plans and seats
This section covers how a customer changes an existing Stripe subscription from the portal, and how each kind of change is billed. With Change Plan they move to another subscription plan of the same product; with Change seats they change the number of seats on a plan sold per seat. Moving to a plan sold per seat also asks for the number of seats.
Before anything changes, the customer sees what the change costs, calculated by Stripe with any tax, discounts and account credit, and confirms it. The price shown is good for an hour. If it is older, or the subscription changed in the meantime, they are asked to review it again. Keygate then asks Stripe for the change, and the license takes its new plan and seats from the subscription as Stripe returns it.
More seats or a bigger plan
A change that lowers no limit, such as more seats, a plan with more features or a move from monthly to yearly, is prorated. Stripe invoices the difference for the rest of the current period right away, and the change applies as soon as that invoice is paid. A change that costs less puts the difference on the customer's Stripe balance for future invoices and applies at once.
- If the payment needs another step, such as confirming the card, the portal shows Payment needed with a link to pay the invoice. The subscription stays as it is until then. If the invoice is not paid by the date shown, the change is dropped and nothing is charged.
- While a change waits for payment, the customer can cancel it from the portal, or make another change, which replaces it.
- Stripe can hold a change until it is paid only for some payment methods: cards, wallets, Link, PayPal and the like, not bank debits. A subscription paid another way, or one whose invoices are not charged automatically, cannot make these changes in the portal; the customer is asked to switch to a card or to contact you.
Fewer seats or a smaller plan
A change that lowers the number of seats or the device limit is a downgrade. It applies at once and is not prorated: nothing is charged or credited now, the rest of the period is not refunded, and the next invoice bills the new terms.
- Nobody is removed by a downgrade, so it is refused while more is in use than it leaves: with
SEATS_IN_USEwhen more people are on or invited to the license than the new seats, the owner included, and withDEVICES_IN_USEwhen more devices are activated than the new limit, or on a floating plan more sessions are running. The portal says what to remove first. - A downgrade that lowers one limit while raising another, costs more for the rest of the period, or moves to a price billed on another schedule cannot be made in the portal. The customer is asked to contact you.
When a change is refused
- A subscription that is past due is paid first; then it can be changed.
- One change to a subscription is made at a time.
- A subscription you set up by hand in Stripe, with a schedule, several items or a metered price, cannot be changed in the portal. The customer is asked to contact you.
- The plan to move to has to be an active subscription plan of the same product, and the number of seats has to be within its range.
Changes made in Stripe
Stripe is the record of what a subscription bills. If you change a subscription's price or quantity in the Stripe dashboard, the license follows at Stripe's next event: it moves to the plan that uses the new price and takes the new number of seats. Your webhooks receive plan.changed and license.quantity_changed; see the webhook events.
If the seats drop below the people already on the license this way, nobody is removed: the members who joined last are paused and cannot use their keys until a seat is free. Devices over a lower limit keep working, but no new ones can be activated until enough are freed.
Upgrading a free license
A license on a free plan, one issued in the dashboard or claimed through self sign up, can move to a paid plan of the same product without changing its key. The owner sees an Upgrade button on the license in the customer portal when all of these hold:
- Stripe is connected.
- The license's plan has no Stripe price, update period or renewals, and Stripe does not bill the license already. A license Stripe bills changes plan with Change Plan instead.
- The license is not suspended or revoked. An expired or canceled license can upgrade; paying is how it comes back.
- The product has a plan to upgrade to: an active plan with a Stripe price that is not a trial and does not sell an update period.
The customer picks a plan and pays on Stripe Checkout. Once the payment is confirmed, the same license moves to the new plan: the key and the activated devices stay, and your app sees the new features at its next verify. From then on the license follows its Stripe subscription like any other, or for a perpetual plan, never expires and gets updates for life. Your webhooks receive plan.changed and the customer gets an email about the new plan.
- Upgrading to a plan sold per seat starts checkout with a seat for everyone already on the license, or the plan's minimum if that is more. The customer can choose more seats, but not fewer. A team larger than the plan's maximum cannot move to it, and the portal answers
409 SEATS_IN_USE. While that checkout is open, for at most an hour, no new members can be invited. When the upgrade changes the seats, your webhooks also receivelicense.quantity_changed. - Opening a new upgrade checkout closes the one opened before, so a customer cannot pay twice for the same license. If the earlier one was already paid and is still being applied, the new attempt answers
409 UPGRADE_IN_PROGRESS. - If the license was suspended, revoked or otherwise changed between checkout and payment, the upgrade is not applied. The confirmation page says the payment is being processed, and the server log and the audit log record it. Refund the payment in Stripe, and cancel the subscription for a subscription plan.
- If the payment was refunded, or its subscription ended, before the upgrade could be applied, the confirmation page says the upgrade was not applied.
Back to the free plan
An upgraded license is not revoked or canceled when its payment stops. It goes back to the free plan, with the status, dates and seats it had before the upgrade, and keeps its key. That happens when:
- the upgrade's payment is refunded in full in Stripe;
- its subscription is canceled, or turns unpaid;
- it has been past due for 30 days;
- its period and the plan's grace days run out without a renewal;
- an admin uses Cancel and revoke on it.
Where the subscription is still open, Keygate cancels it in Stripe first. Each of these sends plan.changed with a reason; the webhooks page lists them. If the free plan was deleted in the meantime, there is nothing to go back to, and the license is treated like any other purchase.
Trials billed by Stripe
This section covers a trial that turns into a subscription, sold through Stripe. While the subscription is in its trial, the license is trialing. When the trial ends, Stripe charges the card and reports the result: the license becomes an active subscription, or past due if the charge fails, and follows the subscription from then on. A few days before the end, Stripe announces it and the customer gets the Stripe trial ending soon email.
Stripe's report can arrive some time after the trial's end date. Keygate waits for it for the plan's grace days, and at least one day even when the plan has none, before the hourly check expires the trial. That only happens when Stripe never reports at all, for example when its webhooks were lost for good. Whether the key keeps working during the wait follows the plan's grace days: with none, it stops at the trial's end until Stripe's report arrives.
A trial plan can name a free plan its licenses move to when the trial ends, instead of expiring. That move is for trials nothing bills. A trial Stripe bills is Stripe's to settle and never moves to the fallback plan; if Keygate has to expire it, it expires.
Renewals and failed payments
When a subscription renews, the license's end date moves to the end of the new period. The day before a renewal, the customer gets a reminder that they will be charged.
If a payment fails, the license becomes past due but keeps working while Stripe retries the card. Keygate emails the customer one day, seven days and fourteen days into the problem. Once a payment goes through, the license is active again and the customer is told.
Subscriptions set to cancel
A subscription that will not renew gets expiry reminders instead of renewal reminders, by default seven, three and one day before it ends. You can change the days under email settings.
Cancellations and refunds
- A customer who cancels keeps the license until the end of the period they paid for. Then it ends.
- A full refund of the current period cancels the subscription in Stripe and revokes the license, or puts an upgraded license back on its free plan. A refund of a period already over, or of a charge Keygate can tie to the license only through the customer, changes nothing and is recorded in the audit log: cancel in Stripe if the customer is leaving. A full refund of a renewal takes the renewed time off the update period. A partial refund leaves the license as it is and is recorded in the audit log.
- A lost dispute counts as a full refund, whatever period it was over: the subscription is cancelled, so the same card is not charged again, and the license is revoked or put back on its free plan. Bank debit disputes (SEPA, ACH, Bacs) are final when opened and are acted on then. A dispute that is open or won changes nothing.
- A delayed payment (SEPA, ACH) that fails at checkout issues no license, and the subscription Stripe opened for it is cancelled.
- Cancel and revoke on a license in the dashboard cancels its subscription in Stripe and then revokes the license, or puts an upgraded license back on its free plan. It moves no money: make the refund in the Stripe dashboard. If Stripe does not confirm the cancel, nothing changes and the dashboard says so. A one time purchase has no subscription to cancel; use Revoke for it.
- Revoke on its own does not touch Stripe: on a subscription license the customer keeps being charged, and the license stays revoked. Use Cancel and revoke for those.
Stripe-billed licenses in the dashboard
While a license is tied to a Stripe subscription, Stripe decides its plan, its seats and its end date. The dashboard does not change them behind Stripe's back, because Stripe would keep charging for the old terms:
- Change Plan on the license answers
STRIPE_MANAGED. Change the plan from the customer portal, which moves the subscription in Stripe too, or change the subscription in the Stripe dashboard and let the license follow. - The seats of a per-seat license show as set by the Stripe subscription and cannot be edited. They change in the portal or in Stripe.
- The end date cannot be edited either; renewals move it.
To take a license out of Stripe's hands, for example to move it to a plan you sell another way, cancel the subscription in Stripe first and then use Unlink on the license. Keygate asks Stripe and refuses while the subscription is still there. Once unlinked, the license's plan and end date can be edited in the dashboard again.
Local development
Stripe cannot deliver webhooks to localhost. Use the Stripe CLI to forward them:
stripe listen --forward-to localhost:9000/api/v1/webhook/stripeIt prints a signing secret starting with whsec_. Put it in .env next to your test key and restart Keygate:
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...Now buy a plan through its checkout link with the test card 4242 4242 4242 4242 and watch the license appear in the dashboard.
Frequently asked questions
How do I send a buyer to checkout with a set number of seats?
Add quantity to the plan's checkout link, for example https://licenses.example.com/pay/k3x9q2mf?quantity=5. The number must be within the plan's minimum and maximum seats, or the link answers with an error instead of opening checkout. On Stripe's page the buyer can still change the number within that range, unless the minimum and maximum are the same.
Are seat and plan changes in the customer portal prorated?
A change that adds seats or moves to a bigger plan is prorated: Stripe invoices the difference for the rest of the period at once, and the change applies when that invoice is paid. A change that lowers the seats or the device limit applies at once without proration: nothing is charged or refunded now, and the next invoice bills the new terms.
Why can't a customer lower the number of seats?
Keygate never removes people or devices to make a downgrade fit. The portal refuses with SEATS_IN_USE while more people are on or invited to the license than the new number of seats, the owner included, and with DEVICES_IN_USE while more devices are activated than the new limit. The customer removes members, cancels invitations or frees devices first, then lowers the seats. A subscription that is past due has to be paid before any change.
Can I change the plan or seats of a Stripe-billed license in the dashboard?
No. While a license is tied to a Stripe subscription, Stripe decides its plan, seats and end date, and the dashboard answers STRIPE_MANAGED. Change the plan or seats from the customer portal, which moves the subscription in Stripe too, or change the subscription in the Stripe dashboard and the license follows. To manage the license in Keygate instead, cancel the subscription in Stripe and then use Unlink on the license.
What happens to a license when a Stripe trial ends?
Stripe charges the card and reports the result, and the license becomes an active subscription, or past due if the charge failed. Keygate waits for that report for the plan's grace days, and at least one day, before the hourly check would expire the trial. A trial that Stripe bills never moves to the trial plan's fallback plan.
Last updated October 26, 2026