diff --git a/website/content/api-docs/system/internal-counters.mdx b/website/content/api-docs/system/internal-counters.mdx
index 3aae794ffcbe..e4ba873caccd 100644
--- a/website/content/api-docs/system/internal-counters.mdx
+++ b/website/content/api-docs/system/internal-counters.mdx
@@ -263,6 +263,8 @@ not have namespace attribution for the `new_clients` stanza. Furthermore, the
`new_clients` counts returned for the current month will be an approximation.
That is to say, the response will appear as follows.
+ @include 'auto-roll-billing-start-example.mdx'
+
```json
{
"months":[
@@ -342,8 +344,8 @@ This endpoint was added in Vault 1.6.
### Parameters
- `start_time` `(string, optional)` - An RFC3339 timestamp or Unix epoch time. Specifies the start of the
- period for which client counts will be reported. If no start time is specified, the `default_report_months`
- prior to the `end_time` will be used.
+ period for which client counts will be reported. If no start time is specified, the billing start date will be used.
+ The [billing start date](/vault/docs/concepts/billing-start-date) automatically rolls over to the latest billing year at the end of the last cycle.
- `end_time` `(string, optional)` - An RFC3339 timestamp or Unix epoch time. Specifies the end of the period
for which client counts will be reported. If no end time is specified, the end of the previous calendar
month will be used.
@@ -1072,6 +1074,18 @@ $ curl \
}
```
+
+ As of 1.16.7, 1.17.3 and later,
+ the billing start date automatically
+ rolls over to the latest billing year at the end of the last cycle.
+
+ For more information, refer to the upgrade guide for your Vault version:
+
+ [Vault v1.16.x](/vault/docs/upgrading/upgrade-to-1.16.x#auto-rolled-billing-start-date),
+ [Vault v1.17.x](/vault/docs/upgrading/upgrade-to-1.17.x#auto-rolled-billing-start-date)
+
+
+
## Activity export
This endpoint returns an export of the clients that had activity within the
diff --git a/website/content/docs/concepts/billing-start-date.mdx b/website/content/docs/concepts/billing-start-date.mdx
new file mode 100644
index 000000000000..bbeae765d79e
--- /dev/null
+++ b/website/content/docs/concepts/billing-start-date.mdx
@@ -0,0 +1,21 @@
+---
+layout: docs
+page_title: Billing start date
+description: >-
+ A description of Vault cluster's billing start date used throughout Vault.
+---
+
+# Billing start date
+
+It is the start of the period for which [automated](/vault/docs/enterprise/license/utilization-reporting) and [manual](/vault/docs/enterprise/license/manual-reporting) license utilization data will be reported for a cluster. This is the license start date if you do not have an explicit
+billing start date configured.
+
+Vault also uses the billing start date as a default start timestamp for:
+- [Direct queries via the activity log API](/vault/api-docs/system/internal-counters)
+- [Activity export CLI](/vault/api-docs/system/internal-counters#activity-export)
+
+As of 1.16.7, 1.17.3 and later, Vault clusters will automatically adjust the billing start date to provide a year's worth of utilization data.
+
+@include 'auto-roll-billing-start.mdx'
+
+@include 'auto-roll-billing-start-example.mdx'
diff --git a/website/content/docs/enterprise/license/utilization-reporting.mdx b/website/content/docs/enterprise/license/utilization-reporting.mdx
index a0278d7e91b9..8a90c3ea14c4 100644
--- a/website/content/docs/enterprise/license/utilization-reporting.mdx
+++ b/website/content/docs/enterprise/license/utilization-reporting.mdx
@@ -227,7 +227,21 @@ HashiCorp collects the following utilization data as JSON payloads:
- `entity` - The sum of tokens generated for a unique client identifier
- `nonentity` - The sum of tokens without an entity attached
- `metadata` - Optional product-specific metadata
- - `billing_start` - The billing start date associated with the reporting cluster (license start date if not configured)
+ - `billing_start` - The billing start date associated with the reporting cluster (license start date if not configured).
+
+
+
+ As of 1.16.7, 1.17.3 and later,
+ the billing start date automatically
+ rolls over to the latest billing year at the end of the last cycle.
+
+ For more information, refer to the upgrade guide for your Vault version:
+
+ [Vault v1.16.x](/vault/docs/upgrading/upgrade-to-1.16.x#auto-rolled-billing-start-date),
+ [Vault v1.17.x](/vault/docs/upgrading/upgrade-to-1.17.x#auto-rolled-billing-start-date)
+
+
+
- `cluster_id` - The cluster UUID as shown by `vault status` on the reporting
cluster
diff --git a/website/content/docs/upgrading/upgrade-to-1.16.x.mdx b/website/content/docs/upgrading/upgrade-to-1.16.x.mdx
index a4ba0d15c15a..4ea30571d8c6 100644
--- a/website/content/docs/upgrading/upgrade-to-1.16.x.mdx
+++ b/website/content/docs/upgrading/upgrade-to-1.16.x.mdx
@@ -88,6 +88,14 @@ operation called an activation-flag. The feature is gated until a Vault operator
decides to trigger the flag. More information can be found in the
[secrets sync documentation](/vault/docs/sync#activating-the-feature).
+### Auto-rolled billing start date
+
+As of 1.16.7 and later, the billing start date (license start date if not configured) automatically rolls over to the latest billing year at the end of the last cycle.
+
+@include 'auto-roll-billing-start.mdx'
+
+@include 'auto-roll-billing-start-example.mdx'
+
## Known issues and workarounds
@include 'known-issues/1_16-jwt_auth_bound_audiences.mdx'
diff --git a/website/content/partials/auto-roll-billing-start-example.mdx b/website/content/partials/auto-roll-billing-start-example.mdx
new file mode 100644
index 000000000000..92617914e5ef
--- /dev/null
+++ b/website/content/partials/auto-roll-billing-start-example.mdx
@@ -0,0 +1,8 @@
+
+The default billing start date used in queries and license utilization reporting will be automatically adjusted to the latest billing year. Past year billing information will still be retained.
+
+For example, assume a customer has signed a deal for 3 years with a license start date of Dec 1, 2023. After upgrading to the version with this change, the billing start date
+auto-rolls to the most recent year.
+- If the upgrade happens on Sept 1, 2024, the billing start date will continue to be Dec 1, 2023. Once we reach Dec 1, 2024, the billing start date
+will automatically roll to Dec 1, 2024.
+- If the upgrade happens on Dec 15, 2024, the billing start date should automatically roll to Dec 1, 2024 after upgrade.
\ No newline at end of file
diff --git a/website/content/partials/auto-roll-billing-start.mdx b/website/content/partials/auto-roll-billing-start.mdx
new file mode 100644
index 000000000000..9c670c2c962f
--- /dev/null
+++ b/website/content/partials/auto-roll-billing-start.mdx
@@ -0,0 +1,3 @@
+
+This means that the billing start dates from earlier years will get updated to current calendar year, unless the date has not yet occured this year, in which case
+it will remain in the last calendar year. The billing start date will adjust accordingly for leap years.
\ No newline at end of file
diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json
index c6e4318ec039..a5d713ba3a2c 100644
--- a/website/data/docs-nav-data.json
+++ b/website/data/docs-nav-data.json
@@ -257,6 +257,10 @@
"title": "Resource Quotas",
"path": "concepts/resource-quotas"
},
+ {
+ "title": "Billing Start Date",
+ "path": "concepts/billing-start-date"
+ },
{
"title": "Client count",
"routes": [