Stripe subscriptions
Map a recurring Stripe price to a policy, and each subscription to it gets one license, valid while the subscription is paid. When the customer stops paying, cancels, or Stripe gives up on a failed payment, the license expires on its own. You don’t renew anything: Stripe charges the customer each period, and LicenseManager keeps their license in line.
Sell the same product monthly, yearly, or both, in any currency: each recurring price is mapped on its own, to the same policy or to different ones.
Set it up
Give the API key the subscription permissions
Subscriptions need the Subscriptions: Read permission on the restricted key. Give it Subscriptions: Write and Customer portal: Write too, both optional: the first lets you cancel subscriptions from LicenseManager, the second lets customers manage their subscription from the customer portal. See permissions.
You can edit the permissions of an existing key in Stripe: then click Check now on the Stripe card.
Create a recurring price in Stripe
In the Stripe dashboard , create a product, or open one, and add a price with Recurring pricing: monthly, yearly, every 3 months, any period. Usage-based (metered) prices aren’t supported.
Map it to a policy
On the Integrations page of your product, click New mapping, pick the price, shown like Acme Pro · $10.00 / month, and the policy. See mapping prices to policies.
Configure the Stripe customer portal
In Stripe, open Settings › Billing › Customer portal and turn it on. Choose what customers can do there: cancel, update their payment method, see their invoices, and optionally switch between your prices or change their quantity. LicenseManager follows every change they make.
Sell it
Create a Payment Link or a Checkout Session in subscription mode with the price. Subscriptions you create from the Stripe dashboard or the API work too.
What a subscription license gets
A subscription license takes the max machines and max offline duration of its policy, like any license. The rest is set by the subscription:
| Setting | One-time license | Subscription license |
|---|---|---|
| Expiration | After the policy’s duration, or never | The end of the paid period, plus the grace period |
| Updates | The policy’s versions | Every version, for as long as the subscription is paid |
| Max machines | The policy’s | The policy’s, times the quantity subscribed |
| Money back guarantee | The policy’s | None: customers cancel the subscription instead |
| Price | What was paid | The price of one period, times the quantity, before taxes |
| Licenses per purchase | One per unit bought | One per subscription |
The policy’s duration, updates and money back guarantee are ignored, so one policy can be sold both ways: Pro for $99 once with a year of updates, or for $10 a month with every update.
The license page shows its Subscription: the price per period, and when it renews, ends, or that its payment failed, linking to the subscription in the Stripe dashboard. Its Meta holds stripe.subscriptionId.
The subscription’s life
The first payment
The license is created when the first invoice is paid, for the customer of the invoice’s email, and its key is emailed to them, as for a one-time purchase. Until then, nothing is created: a subscription whose first payment never succeeds creates no license.
A Stripe trial creates the license right away: its first invoice, of $0, is paid when the trial starts. The license is valid until the end of the trial, then renews with the first real payment.
Renewals
Each time Stripe charges a new period, the license’s expiration is pushed back to the end of the new period, plus the grace period. The key stays the same, nothing is emailed, and the customer has nothing to do. Each payment records a license.payment_succeeded event, with the amount paid before taxes.
Grace period
When a renewal fails, Stripe retries the payment for several days, and the subscription is past due meanwhile. So that customers don’t lose access while Stripe retries, the license stays valid for a grace period after the end of its period: 7 days by default.
Set it on the Subscriptions card of the Integrations page, from 0 to 60 days. Match it to your Stripe retry schedule: when Stripe gives up, the license expires right away anyway. The setting applies to every product of the organization in the same mode, and to the licenses from their next renewal or change.
Each failed payment records a license.payment_failed event, with the attempt number and when Stripe tries again. The customer portal tells the customer their payment failed.
When the subscription ends
The license expires right away when the subscription:
- Is canceled, by the customer from the Stripe customer portal, by you from Stripe or from LicenseManager.
- Is unpaid, or canceled by Stripe, once it gave up retrying a failed payment, depending on your Stripe settings .
- Is paused.
Its expiration is set to when the subscription ended, a license.subscription_ended event records why, and validating its key fails with license_expired, like any expired license. With offline validation, the app keeps working until its license token expires, which is never after the license.
A subscription set to cancel at the end of its period keeps its license until then, without a grace period: the customer paid for that period, and no renewal is expected.
An ended subscription can’t be resumed. When the customer subscribes again, they get a new subscription, and a new license with a new key.
Plan and quantity changes
When the customer, or you, change the subscription in Stripe:
- Another mapped price, like from monthly to yearly, or from Personal to Business: the license moves to that price’s policy, with its max machines and max offline duration. Its key stays the same.
- An unmapped price: the license keeps its policy, and follows the subscription’s new period.
- A new quantity: the license’s max machines become the policy’s times the new quantity. A Business policy of 3 machines subscribed 5 times gives 15 machines.
Changes are recorded as license.updated events by Stripe.
What you can change
Stripe decides the subscription license’s expiration, price, updates and money back guarantee: editing them is refused, since the next renewal would undo the change. Change the subscription in Stripe instead.
You can still edit its max machines, max offline duration and meta. A max machines you set is kept until the quantity or the policy of the subscription changes.
Canceling
Canceling from LicenseManager
Click ⋯ on the license, then Cancel: the license stops working at once, and its Stripe subscription is canceled immediately, without refund nor proration. To let the customer use the period they paid for, cancel the subscription in Stripe at the end of the period instead.
It needs the Subscriptions: Write permission. Without it, LicenseManager can’t cancel the subscription, so it refuses to cancel the license: cancel the subscription from Stripe, and the license expires.
Through the API, POST /v1/licenses/{id}/cancel works the same way, and answers 409 with subscription_managed when the key lacks the permission.
Canceling as a customer
Subscription licenses have no money back guarantee: their card in the customer portal has no Cancel license button. Customers click Manage subscription instead, and cancel from the Stripe customer portal, where Stripe applies your cancellation settings. See managing a subscription.
Refunds
LicenseManager never refunds subscription payments. Refund them from Stripe: as for one-time payments, a refund made in Stripe doesn’t change the license. Cancel the subscription too to stop the license.
Revenue and stats
The Subscriptions section of the product’s Dashboard shows your MRR, active subscriptions, churn and failed renewals, and the Revenue section counts each subscription payment on the day it was paid. See subscriptions.
Edge cases
A subscription with several prices. The license follows the first mapped price of the subscription. Other prices are ignored.
A subscription without a mapped price. Ignored: it creates no license, until its price is changed to a mapped one and an invoice is paid.
Deleting the mapping. New subscriptions to the price no longer create licenses. The licenses already created keep following their subscriptions.
A subscription created before mapping its price. Its next paid invoice creates its license.
Free periods. An invoice with nothing to pay, like with a 100% off coupon, renews the license without recording a payment.
Disputes. A disputed subscription payment doesn’t change the license. If Stripe then cancels the subscription, the license expires.