killbill · KBbitsP · Sep 15, 2026
diff --git a/html5/_main_toc.html.slim b/html5/_main_toc.html.slim
@@ -330,6 +330,9 @@ nav.sidebar-nav
         li
           a.nav-link href="/latest/how-to-install-the-aviate-plugin.html"
             | Aviate Plugin Installation
+        li
+          a.nav-link href="/latest/aviate-tenant-settings.html"
+            | Tenant Settings
         li
           a.nav-link href="/latest/aviate-database-migrations.html"
             | Database Migrations

diff --git a/userguide/aviate/aviate-getting-started.adoc b/userguide/aviate/aviate-getting-started.adoc
@@ -47,6 +47,8 @@ For the purpose of this guide, use the following fictive company:
   ** United Kingdom (GBP)
   ** France (EUR)
 
+For the full set of organization options-including logo and brand color-and how they interact with invoice and email templates, see the https://docs.killbill.io/latest/aviate-tenant-settings.html[Aviate Tenant Settings] guide.
+
 The following demo shows how you can configure the organization settings via Aviate.
 
 :storylane-id: eykmjqwtc4vf

diff --git a/userguide/aviate/aviate-tenant-settings.adoc b/userguide/aviate/aviate-tenant-settings.adoc
@@ -0,0 +1,172 @@
+= Aviate Tenant Settings
+
+:card-badge: Premium
+:card-title: Aviate
+:card-link: https://aviate.killbill.io/
+:card-description:
+include::{sourcedir}/includes/premium-card.adoc[]
+
+== Overview
+
+The *Settings* screen groups the configuration that applies to a single tenant. It is reached from *Configuration -> Settings* in the left navigation.
+
+Settings are scoped to the tenant of the currently selected deployment. Switching deployments reloads the screen with that tenant's values.
+
+The *Organization* tab holds your company details and branding, and is described in full below. The remaining tabs expose Kill Bill per-tenant configuration properties.
+
+== Organization
+
+The *Organization* tab defines who you are as a business. The values entered here apply by default to invoices, emails, and quotes, so that customer-facing documents carry consistent company details and branding.
+
+=== Company Information
+
+[cols="1,3", options="header"]
+|===
+| Field | Description
+
+| Company name
+| The legal or trading name of your business.
+
+| Company address
+| Street address of your business.
+
+| City, province, postal code
+| Remainder of the postal address, entered as a single line.
+
+| Company country
+| Country of your business, selected from a list of ISO countries.
+
+| Company URL
+| Your company website. If no protocol is entered, `https://` is added automatically when the value is saved.
+|===
+
+=== Logo and Brand Color
+
+The Organization tab also lets you upload a *company logo* and choose a *primary brand color*. The logo appears on invoice and email documents, and the brand color is used for styling elements such as invoice table headings.
+
+=== How These Values Are Used
+
+Organization settings act as the defaults for customer-facing documents. Individual invoice templates and email templates can define their own values, in which case those take precedence.
+
+The resolution order is:
+
+. The template-level override, if one is defined.
+. The Organization setting.
+. The built-in default.
+
+This means you can set your company details once on the Organization tab, and only override them where a specific template needs something different.
+
+=== Saving Changes
+
+*Save* becomes active as soon as you change a value. Company information, brand color, and logo are saved independently, so changing one does not rewrite the others. Use *Reset* to discard unsaved changes and restore the values currently stored.
+
+[NOTE]
+On the first save, values still at their defaults are written as well, so that the stored configuration matches what the screen shows.
+
+=== Reading the Stored Values via the API
+
+Organization settings are stored as Kill Bill tenant key-values and can be read through the Kill Bill https://apidocs.killbill.io/tenant.html[Tenant API]. For example, to retrieve the saved company information:
+
+[source,bash]
+----
+curl -u admin:password \
+  -H "X-Killbill-ApiKey: my-tenant" \
+  -H "X-Killbill-ApiSecret: my-secret" \
+  "http://127.0.0.1:8080/1.0/kb/tenants/userKeyValue/COMPANY_INFO"
+----
+
+[NOTE]
+The structure of these values is managed by Aviate. Use the Organization tab to change them rather than writing the keys directly.
+
+== Configuration Tabs
+
+The remaining tabs edit Kill Bill configuration properties for the selected tenant. Rather than repeating the property list here, each field on screen shows the underlying system key (for example `org.killbill.invoice.maxNumberOfMonthsInFuture`), which you can look up in the https://docs.killbill.io/latest/userguide_configuration.html[Kill Bill Configuration Guide] for its meaning, default value, and how else it can be set.
+
+=== Where a Value Comes From
+
+Kill Bill resolves a property from several layers. Each field carries a badge showing the layer the value currently in effect came from:
+
+[cols="1,3", options="header"]
+|===
+| Badge | Meaning
+
+| Default
+| The built-in Kill Bill default; nothing has overridden it.
+
+| Runtime
+| The value comes from the runtime configuration.
+
+| Environment
+| The value comes from an environment variable.
+
+| Tenant
+| A per-tenant value has been set for this tenant.
+|===
+
+Saving a change on one of these tabs writes a per-tenant value, which takes precedence over the global configuration.
+
+=== System-Level Properties
+
+Not every Kill Bill property can be set per tenant. Properties that cannot are listed on the tab under *System-Level Properties* and are shown read-only: they are configured at the system level during deployment, through the Kill Bill properties file or environment variables.
+
+=== Available Tabs
+
+[cols="1,2", options="header"]
+|===
+| Tab | Corresponding section of the Configuration Guide
+
+| Invoices
+| Invoice Properties
+
+| Payments
+| Payment Properties
+
+| Payment Retry
+| Payment Properties (retry schedule)
+
+| Push Notifications
+| Push Notifications Properties
+
+| Events
+| Events Properties
+
+| Subscriptions
+| Subscription Properties
+
+| Catalog
+| Catalog Properties
+
+| JAX-RS
+| Jax-rs Properties
+
+| Server
+| Kill Bill Server Properties
+
+| Database
+| Database Properties
+
+| Read-Only Database
+| RO Database Properties
+
+| OSGI
+| OSGi Properties
+
+| OSGI Database
+| Plugin Database Properties
+
+| Security
+| Security Properties
+|===
+
+=== Setting Per-Tenant Properties via the API
+
+Per-tenant properties can also be set outside the UI, using the https://apidocs.killbill.io/#tenant-add-a-per-tenant-system-properties-configuration[uploadPerTenantConfig] endpoint. Refer to the https://docs.killbill.io/latest/userguide_configuration.html[Kill Bill Configuration Guide] for details and for the full list of properties.
+
+[NOTE]
+Each call to that endpoint overwrites the previous per-tenant properties, so the full list must be supplied every time.
+
+== Related
+
+* https://docs.killbill.io/latest/aviate-getting-started.html[Getting Started with Aviate and Kaui] - initial setup, including organization settings
+* https://docs.killbill.io/latest/userguide_configuration.html[Kill Bill Configuration Guide] - all configuration properties and the ways they can be set
+* https://apidocs.killbill.io/tenant.html[Tenant API] - read and write tenant configuration programmatically