atmn 2.0.190 → 2.0.191

package/dist/bin.js

@@ -7988,7 +7988,7 @@ var createClient = (options) => ({
 });
 
 // src/version.ts
-var version = "2.0.190";
+var version = "2.0.191";
 
 // src/http/autumnFetch.ts
 var runtime = typeof Bun !== "undefined" ? `bun ${Bun.version}` : `node ${process.versions.node}`;
@@ -16419,6 +16419,20 @@ curl -X POST 'https://api.useautumn.com/v1/billing.update' \\
 
 To change the payment methods on an invoice that is already draft or open, use [\`invoices.update\`](/api-reference/invoices/updateInvoice).
 
+### Choosing how renewal invoices are issued
+
+A customer's \`config.renewal_issue_method\` controls how renewal invoices are issued for their subscriptions in invoice mode. Subscriptions that charge automatically are not affected.
+
+| Value | What happens to each renewal invoice |
+| --- | --- |
+| \`send\` | Stripe finalizes it and emails it to the customer. This is the default when the value is unset. |
+| \`finalize\` | Autumn finalizes it with \`auto_advance\` off, so Stripe does not email, remind or charge it. Use this for invoices you collect outside Stripe. |
+| \`draft\` | Autumn leaves it as a draft with \`auto_advance\` off, so you can edit it in Stripe before issuing it. |
+
+Set it when you create the customer, with [\`customers.update\`](/api-reference/customers/updateCustomer), or with the **Renewal issue method** option in the customer's **Edit Config** sheet in the dashboard. Pass \`null\` to clear it and go back to \`send\`. Updating it keeps the customer's other \`config\` keys.
+
+\`invoice_mode.issue_method\` on \`billing.attach\` only controls the subscription's first invoice. Renewals follow the customer's \`renewal_issue_method\`, not the value used at attach.
+
 ## How billing works
 
 By default, updating a subscription with billing changes will generate an invoice:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "atmn",
-  "version": "2.0.190",
+  "version": "2.0.191",
   "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": "55f7143cdca65c668336d51f345b91d028ca25fe"
+  "gitHead": "158fd25ffabe95ee32d673b262438023e2bf76a4"
 }

package/src/generated/skills.ts

@@ -203,7 +203,7 @@ export const SKILLS: readonly BundledSkill[] = [
 			{
 				path: "references/updating-subscriptions.md",
 				contents:
-					'## Updating Subscriptions\n\nUse `billing.update` to modify an existing subscription. This is different from `billing.attach` which is for attaching new plans or changing between plans.\n\n**When to use `billing.update`:**\n\n- **Update feature quantities** — if your plan contains prepaid features (like seats)\n- **Cancel or uncancel** — cancel a subscription immediately or at end of cycle\n- **Customize the plan** — modify pricing or feature configuration (advanced)\n\n## Updating prepaid feature quantities\n\nPrepaid features are features where customers pay upfront for a quantity (e.g., seats, team members). Here\'s an example plan with a prepaid `seats` feature:\n\n```typescript autumn.config.ts\nimport { atmn, feature, plan } from "atmn";\n\nexport const seats = feature({\n  featureId: "seats",\n  name: "Seats",\n  type: "metered",\n  consumable: false, // Non-consumable = doesn\'t reset\n});\n\nexport const team = plan({\n  planId: "team",\n  versionSlug: "v1",\n  active: true,\n  name: "Team Plan",\n  price: {\n    amount: 49,\n    interval: "month",\n  },\n  items: [\n    {\n      featureId: seats.featureId,\n      included: 5, // 5 seats included\n      price: {\n        amount: 10, // $10 per additional seat\n        interval: "month",\n        billingMethod: "prepaid",\n      },\n    },\n  ],\n});\n\nexport default atmn({ features: [seats], plans: [team] });\n```\n\nTo update the quantity of seats for a customer:\n\n<CodeGroup>\n\n```typescript TypeScript\nconst response = await autumn.billing.update({\n  customerId: "user_123",\n  planId: "team",\n  featureQuantities: [\n    { featureId: "seats", quantity: 10 }\n  ],\n});\n```\n\n```python Python\nresponse = await autumn.billing.update(\n    customer_id="user_123",\n    plan_id="team",\n    feature_quantities=[\n        { "feature_id": "seats", "quantity": 10 }\n    ],\n)\n```\n\n```bash cURL\ncurl -X POST \'https://api.useautumn.com/v1/billing/update\' \\\n  -H \'Authorization: Bearer am_sk_...\' \\\n  -H \'Content-Type: application/json\' \\\n  -d \'{\n    "customer_id": "user_123",\n    "plan_id": "team",\n    "feature_quantities": [\n      { "feature_id": "seats", "quantity": 10 }\n    ]\n  }\'\n```\n\n</CodeGroup>\n\n## Canceling a subscription\n\nUse `cancelAction` to cancel or uncancel a subscription:\n\n| Action | Description |\n|--------|-------------|\n| `cancel_end_of_cycle` | Cancel at the end of the current billing period. Customer retains access until then. |\n| `cancel_immediately` | Cancel immediately with a prorated refund. |\n| `uncancel` | Reverse a pending cancellation (only works if not yet expired). |\n\n<CodeGroup>\n\n```typescript TypeScript\n// Cancel at end of billing cycle\nawait autumn.billing.update({\n  customerId: "user_123",\n  planId: "pro",\n  cancelAction: "cancel_end_of_cycle",\n});\n\n// Uncancel a pending cancellation\nawait autumn.billing.update({\n  customerId: "user_123",\n  planId: "pro",\n  cancelAction: "uncancel",\n});\n```\n\n```python Python\n# Cancel at end of billing cycle\nawait autumn.billing.update(\n    customer_id="user_123",\n    plan_id="pro",\n    cancel_action="cancel_end_of_cycle",\n)\n```\n\n```bash cURL\ncurl -X POST \'https://api.useautumn.com/v1/billing/update\' \\\n  -H \'Authorization: Bearer am_sk_...\' \\\n  -H \'Content-Type: application/json\' \\\n  -d \'{\n    "customer_id": "user_123",\n    "plan_id": "pro",\n    "cancel_action": "cancel_end_of_cycle"\n  }\'\n```\n\n</CodeGroup>\n\n## Switching between invoicing and charging automatically\n\nCall `billing.update` with `invoice_mode` as the only change to switch how an existing subscription is collected. The switch applies from the next renewal: nothing is charged or invoiced now, and invoices that are already open keep their payment method.\n\n<CodeGroup>\n\n```typescript TypeScript\n// Send invoices from the next renewal, due in 30 days, payable by card or ACH\nawait autumn.billing.update({\n  customerId: "user_123",\n  planId: "team",\n  invoiceMode: {\n    enabled: true,\n    netTermsDays: 30,\n    paymentMethodTypes: ["card", "us_bank_account"],\n  },\n});\n\n// Charge the card on file automatically again\nawait autumn.billing.update({\n  customerId: "user_123",\n  planId: "team",\n  invoiceMode: { enabled: false },\n});\n```\n\n```bash cURL\ncurl -X POST \'https://api.useautumn.com/v1/billing.update\' \\\n  -H \'Authorization: Bearer am_sk_...\' \\\n  -H \'Content-Type: application/json\' \\\n  -d \'{\n    "customer_id": "user_123",\n    "plan_id": "team",\n    "invoice_mode": {\n      "enabled": true,\n      "net_terms_days": 30,\n      "payment_method_types": ["card", "us_bank_account"]\n    }\n  }\'\n```\n\n</CodeGroup>\n\n- Switching to charging automatically requires a payment method on file; otherwise the request is rejected.\n- `payment_method_types` overrides your organization\'s default payment methods. Omit it to keep the defaults.\n- If the request changes anything else (plan, quantities, items), `invoice_mode` describes how that change is billed instead of switching the subscription.\n\nTo change the payment methods on an invoice that is already draft or open, use [`invoices.update`](/api-reference/invoices/updateInvoice).\n\n## How billing works\n\nBy default, updating a subscription with billing changes will generate an invoice:\n\n- **Increasing quantity** (e.g., adding seats) charges a prorated amount for the remainder of the billing cycle\n- **Decreasing quantity** (e.g., removing seats) generates a credit applied to the next invoice\n- **Canceling immediately** generates a negative invoice granting credits to the customer\n\n### Previewing changes before executing\n\nSimilar to [`billing.previewAttach`](/documentation/customers/payment-flow#step-1-preview-the-charge), you can use `billing.previewUpdate` to see exactly what will be charged before making changes. This returns line items and totals that you can display in a confirmation UI.\n\n<CodeGroup>\n\n```typescript TypeScript\nconst preview = await autumn.billing.previewUpdate({\n  customerId: "user_123",\n  planId: "team",\n  featureQuantities: [\n    { featureId: "seats", quantity: 10 }\n  ],\n});\n\n// Display preview.lineItems, preview.total, preview.currency\n// Then call billing.update to execute\n```\n\n```python Python\npreview = await autumn.billing.preview_update(\n    customer_id="user_123",\n    plan_id="team",\n    feature_quantities=[\n        { "feature_id": "seats", "quantity": 10 }\n    ],\n)\n\n# Display preview.line_items, preview.total\n```\n\n```bash cURL\ncurl -X POST \'https://api.useautumn.com/v1/billing/preview-update\' \\\n  -H \'Authorization: Bearer am_sk_...\' \\\n  -H \'Content-Type: application/json\' \\\n  -d \'{\n    "customer_id": "user_123",\n    "plan_id": "team",\n    "feature_quantities": [\n      { "feature_id": "seats", "quantity": 10 }\n    ]\n  }\'\n```\n\n</CodeGroup>\n\n### Skipping charges\n\nIf you want to update a subscription without creating any charges or credits, pass `prorationBehavior: "none"`:\n\n```typescript\nawait autumn.billing.update({\n  customerId: "user_123",\n  planId: "team",\n  featureQuantities: [\n    { featureId: "seats", quantity: 10 }\n  ],\n  prorationBehavior: "none", // No charges or credits created\n});\n```\n\nThis is useful for administrative adjustments or when you want to handle billing separately.',
+					'## Updating Subscriptions\n\nUse `billing.update` to modify an existing subscription. This is different from `billing.attach` which is for attaching new plans or changing between plans.\n\n**When to use `billing.update`:**\n\n- **Update feature quantities** — if your plan contains prepaid features (like seats)\n- **Cancel or uncancel** — cancel a subscription immediately or at end of cycle\n- **Customize the plan** — modify pricing or feature configuration (advanced)\n\n## Updating prepaid feature quantities\n\nPrepaid features are features where customers pay upfront for a quantity (e.g., seats, team members). Here\'s an example plan with a prepaid `seats` feature:\n\n```typescript autumn.config.ts\nimport { atmn, feature, plan } from "atmn";\n\nexport const seats = feature({\n  featureId: "seats",\n  name: "Seats",\n  type: "metered",\n  consumable: false, // Non-consumable = doesn\'t reset\n});\n\nexport const team = plan({\n  planId: "team",\n  versionSlug: "v1",\n  active: true,\n  name: "Team Plan",\n  price: {\n    amount: 49,\n    interval: "month",\n  },\n  items: [\n    {\n      featureId: seats.featureId,\n      included: 5, // 5 seats included\n      price: {\n        amount: 10, // $10 per additional seat\n        interval: "month",\n        billingMethod: "prepaid",\n      },\n    },\n  ],\n});\n\nexport default atmn({ features: [seats], plans: [team] });\n```\n\nTo update the quantity of seats for a customer:\n\n<CodeGroup>\n\n```typescript TypeScript\nconst response = await autumn.billing.update({\n  customerId: "user_123",\n  planId: "team",\n  featureQuantities: [\n    { featureId: "seats", quantity: 10 }\n  ],\n});\n```\n\n```python Python\nresponse = await autumn.billing.update(\n    customer_id="user_123",\n    plan_id="team",\n    feature_quantities=[\n        { "feature_id": "seats", "quantity": 10 }\n    ],\n)\n```\n\n```bash cURL\ncurl -X POST \'https://api.useautumn.com/v1/billing/update\' \\\n  -H \'Authorization: Bearer am_sk_...\' \\\n  -H \'Content-Type: application/json\' \\\n  -d \'{\n    "customer_id": "user_123",\n    "plan_id": "team",\n    "feature_quantities": [\n      { "feature_id": "seats", "quantity": 10 }\n    ]\n  }\'\n```\n\n</CodeGroup>\n\n## Canceling a subscription\n\nUse `cancelAction` to cancel or uncancel a subscription:\n\n| Action | Description |\n|--------|-------------|\n| `cancel_end_of_cycle` | Cancel at the end of the current billing period. Customer retains access until then. |\n| `cancel_immediately` | Cancel immediately with a prorated refund. |\n| `uncancel` | Reverse a pending cancellation (only works if not yet expired). |\n\n<CodeGroup>\n\n```typescript TypeScript\n// Cancel at end of billing cycle\nawait autumn.billing.update({\n  customerId: "user_123",\n  planId: "pro",\n  cancelAction: "cancel_end_of_cycle",\n});\n\n// Uncancel a pending cancellation\nawait autumn.billing.update({\n  customerId: "user_123",\n  planId: "pro",\n  cancelAction: "uncancel",\n});\n```\n\n```python Python\n# Cancel at end of billing cycle\nawait autumn.billing.update(\n    customer_id="user_123",\n    plan_id="pro",\n    cancel_action="cancel_end_of_cycle",\n)\n```\n\n```bash cURL\ncurl -X POST \'https://api.useautumn.com/v1/billing/update\' \\\n  -H \'Authorization: Bearer am_sk_...\' \\\n  -H \'Content-Type: application/json\' \\\n  -d \'{\n    "customer_id": "user_123",\n    "plan_id": "pro",\n    "cancel_action": "cancel_end_of_cycle"\n  }\'\n```\n\n</CodeGroup>\n\n## Switching between invoicing and charging automatically\n\nCall `billing.update` with `invoice_mode` as the only change to switch how an existing subscription is collected. The switch applies from the next renewal: nothing is charged or invoiced now, and invoices that are already open keep their payment method.\n\n<CodeGroup>\n\n```typescript TypeScript\n// Send invoices from the next renewal, due in 30 days, payable by card or ACH\nawait autumn.billing.update({\n  customerId: "user_123",\n  planId: "team",\n  invoiceMode: {\n    enabled: true,\n    netTermsDays: 30,\n    paymentMethodTypes: ["card", "us_bank_account"],\n  },\n});\n\n// Charge the card on file automatically again\nawait autumn.billing.update({\n  customerId: "user_123",\n  planId: "team",\n  invoiceMode: { enabled: false },\n});\n```\n\n```bash cURL\ncurl -X POST \'https://api.useautumn.com/v1/billing.update\' \\\n  -H \'Authorization: Bearer am_sk_...\' \\\n  -H \'Content-Type: application/json\' \\\n  -d \'{\n    "customer_id": "user_123",\n    "plan_id": "team",\n    "invoice_mode": {\n      "enabled": true,\n      "net_terms_days": 30,\n      "payment_method_types": ["card", "us_bank_account"]\n    }\n  }\'\n```\n\n</CodeGroup>\n\n- Switching to charging automatically requires a payment method on file; otherwise the request is rejected.\n- `payment_method_types` overrides your organization\'s default payment methods. Omit it to keep the defaults.\n- If the request changes anything else (plan, quantities, items), `invoice_mode` describes how that change is billed instead of switching the subscription.\n\nTo change the payment methods on an invoice that is already draft or open, use [`invoices.update`](/api-reference/invoices/updateInvoice).\n\n### Choosing how renewal invoices are issued\n\nA customer\'s `config.renewal_issue_method` controls how renewal invoices are issued for their subscriptions in invoice mode. Subscriptions that charge automatically are not affected.\n\n| Value | What happens to each renewal invoice |\n| --- | --- |\n| `send` | Stripe finalizes it and emails it to the customer. This is the default when the value is unset. |\n| `finalize` | Autumn finalizes it with `auto_advance` off, so Stripe does not email, remind or charge it. Use this for invoices you collect outside Stripe. |\n| `draft` | Autumn leaves it as a draft with `auto_advance` off, so you can edit it in Stripe before issuing it. |\n\nSet it when you create the customer, with [`customers.update`](/api-reference/customers/updateCustomer), or with the **Renewal issue method** option in the customer\'s **Edit Config** sheet in the dashboard. Pass `null` to clear it and go back to `send`. Updating it keeps the customer\'s other `config` keys.\n\n`invoice_mode.issue_method` on `billing.attach` only controls the subscription\'s first invoice. Renewals follow the customer\'s `renewal_issue_method`, not the value used at attach.\n\n## How billing works\n\nBy default, updating a subscription with billing changes will generate an invoice:\n\n- **Increasing quantity** (e.g., adding seats) charges a prorated amount for the remainder of the billing cycle\n- **Decreasing quantity** (e.g., removing seats) generates a credit applied to the next invoice\n- **Canceling immediately** generates a negative invoice granting credits to the customer\n\n### Previewing changes before executing\n\nSimilar to [`billing.previewAttach`](/documentation/customers/payment-flow#step-1-preview-the-charge), you can use `billing.previewUpdate` to see exactly what will be charged before making changes. This returns line items and totals that you can display in a confirmation UI.\n\n<CodeGroup>\n\n```typescript TypeScript\nconst preview = await autumn.billing.previewUpdate({\n  customerId: "user_123",\n  planId: "team",\n  featureQuantities: [\n    { featureId: "seats", quantity: 10 }\n  ],\n});\n\n// Display preview.lineItems, preview.total, preview.currency\n// Then call billing.update to execute\n```\n\n```python Python\npreview = await autumn.billing.preview_update(\n    customer_id="user_123",\n    plan_id="team",\n    feature_quantities=[\n        { "feature_id": "seats", "quantity": 10 }\n    ],\n)\n\n# Display preview.line_items, preview.total\n```\n\n```bash cURL\ncurl -X POST \'https://api.useautumn.com/v1/billing/preview-update\' \\\n  -H \'Authorization: Bearer am_sk_...\' \\\n  -H \'Content-Type: application/json\' \\\n  -d \'{\n    "customer_id": "user_123",\n    "plan_id": "team",\n    "feature_quantities": [\n      { "feature_id": "seats", "quantity": 10 }\n    ]\n  }\'\n```\n\n</CodeGroup>\n\n### Skipping charges\n\nIf you want to update a subscription without creating any charges or credits, pass `prorationBehavior: "none"`:\n\n```typescript\nawait autumn.billing.update({\n  customerId: "user_123",\n  planId: "team",\n  featureQuantities: [\n    { featureId: "seats", quantity: 10 }\n  ],\n  prorationBehavior: "none", // No charges or credits created\n});\n```\n\nThis is useful for administrative adjustments or when you want to handle billing separately.',
 			},
 			{
 				path: "references/edge-cases.md",