From 35c1c3321d1bd289e03bcc917923aa4359f6f1e3 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Mon, 16 Mar 2026 00:09:24 +0000
Subject: [PATCH 1/2] Add March 16th changelog: balance carry-over and feature
flags
Generated-By: mintlify-agent
---
apps/docs/mintlify/changelog/changelog.mdx | 36 ++++++++++++++++++++++
1 file changed, 36 insertions(+)
diff --git a/apps/docs/mintlify/changelog/changelog.mdx b/apps/docs/mintlify/changelog/changelog.mdx
index fe2121100..7308311f9 100644
--- a/apps/docs/mintlify/changelog/changelog.mdx
+++ b/apps/docs/mintlify/changelog/changelog.mdx
@@ -4,6 +4,42 @@ mode: "center"
description: "Some new things we've shipped at Autumn HQ"
---
+
+ ## Balance and usage carry-over on plan upgrades
+
+ You can now preserve a customer's remaining balances and usage when they upgrade plans. Two new parameters on `billing.attach` give you fine-grained control over what happens to consumable features during an immediate upgrade.
+
+ - **`carry_over_balances`**: Unused credits or balances from the old plan are carried forward to the new one — so customers don't lose what they've already paid for
+ - **`carry_over_usages`**: Prior usage is deducted from the new plan's allowance, preventing customers from getting a free reset on upgrade
+ - **Per-feature control**: Optionally scope carry-over to specific features using `feature_ids`
+
+ See the [attach API reference](/api-reference/billing/attach) for details.
+
+ ## Feature flags in customer and entity responses
+
+ Boolean features are now returned as a dedicated `flags` object on customer and entity API responses. This makes it easier to check on/off feature access without calling the `check` endpoint separately.
+
+ - **Separate from balances**: Flags live under `flags` in the response, clearly separated from consumable balances
+ - **Available everywhere**: Returned on customer get, list, entity get, and entity create endpoints
+ - **Includes metadata**: Each flag shows the originating plan, expiration, and feature ID
+
+ See the [check endpoint](/api-reference/core/check) and [customer endpoints](/api-reference/customers/getOrCreateCustomer) for the updated response format.
+
+
+
+ - Balance carry-over on immediate plan upgrades via `carry_over_balances` - [#861](https://github.com/useautumn/autumn/pull/861)
+ - Usage carry-over on immediate plan upgrades via `carry_over_usages` - [#875](https://github.com/useautumn/autumn/pull/875)
+ - Boolean features returned as `flags` in customer and entity objects - [#950](https://github.com/useautumn/autumn/pull/950)
+ - Updated API, SDKs, and frontend with new flag fields - [#951](https://github.com/useautumn/autumn/pull/951)
+
+
+
+ - Fixed customer retrieval query causing errors in certain configurations - [#958](https://github.com/useautumn/autumn/pull/958), [#959](https://github.com/useautumn/autumn/pull/959)
+ - Fixed trial upgrade reliability when unsetting trial periods - [#958](https://github.com/useautumn/autumn/pull/958)
+
+
+
+
## Autumn Checkout
From 3f700bf73586111b504097121d9bddbd27530fde Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Tue, 17 Mar 2026 09:54:00 +0000
Subject: [PATCH 2/2] Document explicit customer creation requirement for check
and track endpoints
Generated-By: mintlify-agent
---
apps/docs/mintlify/changelog/changelog.mdx | 22 ++++++++
.../documentation/customers/check.mdx | 54 +++++++++++++++++++
.../customers/creating-customers.mdx | 4 ++
.../customers/tracking-usage.mdx | 4 ++
4 files changed, 84 insertions(+)
diff --git a/apps/docs/mintlify/changelog/changelog.mdx b/apps/docs/mintlify/changelog/changelog.mdx
index 7308311f9..fa1ed0297 100644
--- a/apps/docs/mintlify/changelog/changelog.mdx
+++ b/apps/docs/mintlify/changelog/changelog.mdx
@@ -4,6 +4,28 @@ mode: "center"
description: "Some new things we've shipped at Autumn HQ"
---
+
+ ## Explicit customer creation required for `check` and `track`
+
+ The `/check` and `/track` endpoints no longer auto-create customers. If you call these endpoints with a `customer_id` that doesn't exist, the API now returns a `customer_not_found` error instead of silently creating the customer.
+
+ This change encourages explicit customer lifecycle management and prevents accidental customer creation from typos or stale IDs.
+
+ - **Create customers first**: Call [`customers.getOrCreate`](/documentation/customers/creating-customers) during signup or login before using `check` or `track`
+ - **Handle the error**: If a customer doesn't exist, the API returns error code `customer_not_found`
+
+ ## `autumn-js` SDK 1.0.0
+
+ The `autumn-js` SDK has been promoted from beta to stable at version `1.0.0`.
+
+
+
+ - Explicit customer creation required for `check` and `track` endpoints - [#968](https://github.com/useautumn/autumn/pull/968)
+ - `autumn-js` SDK promoted to `1.0.0` stable release - [#968](https://github.com/useautumn/autumn/pull/968)
+
+
+
+
## Balance and usage carry-over on plan upgrades
diff --git a/apps/docs/mintlify/documentation/customers/check.mdx b/apps/docs/mintlify/documentation/customers/check.mdx
index 4b8924e75..16e8c8de4 100644
--- a/apps/docs/mintlify/documentation/customers/check.mdx
+++ b/apps/docs/mintlify/documentation/customers/check.mdx
@@ -18,6 +18,10 @@ The `allowed` field will return `true` for a given feature if:
Under these conditions, you should allow your customer to use the feature. You can then [record the usage event](/documentation/customers/tracking-usage/) so Autumn can update the `allowed` field as necessary.
+
+The customer must already exist before calling `check`. If the `customer_id` doesn't match an existing customer, the API returns a `customer_not_found` error. Create customers using [`customers.getOrCreate`](/documentation/customers/creating-customers) during signup or login.
+
+
## Checking metered features
Before your customer uses a feature, you can check if the customer is allowed to use it and their current usage.
@@ -260,3 +264,53 @@ if (allowed) {
// Show premium dashboard
}
```
+
+### Feature flags in customer responses
+
+Boolean features are also returned as a `flags` object on customer and entity API responses. This lets you check on/off feature access directly from the customer object without calling the `check` endpoint separately.
+
+```json
+{
+ "balances": {
+ "credits": { "featureId": "credits", "granted": 1000, "remaining": 800, "usage": 200 }
+ },
+ "flags": {
+ "premiumDashboard": {
+ "id": "cus_ent_abc123",
+ "planId": "pro_plan",
+ "expiresAt": null,
+ "featureId": "premiumDashboard"
+ }
+ }
+}
+```
+
+- **Flags** are separate from **balances** — boolean features appear under `flags`, while metered and credit system features remain under `balances`
+- Each flag shows which `planId` it originates from and when it expires
+- Use `expand: ["flags.feature"]` to include the full feature object on each flag
+
+
+
+```typescript TypeScript
+const customer = await autumn.customers.getOrCreate({
+ customerId: "user_123",
+ expand: ["flags.feature"],
+});
+
+if (customer.flags?.["premiumDashboard"]) {
+ // Customer has the premium dashboard feature
+}
+```
+
+```python Python
+customer = await autumn.customers.get_or_create(
+ customer_id="user_123",
+ expand=["flags.feature"],
+)
+
+if customer.flags and "premium_dashboard" in customer.flags:
+ # Customer has the premium dashboard feature
+ pass
+```
+
+
diff --git a/apps/docs/mintlify/documentation/customers/creating-customers.mdx b/apps/docs/mintlify/documentation/customers/creating-customers.mdx
index aad7f42bd..40d27f766 100644
--- a/apps/docs/mintlify/documentation/customers/creating-customers.mdx
+++ b/apps/docs/mintlify/documentation/customers/creating-customers.mdx
@@ -60,6 +60,10 @@ Only the `customerId` field is required — this should be your unique identifie
A common pattern is to call `customers.getOrCreate` on every login or signup in your application, so Autumn always has the latest customer information.
+
+Customers must be created before calling the [`check`](/documentation/customers/check) or [`track`](/documentation/customers/tracking-usage) endpoints. If you call these endpoints with a `customer_id` that doesn't exist, the API will return a `customer_not_found` error. Make sure to call `customers.getOrCreate` during signup or login before checking access or tracking usage.
+
+
## Pre-creating customers via the dashboard
You can create a customer in the Autumn dashboard before they've ever interacted with your application. This is useful for enterprise or sales-led deals where you want to provision access before the customer signs up.
diff --git a/apps/docs/mintlify/documentation/customers/tracking-usage.mdx b/apps/docs/mintlify/documentation/customers/tracking-usage.mdx
index 590efacd5..e0809faac 100644
--- a/apps/docs/mintlify/documentation/customers/tracking-usage.mdx
+++ b/apps/docs/mintlify/documentation/customers/tracking-usage.mdx
@@ -7,6 +7,10 @@ When customers use features in your product, you'll need to record their usage s
There are two ways to record usage: sending events or setting usage directly.
+
+The customer must already exist before calling `track`. If the `customer_id` doesn't match an existing customer, the API returns a `customer_not_found` error. Create customers using [`customers.getOrCreate`](/documentation/customers/creating-customers) during signup or login.
+
+
## Sending Events
The track route is recommended for tracking consumable features, like AI messages, credits or API calls. Each time a customer uses a feature, send an event to count their usage.