atmn 2.0.123 → 2.0.124

package/dist/bin.js

@@ -7635,7 +7635,7 @@ var createClient = (options) => ({
 });
 
 // src/version.ts
-var version = "2.0.123";
+var version = "2.0.124";
 
 // src/http/autumnFetch.ts
 var runtime = typeof Bun !== "undefined" ? `bun ${Bun.version}` : `node ${process.versions.node}`;
@@ -16001,6 +16001,55 @@ curl -X POST 'https://api.useautumn.com/v1/billing/update' \\
 
 </CodeGroup>
 
+## Switching between invoicing and charging automatically
+
+Call \`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.
+
+<CodeGroup>
+
+\`\`\`typescript TypeScript
+// Send invoices from the next renewal, due in 30 days, payable by card or ACH
+await autumn.billing.update({
+  customerId: "user_123",
+  planId: "team",
+  invoiceMode: {
+    enabled: true,
+    netTermsDays: 30,
+    paymentMethodTypes: ["card", "us_bank_account"],
+  },
+});
+
+// Charge the card on file automatically again
+await autumn.billing.update({
+  customerId: "user_123",
+  planId: "team",
+  invoiceMode: { enabled: false },
+});
+\`\`\`
+
+\`\`\`bash cURL
+curl -X POST 'https://api.useautumn.com/v1/billing.update' \\
+  -H 'Authorization: Bearer am_sk_...' \\
+  -H 'Content-Type: application/json' \\
+  -d '{
+    "customer_id": "user_123",
+    "plan_id": "team",
+    "invoice_mode": {
+      "enabled": true,
+      "net_terms_days": 30,
+      "payment_method_types": ["card", "us_bank_account"]
+    }
+  }'
+\`\`\`
+
+</CodeGroup>
+
+- Switching to charging automatically requires a payment method on file; otherwise the request is rejected.
+- \`payment_method_types\` overrides your organization's default payment methods. Omit it to keep the defaults.
+- If the request changes anything else (plan, quantities, items), \`invoice_mode\` describes how that change is billed instead of switching the subscription.
+
+To change the payment methods on an invoice that is already draft or open, use [\`invoices.update\`](/api-reference/invoices/updateInvoice).
+
 ## 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.123",
+  "version": "2.0.124",
   "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": "6013949eb399b230b6e656ea625946802e1b03ff"
+  "gitHead": "6213e05bc3f8151a19622e8ca537b82a67e776aa"
 }

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## 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## 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",