chore: serve OpenAPI spec at /openapi.yml and /openapi.json

.claude/rules/sdk.mdc

@@ -6,6 +6,8 @@ alwaysApply: true
 
 Zod Schemas → ORPC Contracts → OpenAPI Spec → Speakeasy SDKs → autumn-js Wrapper → React Hooks
 
+Webhook Zod Schemas → Webhook Registry → OpenAPI Spec (injected) + Svix Event Types
+
 Run `bun api` from root to execute the full pipeline.
 
 ---
@@ -152,15 +154,40 @@ When writing documentation examples for React hooks or the TypeScript SDK, alway
 
 ---
 
-## 6. Testing (sdk-test)
+## 6. Webhook Pipeline
+
+**Registry:** `shared/api/webhooks/webhookRegistry.ts`
+
+Each webhook is defined as a `WebhookDefinition` with `eventType`, `operationId`, `title`, `schema` (Zod), `description`, and `group`. Schemas live in `shared/api/webhooks/`.
+
+### OpenAPI injection
+
+`packages/openapi/v2.1/webhooks/injectWebhooks.ts` reads the registry and injects `webhooks` entries into the generated OpenAPI document. Only definitions with a Zod schema are included.
+
+### Svix sync
+
+`packages/openapi/scripts/svixPush.ts` pushes event types to Svix (create or update). It does **not** delete event types missing from the registry.
+
+### Adding a new webhook event
+
+1. **Create schema** in `shared/api/webhooks/` (Zod schema with `.meta()` descriptions)
+2. **Add to registry** in `shared/api/webhooks/webhookRegistry.ts`
+3. **Add to `WebhookEventType`** enum in `shared/api/webhooks/webhookEventType.ts`
+4. **Re-export** from `shared/api/webhooks/index.ts`
+5. **Regenerate** via `bun api` (webhooks are injected into the OpenAPI spec automatically)
+6. **Push to Svix** via `bun run --cwd packages/openapi scripts/svixPush.ts`
+
+---
+
+## 7. Testing (sdk-test)
 
 **Location:** `apps/sdk-test/`
 
 Scenario pages organized by provider: `scenarios/core/`, `scenarios/better-auth/`, `scenarios/convex/`.
 
 ---
 
-## Adding a New Route
+## Adding a New API Route
 
 1. **Add contract** in `packages/openapi/v2.1/contracts/`
 2. **Add to router** in `packages/openapi/v2.1/contracts/index.ts`
