> 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/installation.md).

# Installation

Installing UmbCheckout

**UmbCheckout 17 supports Umbraco 17.6 or later, on .NET 10.**

{% hint style="info" %}
Upgrading a site from Umbraco 13? Read [Upgrading from v13](/v17/getting-started/upgrading-from-v13.md) first.
{% endhint %}

UmbCheckout is installed using the NuGet package manager using the below command:

```
dotnet add package UmbCheckout
```

You will also need to install a [payment provider](/v17/payment-providers/payment-providers.md). The `UmbCheckout` package doesn't include one, so for Stripe also run:

```
dotnet add package UmbCheckout.Stripe
```

Alternatively, you can install using the NuGet package manager GUI within Visual Studio.

UmbCheckout stores the Basket in the .NET session. It adds the session middleware itself, so you don't need to add `app.UseSession()` to `Program.cs` (an existing call is harmless).

* **To change the session settings** (for example the idle timeout or the cookie name), use `PostConfigure` in `Program.cs`. It works in any order:

```csharp
builder.Services.PostConfigure<SessionOptions>(options =>
{
    options.IdleTimeout = TimeSpan.FromHours(2);
});
```

* **Load-balanced sites:** the session is kept in memory unless your site registers a distributed cache. UmbCheckout registers an in-memory one only when none exists, so register a shared one (for example `AddStackExchangeRedisCache` or `AddDistributedSqlServerCache`) and every server sees the same Basket. `SessionOptions` are site-wide.

### Upgrades

UmbCheckout creates the tables it needs when the site starts, so upgrades follow the same process as installation: run the command found above or upgrade using the NuGet package manager GUI.

### Installing a License

If you have purchased a license to enable more features, add the following to your `appsettings.json` file (or, better, to your environment's secrets or environment variables):

```json
  "UmbCheckout": {
    "LicenseKey": "YOUR LICENSE KEY HERE"
  }
```

*Replacing* `YOUR LICENSE KEY HERE` *with the key found in your* [*UmbPanel account*](https://www.umbpanel.io)*.*

You are also required to configure the [UmbracoApplicationUrl](https://docs.umbraco.com/umbraco-cms/reference/configuration/webroutingsettings#umbraco-application-url) within the [Web routing settings](https://docs.umbraco.com/umbraco-cms/reference/configuration/webroutingsettings) within your appsettings.json file. The configuration screen shows a warning while it isn't set.

```json
"Umbraco": {
  "CMS": {
    "WebRouting": {
      "UmbracoApplicationUrl": "https://www.mysite.com/"
    }
  }
}
```

{% hint style="info" %}
**When do I need a license?**

UmbCheckout requires a license to use any of the Addon packages, and every running instance of a production site needs one. See [Licensing](/v17/getting-started/licensing.md) for how licenses work in UmbCheckout 17.

Using UmbCheckout without a license disables the Tax Rates, the payments, invoices and refunds screens, and storing the Basket in a Cookie or the Database.

Licensed sites will also be able to make use of the support ticketing system.

For development and staging sites, see [Development Licenses and Development Mode](/v17/getting-started/developer-license.md).
{% endhint %}


---

# 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/installation.md?ask=<question>&goal=<user_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.