atmn 2.0.181 → 2.0.182

package/dist/bin.js

@@ -7964,7 +7964,7 @@ var createClient = (options) => ({
 });
 
 // src/version.ts
-var version = "2.0.181";
+var version = "2.0.182";
 
 // src/http/autumnFetch.ts
 var runtime = typeof Bun !== "undefined" ? `bun ${Bun.version}` : `node ${process.versions.node}`;
@@ -19199,6 +19199,14 @@ Metered volume variant:
 
 </trial-behavior>
 
+<past-due-behavior>
+
+- \`config.ignore_past_due\` is a plan setting (dashboard: plan settings → "Ignore past due"). When true, customers on the plan keep working while a payment is past due: balances still reset, usage is not blocked, and Stripe does not cancel the subscription.
+- Customers have the same flag on their own \`config\`. When set (true or false), the customer's value wins over every plan they hold; when unset, each plan's value decides.
+- Setting it on the plan covers current and future customers on that plan; setting it per customer covers only that customer.
+
+</past-due-behavior>
+
 <replacement-behavior>
 
 - By default, attaching a plan replaces the customer's current plan in the same group.
@@ -19238,7 +19246,7 @@ Metered volume variant:
       },
       {
         path: "references/trials.md",
-        contents: "### Trials\n\n- A trial gives a customer temporary, free access to a plan. It can be passed in during the billing call, or it can come with the plan configuration itself (which can be overriden).\n- Set a trial with `free_trial` on attach: `{ duration_length, duration_type (day|month|year), card_required, on_end }`. Always pass `duration_type`. \n- Default to card not required (if there is no paid plan), and on_end: revert (if there is a paid plan).\n\nIf the customer the customer is NOT on a paid plan (free plan or no plan at all). 2 options:\n\n- No-card trial (default to this): attach with `free_trial` and set `card_required` false. The subscription starts with no card and ends at trial end if none is added. While on it, the customer cannot upgrade or attach another plan until they add a card via the Stripe billing portal.\n- No-card trials cannot be combined with `invoice_mode` (attach rejects it). If an invoice is needed, use `card_required: true`.\n- Card-required trial: attach with `free_trial` and `card_required: true` and `long_lived_checkout` If the customer has no payment method, the attach returns a checkout URL to collect a card; they are charged when the trial ends. This should be done with a long-lived checkout URL param.\n\nThe customer already has an active (Stripe) subscription — common in sales-led trials.\n\n- On end: revert (default to this): attach the new plan with `on_end: \"revert\"` . This grants the plan in Autumn without touching the Stripe subscription; at trial end Autumn moves the customer back to their original plan, preserving the existing billing cycle.\n- To end a revert trial early, cancel it with `updateSubscription` and `cancel_action: \"cancel_immediately\"`; Autumn restores the previous plan. Do not remove `free_trial` (that converts the trial to paid) or re-attach the old plan.\n- On end: bill -- attaching a plan with a trial (or updating the subscription to add one) resets the Stripe billing anchor/cycle. This can be undesired so warn the user if they request this.\n- Card required param is ignored if there is already an active sub.\n\n\nUpdating or ending a trial\n- Call update_subscription on the trialing plan with the new trial nested under `customize`: `{ customer_id, subscription_id, customize: { free_trial: { duration_length, duration_type, card_required, on_end } } }`. Never put `free_trial` at the top level of an update: the update endpoint rejects a request whose only change is a top-level `free_trial` (\"At least one update parameter must be provided\"), while `customize.free_trial` is accepted. The duration is counted from now, not from the original start. A 14-day extension on day 10 of a 14-day trial gives 14 more days, not 4.\n- For a bill-on-end trial, pass `customize: { free_trial: null }` to end the trial immediately and start paid billing. Never do this for a revert trial: it activates the trial plan at full price instead of restoring the old plan. Cancel a revert trial instead (see above)."
+        contents: '### Trials\n\n- A trial gives a customer temporary, free access to a plan. It can be passed in during the billing call, or it can come with the plan configuration itself (which can be overriden).\n- Set a trial with `free_trial` on attach: `{ duration_length, duration_type (day|month|year), card_required, on_end }`. Always pass `duration_type` and `on_end`; never omit `on_end`, because it silently defaults to `"bill"`.\n- Default to card not required (if there is no paid plan), and on_end: revert (if there is a paid plan).\n- `on_end` must match what you tell the user happens when the trial ends. If you say the customer goes back to their current or previous plan (e.g. "if no card is added, they go back to Hobby"), pass `on_end: "revert"`. Pass `on_end: "bill"` only when the customer should be charged and keep the plan at trial end, and say that.\n\nIf the customer the customer is NOT on a paid plan (free plan or no plan at all). 2 options:\n\n- No-card trial (default to this): attach with `free_trial` and set `card_required` false. The subscription starts with no card and ends at trial end if none is added. While on it, the customer cannot upgrade or attach another plan until they add a card via the Stripe billing portal.\n- No-card trials cannot be combined with `invoice_mode` (attach rejects it). If an invoice is needed, use `card_required: true`.\n- Card-required trial: attach with `free_trial` and `card_required: true` and `long_lived_checkout` If the customer has no payment method, the attach returns a checkout URL to collect a card; they are charged when the trial ends. This should be done with a long-lived checkout URL param.\n\nThe customer already has an active (Stripe) subscription — common in sales-led trials.\n\n- On end: revert (default to this): attach the new plan with `on_end: "revert"` . This grants the plan in Autumn without touching the Stripe subscription; at trial end Autumn moves the customer back to their original plan, preserving the existing billing cycle.\n- To end a revert trial early, cancel it with `updateSubscription` and `cancel_action: "cancel_immediately"`; Autumn restores the previous plan. Do not remove `free_trial` (that converts the trial to paid) or re-attach the old plan.\n- On end: bill -- attaching a plan with a trial (or updating the subscription to add one) resets the Stripe billing anchor/cycle. This can be undesired so warn the user if they request this.\n- Card required param is ignored if there is already an active sub.\n\n\nUpdating or ending a trial\n- Call update_subscription on the trialing plan with the new trial nested under `customize`: `{ customer_id, subscription_id, customize: { free_trial: { duration_length, duration_type, card_required, on_end } } }`. Never put `free_trial` at the top level of an update: the update endpoint rejects a request whose only change is a top-level `free_trial` ("At least one update parameter must be provided"), while `customize.free_trial` is accepted. The duration is counted from now, not from the original start. A 14-day extension on day 10 of a 14-day trial gives 14 more days, not 4.\n- For a bill-on-end trial, pass `customize: { free_trial: null }` to end the trial immediately and start paid billing. Never do this for a revert trial: it activates the trial plan at full price instead of restoring the old plan. Cancel a revert trial instead (see above).'
       },
       {
         path: "references/customer-entity.md",
@@ -19310,6 +19318,7 @@ Metered volume variant:
 <additional>
 
 - Billing controls can change usage behavior after balances are provisioned; see the Billing Controls section in this Concepts resource.
+- \`config.ignore_past_due\` on a customer overrides the same setting on each of their plans; leave it unset to follow the plans. See the past-due section of the Plan concept.
 - Use \`expand\` to pull related details when needed, such as attached plans, features, entities, invoices, payment method, or billing-control runtime state.
 
 </additional>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atmn",
-  "version": "2.0.181",
+  "version": "2.0.182",
   "license": "MIT",
   "description": "The CLI for Autumn — define your pricing in code, sync it to Autumn, and keep everything in version control.",
   "bin": {
@@ -49,5 +49,5 @@
     "open": "10.2.0",
     "yaml": "2.9.0"
   },
-  "gitHead": "cbe8e91d98816e2e661b3ae99dec513dc529052d"
+  "gitHead": "f87eefe4ad8dd78cf94a24e23efadc129f32d4ee"
 }

package/src/generated/skills.ts

@@ -273,7 +273,7 @@ export const SKILLS: readonly BundledSkill[] = [
 			{
 				path: "references/plan.md",
 				contents:
-					'### Plan\n\n- Plan is the attachable package: Free, Pro, Enterprise, Credit Pack, Add-on, etc.\n- A plan answers two questions: what should this customer get, and how should Autumn treat it when attached?\n- Most "what they get" detail lives in `items[]`; most lifecycle behavior lives on plan-level fields.\n\n</intro>\n\n<relationships>\n\n- `Plan -> Plan Item`: a plan has many items; items define feature grants, limits, prepaid packages, and overage prices.\n- `Subscription -> Plan`: recurring or free plan attached to a customer or entity.\n- `Purchase -> Plan`: one-off plan attached to a customer or entity.\n- `Customer/Entity + Plan --billing.attach--> Subscription/Purchase`: attach turns plan configuration into customer state.\n- Plans also connect to plans, both edges built on customize: a **variant** is a derived plan storing its diff from a base; a **license** is a parent\'s link to a child plan it hands out per seat, optionally customized per parent. See the variants section below and the Licenses concept.\n\n</relationships>\n\n<composition>\n\n- Use `price` for the plan-level/base charge, such as $20/month for Pro or a one-off flat fee.\n- Use `items[]` as the packaging of the plan: feature grants, seats, overages, prepaid packs, boolean access, and add-on contents.\n- Common pattern: `Plan.price` is the platform/package fee; `Plan.items[]` define the packaged value and any feature-level billing.\n- `price: null` does not always mean free; the plan can still be paid if its items contain usage-based or prepaid prices.\n- If the pricing question is "what does this feature grant or bill?", answer it in Plan Item, not Plan.\n\n</composition>\n\n<plan-types>\n\n- Recurring plan: has at least one recurring paid price or recurring lifecycle; attach creates a subscription.\n- Free plan: has no paid prices; attach creates a free subscription.\n- One-off plan: has at least one paid price and all paid prices are one-off; attach creates a purchase.\n- One-off examples: $10 flat purchase, or $10 for 100 prepaid credits.\n- If any price is monthly or yearly, e.g. $10/month, it is not a one-off plan.\n\n</plan-types>\n\n<default-behavior>\n\n- `auto_enable` automatically attaches the plan when a subject is created.\n- Use it for free/default access, not normal paid plans.\n- Common examples: free tier, limited-time trial access plan, entity default tier.\n- If multiple defaults exist across groups, Autumn can assign one default per group.\n- Never use `auto_enable: true` for paid plans; `Plan.price` must be null and plan items should not contain paid prepaid or usage-based prices.\n\n</default-behavior>\n\n<versions>\n\n- A version is one definition of a plan that a group of customers lives on. A plan\'s versions sit side by side — they are not a timeline, and a newer one is not "the" plan.\n- The test for a new version: **should existing customers keep the old terms?** Yes (a base price increase they are grandfathered on) → a new version; they stay on theirs. No (a feature everyone gets) → an edit to the version they are on, or to every version at once — not a new version.\n- Exactly one version of a plan is **active**: the one `billing.attach` puts a customer on when no version is named, and the one reads resolve to by default. Promoting a version moves that pointer; it moves no customer.\n- A version that is not active is a **draft**: minted, not yet sold. Two flows: mint and promote in one step, or mint as a draft, review it, promote later. Drafts also stage customer groups while migrating from another billing system.\n- `version_slug` is the version\'s name (`v1`, `2026-q3`), unique within the plan. Renaming a slug renames the version; it never mints one. The server also numbers versions in creation order — an internal label, not a meaning.\n- Customers do not move when the pointer moves. Editing a version in place changes what its customers have; moving customers to another version is a **migration**, drafted and run on its own.\n- Variants and licenses are versioned with the plan. A variant\'s customize is a diff over one base version. A license link is pinned to one child version; moving a parent onto another child version is an explicit change to that link. How a catalog update expresses these is the `autumn-catalog` skill\'s.\n- A plan can also have **aliases**: after a plan id rename, the old id still resolves to the plan.\n\n</versions>\n\n<variants>\n\n- Variants group related plans under one base definition and store each variant\'s diff as `variant_details.customize`.\n- `plans.list` returns a flat plan list; each variant plan points back to its base through `variant_details`.\n- In a catalog update, variants are defined or customized under the base plan\'s `variants`, never as top-level plans.\n- A base edit does not reach a variant on its own: each variant either follows the change or keeps its current definition, and the update preview says which for every variant.\n- Common variant uses: billing intervals, A/B price packages, and volume ladders.\n- A variant\'s stored diff can change the price, replace the item list (`items`) or patch it (`add_items` / `remove_items`), and change the trial. A variant cannot be the default plan or have variants of its own.\n\nAnnual interval variant:\n\n```json\n{\n  "variant_plan_id": "pro_annual",\n  "name": "Pro Annual",\n  "customize": {\n    "price": { "amount": 200, "interval": "year" }\n  }\n}\n```\n\nA/B testing variant:\n\n```json\n{\n  "variant_plan_id": "pro_b",\n  "name": "Pro B",\n  "customize": {\n    "price": { "amount": 29, "interval": "month" },\n    "add_items": [{ "feature_id": "analytics" }]\n  }\n}\n```\n\nMetered volume variant:\n\n```json\n{\n  "variant_plan_id": "pro_100k",\n  "name": "Pro 100k",\n  "customize": {\n    "price": { "amount": 35, "interval": "month" },\n    "remove_items": [\n      { "feature_id": "emails", "billing_method": "usage_based" }\n    ],\n    "add_items": [\n      {\n        "feature_id": "emails",\n        "included": 100000,\n        "price": {\n          "amount": 0.9,\n          "billing_units": 1000,\n          "billing_method": "usage_based",\n          "interval": "month"\n        }\n      }\n    ]\n  }\n}\n```\n\n</variants>\n\n<trial-behavior>\n\n- This covers how to MODEL trials in the catalog. For how to put a customer on a trial at attach time (card-required, no-card, revert), see the Trials concept.\n- For card-required trials, put `free_trial` on the real paid plan.\n- For no-card trials, prefer a separate limited-time trial plan, e.g. `pro_trial`, plus the real paid `pro` — it gives temporary access, expires automatically, and lets the user later enter the normal checkout flow for `pro`.\n\n</trial-behavior>\n\n<replacement-behavior>\n\n- By default, attaching a plan replaces the customer\'s current plan in the same group.\n- Use `group` when customers can have one active plan from each independent product line.\n- Example: one `support` plan and one `sales` plan can coexist, but two `support` plans should transition.\n- Groups are not needed for simple pricing with one main subscription line.\n\n</replacement-behavior>\n\n<add-on-behavior>\n\n- `add_on` makes the plan additive instead of a replacement.\n- Use add-ons for top-up packs, feature packs, extra concurrency, extra storage, or recurring bolt-ons.\n- Add-ons can be attached alongside other add-ons; repeated attachment can be useful for top-ups or stacked purchases.\n- Add-ons do not participate in normal upgrade/downgrade transitions.\n\n</add-on-behavior>\n\n<useful-docs>\n\n- Concepts overview: https://docs.useautumn.com/documentation/concepts/overview\n- Plans concept: https://docs.useautumn.com/documentation/concepts/plans\n- Free plans: https://docs.useautumn.com/documentation/modelling-pricing/free-plans\n- Recurring plans: https://docs.useautumn.com/documentation/modelling-pricing/recurring\n- Trials: https://docs.useautumn.com/documentation/modelling-pricing/trials\n- Add-ons: https://docs.useautumn.com/documentation/modelling-pricing/add-ons\n\n</useful-docs>',
+					'### Plan\n\n- Plan is the attachable package: Free, Pro, Enterprise, Credit Pack, Add-on, etc.\n- A plan answers two questions: what should this customer get, and how should Autumn treat it when attached?\n- Most "what they get" detail lives in `items[]`; most lifecycle behavior lives on plan-level fields.\n\n</intro>\n\n<relationships>\n\n- `Plan -> Plan Item`: a plan has many items; items define feature grants, limits, prepaid packages, and overage prices.\n- `Subscription -> Plan`: recurring or free plan attached to a customer or entity.\n- `Purchase -> Plan`: one-off plan attached to a customer or entity.\n- `Customer/Entity + Plan --billing.attach--> Subscription/Purchase`: attach turns plan configuration into customer state.\n- Plans also connect to plans, both edges built on customize: a **variant** is a derived plan storing its diff from a base; a **license** is a parent\'s link to a child plan it hands out per seat, optionally customized per parent. See the variants section below and the Licenses concept.\n\n</relationships>\n\n<composition>\n\n- Use `price` for the plan-level/base charge, such as $20/month for Pro or a one-off flat fee.\n- Use `items[]` as the packaging of the plan: feature grants, seats, overages, prepaid packs, boolean access, and add-on contents.\n- Common pattern: `Plan.price` is the platform/package fee; `Plan.items[]` define the packaged value and any feature-level billing.\n- `price: null` does not always mean free; the plan can still be paid if its items contain usage-based or prepaid prices.\n- If the pricing question is "what does this feature grant or bill?", answer it in Plan Item, not Plan.\n\n</composition>\n\n<plan-types>\n\n- Recurring plan: has at least one recurring paid price or recurring lifecycle; attach creates a subscription.\n- Free plan: has no paid prices; attach creates a free subscription.\n- One-off plan: has at least one paid price and all paid prices are one-off; attach creates a purchase.\n- One-off examples: $10 flat purchase, or $10 for 100 prepaid credits.\n- If any price is monthly or yearly, e.g. $10/month, it is not a one-off plan.\n\n</plan-types>\n\n<default-behavior>\n\n- `auto_enable` automatically attaches the plan when a subject is created.\n- Use it for free/default access, not normal paid plans.\n- Common examples: free tier, limited-time trial access plan, entity default tier.\n- If multiple defaults exist across groups, Autumn can assign one default per group.\n- Never use `auto_enable: true` for paid plans; `Plan.price` must be null and plan items should not contain paid prepaid or usage-based prices.\n\n</default-behavior>\n\n<versions>\n\n- A version is one definition of a plan that a group of customers lives on. A plan\'s versions sit side by side — they are not a timeline, and a newer one is not "the" plan.\n- The test for a new version: **should existing customers keep the old terms?** Yes (a base price increase they are grandfathered on) → a new version; they stay on theirs. No (a feature everyone gets) → an edit to the version they are on, or to every version at once — not a new version.\n- Exactly one version of a plan is **active**: the one `billing.attach` puts a customer on when no version is named, and the one reads resolve to by default. Promoting a version moves that pointer; it moves no customer.\n- A version that is not active is a **draft**: minted, not yet sold. Two flows: mint and promote in one step, or mint as a draft, review it, promote later. Drafts also stage customer groups while migrating from another billing system.\n- `version_slug` is the version\'s name (`v1`, `2026-q3`), unique within the plan. Renaming a slug renames the version; it never mints one. The server also numbers versions in creation order — an internal label, not a meaning.\n- Customers do not move when the pointer moves. Editing a version in place changes what its customers have; moving customers to another version is a **migration**, drafted and run on its own.\n- Variants and licenses are versioned with the plan. A variant\'s customize is a diff over one base version. A license link is pinned to one child version; moving a parent onto another child version is an explicit change to that link. How a catalog update expresses these is the `autumn-catalog` skill\'s.\n- A plan can also have **aliases**: after a plan id rename, the old id still resolves to the plan.\n\n</versions>\n\n<variants>\n\n- Variants group related plans under one base definition and store each variant\'s diff as `variant_details.customize`.\n- `plans.list` returns a flat plan list; each variant plan points back to its base through `variant_details`.\n- In a catalog update, variants are defined or customized under the base plan\'s `variants`, never as top-level plans.\n- A base edit does not reach a variant on its own: each variant either follows the change or keeps its current definition, and the update preview says which for every variant.\n- Common variant uses: billing intervals, A/B price packages, and volume ladders.\n- A variant\'s stored diff can change the price, replace the item list (`items`) or patch it (`add_items` / `remove_items`), and change the trial. A variant cannot be the default plan or have variants of its own.\n\nAnnual interval variant:\n\n```json\n{\n  "variant_plan_id": "pro_annual",\n  "name": "Pro Annual",\n  "customize": {\n    "price": { "amount": 200, "interval": "year" }\n  }\n}\n```\n\nA/B testing variant:\n\n```json\n{\n  "variant_plan_id": "pro_b",\n  "name": "Pro B",\n  "customize": {\n    "price": { "amount": 29, "interval": "month" },\n    "add_items": [{ "feature_id": "analytics" }]\n  }\n}\n```\n\nMetered volume variant:\n\n```json\n{\n  "variant_plan_id": "pro_100k",\n  "name": "Pro 100k",\n  "customize": {\n    "price": { "amount": 35, "interval": "month" },\n    "remove_items": [\n      { "feature_id": "emails", "billing_method": "usage_based" }\n    ],\n    "add_items": [\n      {\n        "feature_id": "emails",\n        "included": 100000,\n        "price": {\n          "amount": 0.9,\n          "billing_units": 1000,\n          "billing_method": "usage_based",\n          "interval": "month"\n        }\n      }\n    ]\n  }\n}\n```\n\n</variants>\n\n<trial-behavior>\n\n- This covers how to MODEL trials in the catalog. For how to put a customer on a trial at attach time (card-required, no-card, revert), see the Trials concept.\n- For card-required trials, put `free_trial` on the real paid plan.\n- For no-card trials, prefer a separate limited-time trial plan, e.g. `pro_trial`, plus the real paid `pro` — it gives temporary access, expires automatically, and lets the user later enter the normal checkout flow for `pro`.\n\n</trial-behavior>\n\n<past-due-behavior>\n\n- `config.ignore_past_due` is a plan setting (dashboard: plan settings → "Ignore past due"). When true, customers on the plan keep working while a payment is past due: balances still reset, usage is not blocked, and Stripe does not cancel the subscription.\n- Customers have the same flag on their own `config`. When set (true or false), the customer\'s value wins over every plan they hold; when unset, each plan\'s value decides.\n- Setting it on the plan covers current and future customers on that plan; setting it per customer covers only that customer.\n\n</past-due-behavior>\n\n<replacement-behavior>\n\n- By default, attaching a plan replaces the customer\'s current plan in the same group.\n- Use `group` when customers can have one active plan from each independent product line.\n- Example: one `support` plan and one `sales` plan can coexist, but two `support` plans should transition.\n- Groups are not needed for simple pricing with one main subscription line.\n\n</replacement-behavior>\n\n<add-on-behavior>\n\n- `add_on` makes the plan additive instead of a replacement.\n- Use add-ons for top-up packs, feature packs, extra concurrency, extra storage, or recurring bolt-ons.\n- Add-ons can be attached alongside other add-ons; repeated attachment can be useful for top-ups or stacked purchases.\n- Add-ons do not participate in normal upgrade/downgrade transitions.\n\n</add-on-behavior>\n\n<useful-docs>\n\n- Concepts overview: https://docs.useautumn.com/documentation/concepts/overview\n- Plans concept: https://docs.useautumn.com/documentation/concepts/plans\n- Free plans: https://docs.useautumn.com/documentation/modelling-pricing/free-plans\n- Recurring plans: https://docs.useautumn.com/documentation/modelling-pricing/recurring\n- Trials: https://docs.useautumn.com/documentation/modelling-pricing/trials\n- Add-ons: https://docs.useautumn.com/documentation/modelling-pricing/add-ons\n\n</useful-docs>',
 			},
 			{
 				path: "references/plan-items.md",
@@ -288,12 +288,12 @@ export const SKILLS: readonly BundledSkill[] = [
 			{
 				path: "references/trials.md",
 				contents:
-					'### Trials\n\n- A trial gives a customer temporary, free access to a plan. It can be passed in during the billing call, or it can come with the plan configuration itself (which can be overriden).\n- Set a trial with `free_trial` on attach: `{ duration_length, duration_type (day|month|year), card_required, on_end }`. Always pass `duration_type`. \n- Default to card not required (if there is no paid plan), and on_end: revert (if there is a paid plan).\n\nIf the customer the customer is NOT on a paid plan (free plan or no plan at all). 2 options:\n\n- No-card trial (default to this): attach with `free_trial` and set `card_required` false. The subscription starts with no card and ends at trial end if none is added. While on it, the customer cannot upgrade or attach another plan until they add a card via the Stripe billing portal.\n- No-card trials cannot be combined with `invoice_mode` (attach rejects it). If an invoice is needed, use `card_required: true`.\n- Card-required trial: attach with `free_trial` and `card_required: true` and `long_lived_checkout` If the customer has no payment method, the attach returns a checkout URL to collect a card; they are charged when the trial ends. This should be done with a long-lived checkout URL param.\n\nThe customer already has an active (Stripe) subscription — common in sales-led trials.\n\n- On end: revert (default to this): attach the new plan with `on_end: "revert"` . This grants the plan in Autumn without touching the Stripe subscription; at trial end Autumn moves the customer back to their original plan, preserving the existing billing cycle.\n- To end a revert trial early, cancel it with `updateSubscription` and `cancel_action: "cancel_immediately"`; Autumn restores the previous plan. Do not remove `free_trial` (that converts the trial to paid) or re-attach the old plan.\n- On end: bill -- attaching a plan with a trial (or updating the subscription to add one) resets the Stripe billing anchor/cycle. This can be undesired so warn the user if they request this.\n- Card required param is ignored if there is already an active sub.\n\n\nUpdating or ending a trial\n- Call update_subscription on the trialing plan with the new trial nested under `customize`: `{ customer_id, subscription_id, customize: { free_trial: { duration_length, duration_type, card_required, on_end } } }`. Never put `free_trial` at the top level of an update: the update endpoint rejects a request whose only change is a top-level `free_trial` ("At least one update parameter must be provided"), while `customize.free_trial` is accepted. The duration is counted from now, not from the original start. A 14-day extension on day 10 of a 14-day trial gives 14 more days, not 4.\n- For a bill-on-end trial, pass `customize: { free_trial: null }` to end the trial immediately and start paid billing. Never do this for a revert trial: it activates the trial plan at full price instead of restoring the old plan. Cancel a revert trial instead (see above).',
+					'### Trials\n\n- A trial gives a customer temporary, free access to a plan. It can be passed in during the billing call, or it can come with the plan configuration itself (which can be overriden).\n- Set a trial with `free_trial` on attach: `{ duration_length, duration_type (day|month|year), card_required, on_end }`. Always pass `duration_type` and `on_end`; never omit `on_end`, because it silently defaults to `"bill"`.\n- Default to card not required (if there is no paid plan), and on_end: revert (if there is a paid plan).\n- `on_end` must match what you tell the user happens when the trial ends. If you say the customer goes back to their current or previous plan (e.g. "if no card is added, they go back to Hobby"), pass `on_end: "revert"`. Pass `on_end: "bill"` only when the customer should be charged and keep the plan at trial end, and say that.\n\nIf the customer the customer is NOT on a paid plan (free plan or no plan at all). 2 options:\n\n- No-card trial (default to this): attach with `free_trial` and set `card_required` false. The subscription starts with no card and ends at trial end if none is added. While on it, the customer cannot upgrade or attach another plan until they add a card via the Stripe billing portal.\n- No-card trials cannot be combined with `invoice_mode` (attach rejects it). If an invoice is needed, use `card_required: true`.\n- Card-required trial: attach with `free_trial` and `card_required: true` and `long_lived_checkout` If the customer has no payment method, the attach returns a checkout URL to collect a card; they are charged when the trial ends. This should be done with a long-lived checkout URL param.\n\nThe customer already has an active (Stripe) subscription — common in sales-led trials.\n\n- On end: revert (default to this): attach the new plan with `on_end: "revert"` . This grants the plan in Autumn without touching the Stripe subscription; at trial end Autumn moves the customer back to their original plan, preserving the existing billing cycle.\n- To end a revert trial early, cancel it with `updateSubscription` and `cancel_action: "cancel_immediately"`; Autumn restores the previous plan. Do not remove `free_trial` (that converts the trial to paid) or re-attach the old plan.\n- On end: bill -- attaching a plan with a trial (or updating the subscription to add one) resets the Stripe billing anchor/cycle. This can be undesired so warn the user if they request this.\n- Card required param is ignored if there is already an active sub.\n\n\nUpdating or ending a trial\n- Call update_subscription on the trialing plan with the new trial nested under `customize`: `{ customer_id, subscription_id, customize: { free_trial: { duration_length, duration_type, card_required, on_end } } }`. Never put `free_trial` at the top level of an update: the update endpoint rejects a request whose only change is a top-level `free_trial` ("At least one update parameter must be provided"), while `customize.free_trial` is accepted. The duration is counted from now, not from the original start. A 14-day extension on day 10 of a 14-day trial gives 14 more days, not 4.\n- For a bill-on-end trial, pass `customize: { free_trial: null }` to end the trial immediately and start paid billing. Never do this for a revert trial: it activates the trial plan at full price instead of restoring the old plan. Cancel a revert trial instead (see above).',
 			},
 			{
 				path: "references/customer-entity.md",
 				contents:
-					"### Customer and Entity\n\n- Customer and Entity are the runtime view of billing state: what plans are attached, what access exists, what usage has happened, and what billing controls apply.\n- A Customer is the primary subject being billed or entitled, usually a user, account, workspace, or organization.\n- Entities are optional child subjects under a customer, such as deployments, seats, users, projects, or sub-accounts.\n- Depending on the org's configuration, entities may not be used at all; if they are in play, billing state can exist at both customer and entity scope.\n- Features, Plans, and Plan Items define configuration; Customer and Entity show how that configuration materializes for one real subject.\n\n</intro>\n\n<shared-shape>\n\n- `subscriptions[]` and `purchases[]` show which plans this customer or entity has subscribed to or bought.\n- These arrays describe the join between subject and plan: status, start/end dates, expiry, schedule state, quantity, and attached plan context.\n- `flags[feature_id]` and `balances[feature_id]` show runtime feature state for this subject.\n- Boolean features materialize as flags: access is on or off.\n- Flag fields mostly mirror the API reference and are straightforward, so this card does not expand every field.\n- Metered and credit features materialize as balances: aggregate granted, included, usage, remaining, reset timing, and related runtime details.\n\n  <balances>\n\n  - Balances are the runtime state for metered and credit-system features.\n  - The parent balance object is an aggregate view for one feature.\n  - Each breakdown item is the actual balance source: usually from attaching a plan item, or from a standalone grant created with `balances.create`.\n  - Plan source shape: `Customer/Entity -> Balance Breakdown -> Plan Item`.\n  - `granted` is included grant plus prepaid grant.\n  - `remaining` is the positive balance left from included/prepaid grants and never goes below 0.\n  - `usage` is how much has been used; if usage exceeds granted, the subject is in overage.\n  - A pooled balance is one customer-level balance fed by entity-attached plans whose items have `pooled: true`. Every entity — and the customer — sees the same number, and any of them can spend it. Customer-level purchases (packs, overage) stack beside the pool.\n  - Other balance fields, such as reset timing and unlimited status, are usually self-explanatory from the API reference.\n\n  </balances>\n\n</shared-shape>\n\n<customer-vs-entity-scope>\n\n- Customer-level state belongs to the parent customer.\n- Entity-level state belongs to one specific entity under the customer.\n- Customer-level check/track calls do not inherit entity-level subscriptions, purchases, balances, or flags.\n- Entity-level check/track calls can use customer-level state plus matching entity-level state.\n- If a feature is granted only at entity level, include `entity_id` when checking or tracking it.\n- If all entities share the same allowance, model the allowance at customer level and omit `entity_id` for shared usage.\n- Legacy `entity_feature_id` scoped one plan item's balance across many entities under the customer; this model is deprecated.\n- Prefer attaching plans at entity scope when each entity needs its own tier, balance, or subscription state.\n\n</customer-vs-entity-scope>\n\n<entity-patterns>\n\n- Entity-level balances: one customer subscription grants per-entity limits, useful when all entities get the same features and limits.\n- Entity-level subscriptions: attach plans with `entity_id`, useful when each entity can have its own tier.\n- Pooled balances: entity-attached plans with pooled items feed one shared customer balance any entity can spend — see the pooled-balances concept.\n- License seats: an entity can hold one seat from the customer's license pool — see the licenses concept.\n- Entity-level controls can override customer-level controls for that entity where supported.\n\n</entity-patterns>\n\n<identity>\n\n- Customer `id` and entity `id` should be identifiers from the user's own app database.\n- Users do not need to store a separate Autumn-only ID for customers or entities.\n\n</identity>\n\n<additional>\n\n- Billing controls can change usage behavior after balances are provisioned; see the Billing Controls section in this Concepts resource.\n- Use `expand` to pull related details when needed, such as attached plans, features, entities, invoices, payment method, or billing-control runtime state.\n\n</additional>\n\n<useful-docs>\n\n- Creating customers: https://docs.useautumn.com/documentation/customers/creating-customers\n- Managing customers: https://docs.useautumn.com/documentation/customers/managing-customers\n- Entities: https://docs.useautumn.com/documentation/customers/feature-entities\n- Balances concept: https://docs.useautumn.com/documentation/concepts/balances\n- Subscriptions concept: https://docs.useautumn.com/documentation/concepts/subscriptions\n- Checking access: https://docs.useautumn.com/documentation/customers/check\n- Tracking usage: https://docs.useautumn.com/documentation/customers/tracking-usage\n\n</useful-docs>",
+					"### Customer and Entity\n\n- Customer and Entity are the runtime view of billing state: what plans are attached, what access exists, what usage has happened, and what billing controls apply.\n- A Customer is the primary subject being billed or entitled, usually a user, account, workspace, or organization.\n- Entities are optional child subjects under a customer, such as deployments, seats, users, projects, or sub-accounts.\n- Depending on the org's configuration, entities may not be used at all; if they are in play, billing state can exist at both customer and entity scope.\n- Features, Plans, and Plan Items define configuration; Customer and Entity show how that configuration materializes for one real subject.\n\n</intro>\n\n<shared-shape>\n\n- `subscriptions[]` and `purchases[]` show which plans this customer or entity has subscribed to or bought.\n- These arrays describe the join between subject and plan: status, start/end dates, expiry, schedule state, quantity, and attached plan context.\n- `flags[feature_id]` and `balances[feature_id]` show runtime feature state for this subject.\n- Boolean features materialize as flags: access is on or off.\n- Flag fields mostly mirror the API reference and are straightforward, so this card does not expand every field.\n- Metered and credit features materialize as balances: aggregate granted, included, usage, remaining, reset timing, and related runtime details.\n\n  <balances>\n\n  - Balances are the runtime state for metered and credit-system features.\n  - The parent balance object is an aggregate view for one feature.\n  - Each breakdown item is the actual balance source: usually from attaching a plan item, or from a standalone grant created with `balances.create`.\n  - Plan source shape: `Customer/Entity -> Balance Breakdown -> Plan Item`.\n  - `granted` is included grant plus prepaid grant.\n  - `remaining` is the positive balance left from included/prepaid grants and never goes below 0.\n  - `usage` is how much has been used; if usage exceeds granted, the subject is in overage.\n  - A pooled balance is one customer-level balance fed by entity-attached plans whose items have `pooled: true`. Every entity — and the customer — sees the same number, and any of them can spend it. Customer-level purchases (packs, overage) stack beside the pool.\n  - Other balance fields, such as reset timing and unlimited status, are usually self-explanatory from the API reference.\n\n  </balances>\n\n</shared-shape>\n\n<customer-vs-entity-scope>\n\n- Customer-level state belongs to the parent customer.\n- Entity-level state belongs to one specific entity under the customer.\n- Customer-level check/track calls do not inherit entity-level subscriptions, purchases, balances, or flags.\n- Entity-level check/track calls can use customer-level state plus matching entity-level state.\n- If a feature is granted only at entity level, include `entity_id` when checking or tracking it.\n- If all entities share the same allowance, model the allowance at customer level and omit `entity_id` for shared usage.\n- Legacy `entity_feature_id` scoped one plan item's balance across many entities under the customer; this model is deprecated.\n- Prefer attaching plans at entity scope when each entity needs its own tier, balance, or subscription state.\n\n</customer-vs-entity-scope>\n\n<entity-patterns>\n\n- Entity-level balances: one customer subscription grants per-entity limits, useful when all entities get the same features and limits.\n- Entity-level subscriptions: attach plans with `entity_id`, useful when each entity can have its own tier.\n- Pooled balances: entity-attached plans with pooled items feed one shared customer balance any entity can spend — see the pooled-balances concept.\n- License seats: an entity can hold one seat from the customer's license pool — see the licenses concept.\n- Entity-level controls can override customer-level controls for that entity where supported.\n\n</entity-patterns>\n\n<identity>\n\n- Customer `id` and entity `id` should be identifiers from the user's own app database.\n- Users do not need to store a separate Autumn-only ID for customers or entities.\n\n</identity>\n\n<additional>\n\n- Billing controls can change usage behavior after balances are provisioned; see the Billing Controls section in this Concepts resource.\n- `config.ignore_past_due` on a customer overrides the same setting on each of their plans; leave it unset to follow the plans. See the past-due section of the Plan concept.\n- Use `expand` to pull related details when needed, such as attached plans, features, entities, invoices, payment method, or billing-control runtime state.\n\n</additional>\n\n<useful-docs>\n\n- Creating customers: https://docs.useautumn.com/documentation/customers/creating-customers\n- Managing customers: https://docs.useautumn.com/documentation/customers/managing-customers\n- Entities: https://docs.useautumn.com/documentation/customers/feature-entities\n- Balances concept: https://docs.useautumn.com/documentation/concepts/balances\n- Subscriptions concept: https://docs.useautumn.com/documentation/concepts/subscriptions\n- Checking access: https://docs.useautumn.com/documentation/customers/check\n- Tracking usage: https://docs.useautumn.com/documentation/customers/tracking-usage\n\n</useful-docs>",
 			},
 			{
 				path: "references/billing-controls.md",