@@ -184,3 +211,7 @@ Scenario pages organized by provider: `scenarios/core/`, `scenarios/better-auth/
 | React client | `packages/autumn-js/src/react/client/AutumnClient.ts` |
 | React hooks | `packages/autumn-js/src/react/hooks/` |
 | SDK tests | `apps/sdk-test/` |
+| Webhook schemas | `shared/api/webhooks/` |
+| Webhook registry | `shared/api/webhooks/webhookRegistry.ts` |
+| Webhook OpenAPI injection | `packages/openapi/v2.1/webhooks/injectWebhooks.ts` |
+| Svix push script | `packages/openapi/scripts/svixPush.ts` |

apps/docs/mintlify/api-reference/billing/attach.mdx

@@ -77,15 +77,15 @@ This is useful for attaching custom metadata to the Stripe subscription created
 ### Body Parameters
 
 <DynamicParamField body="customer_id" type="string" required>
-    The ID of the customer to attach the plan to.
+  The ID of the customer to attach the plan to.
 </DynamicParamField>
 
 <DynamicParamField body="entity_id" type="string">
-    The ID of the entity to attach the plan to.
+  The ID of the entity to attach the plan to.
 </DynamicParamField>
 
 <DynamicParamField body="plan_id" type="string" required>
-    The ID of the plan.
+  The ID of the plan.
 </DynamicParamField>
 
 <DynamicParamField body="feature_quantities" type="object[]">
@@ -107,7 +107,7 @@ This is useful for attaching custom metadata to the Stripe subscription created
 </DynamicParamField>
 
 <DynamicParamField body="version" type="number">
-    The version of the plan to attach.
+  The version of the plan to attach.
 </DynamicParamField>
 
 <DynamicParamField body="customize" type="object">
@@ -278,28 +278,16 @@ This is useful for attaching custom metadata to the Stripe subscription created
   </Expandable>
 </DynamicParamField>
 
-<DynamicParamField
-    body="proration_behavior"
-    type="'prorate_immediately' | 'none'"
->
-    How to handle proration when updating an existing subscription.
-    'prorate_immediately' charges/credits prorated amounts now, 'none' skips
-    creating any charges.
+<DynamicParamField body="proration_behavior" type="'prorate_immediately' | 'none'">
+  How to handle proration when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'none' skips creating any charges.
 </DynamicParamField>
 
-<DynamicParamField
-    body="redirect_mode"
-    type="'always' | 'if_required' | 'never'"
->
-    Controls when to return a checkout URL. 'always' returns a URL even if
-    payment succeeds, 'if_required' only when payment action is needed, 'never'
-    disables redirects.
+<DynamicParamField body="redirect_mode" type="'always' | 'if_required' | 'never'">
+  Controls when to return a checkout URL. 'always' returns a URL even if payment succeeds, 'if_required' only when payment action is needed, 'never' disables redirects.
 </DynamicParamField>
 
 <DynamicParamField body="subscription_id" type="string">
-    A unique ID to identify this subscription. Can be used to target specific
-    subscriptions in update operations when a customer has multiple products
-    with the same plan.
+  A unique ID to identify this subscription. Can be used to target specific subscriptions in update operations when a customer has multiple products with the same plan.
 </DynamicParamField>
 
 <DynamicParamField body="discounts" type="object[]">
@@ -317,24 +305,19 @@ This is useful for attaching custom metadata to the Stripe subscription created
 </DynamicParamField>
 
 <DynamicParamField body="success_url" type="string">
-    URL to redirect to after successful checkout.
+  URL to redirect to after successful checkout.
 </DynamicParamField>
 
 <DynamicParamField body="new_billing_subscription" type="boolean">
-    Only applicable when the customer has an existing Stripe subscription. If
-    true, creates a new separate subscription instead of merging into the
-    existing one.
+  Only applicable when the customer has an existing Stripe subscription. If true, creates a new separate subscription instead of merging into the existing one.
 </DynamicParamField>
 
 <DynamicParamField body="plan_schedule" type="'immediate' | 'end_of_cycle'">
-    When the plan change should take effect. 'immediate' applies now,
-    'end_of_cycle' schedules for the end of the current billing cycle. By
-    default, upgrades are immediate and downgrades are scheduled.
+  When the plan change should take effect. 'immediate' applies now, 'end_of_cycle' schedules for the end of the current billing cycle. By default, upgrades are immediate and downgrades are scheduled.
 </DynamicParamField>
 
 <DynamicParamField body="checkout_session_params" type="object">
-    Additional parameters to pass into the creation of the Stripe checkout
-    session.
+  Additional parameters to pass into the creation of the Stripe checkout session.
 </DynamicParamField>
 
 <DynamicParamField body="custom_line_items" type="object[]">
@@ -352,8 +335,7 @@ This is useful for attaching custom metadata to the Stripe subscription created
 </DynamicParamField>
 
 <DynamicParamField body="processor_subscription_id" type="string">
-    The processor subscription ID to link. Use this to attach an existing Stripe
-    subscription instead of creating a new one.
+  The processor subscription ID to link. Use this to attach an existing Stripe subscription instead of creating a new one.
 </DynamicParamField>
 
 <DynamicParamField body="carry_over_balances" type="object">
@@ -384,14 +366,15 @@ This is useful for attaching custom metadata to the Stripe subscription created
   </Expandable>
 </DynamicParamField>
 
+
 ### Response
 
 <DynamicResponseField name="customer_id" type="string">
-    The ID of the customer.
+  The ID of the customer.
 </DynamicResponseField>
 
 <DynamicResponseField name="entity_id" type="string">
-    The ID of the entity, if the plan was attached to an entity.
+  The ID of the entity, if the plan was attached to an entity.
 </DynamicResponseField>
 
 <DynamicResponseField name="invoice" type="object">
@@ -421,8 +404,7 @@ This is useful for attaching custom metadata to the Stripe subscription created
 </DynamicResponseField>
 
 <DynamicResponseField name="payment_url" type="string | null">
-    URL to redirect the customer to complete payment. Null if no payment action
-    is required.
+  URL to redirect the customer to complete payment. Null if no payment action is required.
 </DynamicResponseField>
 
 <DynamicResponseField name="required_action" type="object">
@@ -439,6 +421,7 @@ This is useful for attaching custom metadata to the Stripe subscription created
   </Expandable>
 </DynamicResponseField>
 
+
 <ResponseExample>
 ```json 200
 {

apps/docs/mintlify/api-reference/billing/billingUpdate.mdx

@@ -265,6 +265,16 @@ const response = await autumn.billing.update({
   If true, the subscription is updated internally without applying billing changes in Stripe.
 </DynamicParamField>
 
+<DynamicParamField body="recalculate_balances" type="object">
+  Controls whether balances should be recalculated during the subscription update.
+  <Expandable title="properties">
+    <DynamicParamField body="enabled" type="boolean" required>
+      If true, recalculates balances during the subscription update. Only applicable when updating feature quantities.
+    </DynamicParamField>
+
+  </Expandable>
+</DynamicParamField>
+
 
 ### Response
 

apps/docs/mintlify/api-reference/billing/multiAttach.mdx

@@ -347,6 +347,32 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
           </Expandable>
         </DynamicParamField>
 
+        <DynamicParamField body="usage_alerts" type="object[]">
+          List of usage alert configurations per feature.
+          <Expandable title="properties">
+            <DynamicParamField body="feature_id" type="string">
+              The feature ID this alert applies to. If omitted, the alert applies globally.
+            </DynamicParamField>
+
+            <DynamicParamField body="enabled" type="boolean">
+              Whether this usage alert is enabled.
+            </DynamicParamField>
+
+            <DynamicParamField body="threshold" type="number" required>
+              The threshold value that triggers the alert. For usage, this is an absolute count. For usage_percentage, this is a percentage (0-100).
+            </DynamicParamField>
+
+            <DynamicParamField body="threshold_type" type="'usage' | 'usage_percentage'" required>
+              Whether the threshold is an absolute usage count or a percentage of the usage allowance.
+            </DynamicParamField>
+
+            <DynamicParamField body="name" type="string">
+              Optional user-defined label to distinguish multiple alerts on the same feature.
+            </DynamicParamField>
+
+          </Expandable>
+        </DynamicParamField>
+
       </Expandable>
     </DynamicParamField>
 
@@ -384,6 +410,32 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
           </Expandable>
         </DynamicParamField>
 
+        <DynamicParamField body="usage_alerts" type="object[]">
+          List of usage alert configurations per feature.
+          <Expandable title="properties">
+            <DynamicParamField body="feature_id" type="string">
+              The feature ID this alert applies to. If omitted, the alert applies globally.
+            </DynamicParamField>
+
+            <DynamicParamField body="enabled" type="boolean">
+              Whether this usage alert is enabled.
+            </DynamicParamField>
+
+            <DynamicParamField body="threshold" type="number" required>
+              The threshold value that triggers the alert. For usage, this is an absolute count. For usage_percentage, this is a percentage (0-100).
+            </DynamicParamField>
+
+            <DynamicParamField body="threshold_type" type="'usage' | 'usage_percentage'" required>
+              Whether the threshold is an absolute usage count or a percentage of the usage allowance.
+            </DynamicParamField>
+
+            <DynamicParamField body="name" type="string">
+              Optional user-defined label to distinguish multiple alerts on the same feature.
+            </DynamicParamField>
+
+          </Expandable>
+        </DynamicParamField>
+
       </Expandable>
     </DynamicParamField>
 

apps/docs/mintlify/api-reference/billing/previewAttach.mdx

@@ -307,7 +307,6 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
 </DynamicResponseField>
 
 <DynamicResponseField name="line_items" type="object[]">
-  List of line items for the current billing period.
   <Expandable title="properties">
     <DynamicResponseField name="display_name" type="string">
       The name of the line item to display to the customer if you're building a UI. It will either be the plan name or the feature name.
@@ -796,6 +795,14 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
       When this change takes effect, in milliseconds since the Unix epoch, or null if it applies immediately.
     </DynamicResponseField>
 
+    <DynamicResponseField name="canceled_at" type="number | null">
+      When this plan was canceled, in milliseconds since the Unix epoch, or null if it is not canceled.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="expires_at" type="number | null">
+      When this plan expires, in milliseconds since the Unix epoch, or null if it does not expire.
+    </DynamicResponseField>
+
   </Expandable>
 </DynamicResponseField>
 
@@ -1099,9 +1106,25 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
       When this change takes effect, in milliseconds since the Unix epoch, or null if it applies immediately.
     </DynamicResponseField>
 
+    <DynamicResponseField name="canceled_at" type="number | null">
+      When this plan was canceled, in milliseconds since the Unix epoch, or null if it is not canceled.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="expires_at" type="number | null">
+      When this plan expires, in milliseconds since the Unix epoch, or null if it does not expire.
+    </DynamicResponseField>
+
   </Expandable>
 </DynamicResponseField>
 
+<DynamicResponseField name="redirect_to_checkout" type="boolean">
+  Whether the customer will be redirected to a checkout page if attach is called.
+</DynamicResponseField>
+
+<DynamicResponseField name="checkout_type" type="'stripe_checkout' | 'autumn_checkout'">
+  The type of checkout that will be used if the customer is redirected to a checkout page.
+</DynamicResponseField>
+
 
 <ResponseExample>
 ```json 200