> For the complete documentation index, see [llms.txt](https://docs.umbcheckout.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umbcheckout.net/v17/getting-started/licensing.md). # Licensing How UmbCheckout 17 licenses work The UmbCheckout core is free and open source. A license unlocks the [Addon features](/v17/getting-started/license-comparison.md) and the support desk. You can [buy a license at umbcheckout.net](https://umbcheckout.net). ### What a license covers * **A license is an annual subscription for a production domain.** The domains it covers are listed on the license, and you can see them on the configuration screen. * **Every running instance needs a license.** A site served by two load-balanced servers (or two containers, or two App Service instances) is two instances. Add a **replica add-on** to your license for each extra instance. * **Staging and development sites** don't need a paid license. Use [development mode](/v17/getting-started/developer-license.md#development-mode) on your own machine, or ask for a free [development license](/v17/getting-started/developer-license.md#development-licenses) for a staging site. ### Setting it up 1. Add the key to `UmbCheckout:LicenseKey` (see [Installing a License](/v17/getting-started/installation.md#installing-a-license)). 2. Set `Umbraco:CMS:WebRouting:UmbracoApplicationUrl` to the site's address, for example `https://www.mysite.com/`. It must be an absolute `http` or `https` URL, and its host must be one of the licensed domains. Without it the site is unlicensed. 3. Check the **License Details** box under **Settings → UmbCheckout → Configuration**. ### Licensed domains are checked on every request Licensed features are only on for requests to a domain on the license (or to its `X-Forwarded-Host`, behind a proxy). A request for any other domain is treated as unlicensed: * its license status reads **Domain not licensed**; * the configuration screen explains this and lists the licensed domains; * the site logs the domain, once. Domains must match exactly: `www.mysite.com` and `mysite.com` are different domains, and there are no wildcards. To add a domain, [open a ticket in UmbPanel](https://www.umbpanel.io) and ask UmbHost to add it. Background work (scheduled tasks, the webhook's handlers outside a request) isn't affected. ### The license warning on your shop When a site has a license key but a request isn't licensed, every front-end page shows a red banner at the bottom: > **UmbCheckout is not licensed for [www.mysite.com](http://www.mysite.com)** (Domain not licensed). Licensed shop features are switched off. Site owner: see the licence details in the UmbCheckout settings in the Umbraco backoffice. The status in brackets says why. The banner is never shown: * on a site without a license key (the free version); * in the backoffice; * before the license has been checked for the first time; * on responses that aren't HTML pages. ### How the license is checked The license is checked in the background, never while a page is loading. * Each instance checks in with the license server about once an hour. A restarting instance uses its saved license straight away and checks in when it is due. * **If the license server can't be reached,** the site retries after 1, 5 and 30 minutes, then every 30 minutes. Meanwhile a license verified in the last 30 days stays in force, so an outage doesn't switch your features off. * **When an instance shuts down gracefully,** it releases its place on the license, so a replacement (for example during a deployment) can take it straight away. * **If an instance crashes,** its place is freed once it has been silent for 90 minutes. * **When the license has no room for another instance,** that instance is unlicensed (status **Invalid**, and the banner shows), and the log says "The licence has no room for another instance". It tries again regularly, so it is licensed once a place is free. * An expired, suspended or cancelled license switches the licensed features off at the next check. The **Re-Check License** button on the configuration screen checks with the license server at once and shows the result. It can be used once every 5 minutes. The license server is only ever contacted at `www.umbpanel.io` over HTTPS. If your server restricts outgoing traffic, allow it. ### License statuses | Status | Meaning | | ------------------- | ---------------------------------------------------------------------------------------------------------- | | Active | Licensed | | Development | Licensed features are on in [development mode](/v17/getting-started/developer-license.md#development-mode) | | Domain not licensed | This request is for a domain the license doesn't list | | Invalid | The key isn't valid for this site, or the license has no room for another instance | | Expired, Suspended | The subscription has ended or been suspended | | Unlicensed | No license key, no valid `UmbracoApplicationUrl`, or the license hasn't been checked yet | {% hint style="info" %} While a debugger is attached, a production license is off (development licenses and development mode are exempt). Licensed features come back when the debugger detaches. {% endhint %} ### Upgrading from v13 UmbCheckout 17 needs an UmbCheckout 17 license. A license for UmbCheckout 1.x on Umbraco 13 doesn't change and keeps working there. See [Upgrading from v13](/v17/getting-started/upgrading-from-v13.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.umbcheckout.net/v17/getting-started/licensing.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.