latest

.claude/commands/add-to-autumn-js.md

@@ -0,0 +1,84 @@
+---
+description: Add a new Autumn API endpoint into autumn-js (backend route, generated schemas, better-auth plugin, React hooks, docs, and sdk-test UI)
+argument-hint: [endpoint-name] [sdk-namespace.method]
+---
+
+# Add to Autumn JS
+
+Add a new endpoint end-to-end in `packages/autumn-js` following existing patterns (especially billing attach/open portal).
+
+## Inputs you need
+
+- Endpoint route name in autumn-js (example: `openCustomerPortal`)
+- SDK method path (example: `autumn.billing.openCustomerPortal(args)`)
+- SDK model file in `packages/sdk/src/models` (example: `open-customer-portal-op.ts`)
+- Whether frontend helper needs redirect behavior (`openInNewTab`) and default URL behavior
+
+## Required implementation checklist
+
+1. Update backend route names and route config:
+- `packages/autumn-js/src/backend/core/types/routeTypes.ts`
+  - Add to `ROUTE_NAMES`
+- `packages/autumn-js/src/backend/core/routes/routeConfigs.ts`
+  - Add route entry with `route`, `sdkMethod`, and `bodySchema`
+  - Import schema from `packages/autumn-js/src/generated`
+
+2. Update schema generation for better-auth body validation:
+- `packages/openapi/utils/zodSchemaGeneration.ts`
+  - Add `SCHEMA_SOURCES` entry for the SDK model file
+- Ensure generated schema file exists in `packages/autumn-js/src/generated/`
+  - If not generated yet, add it manually using the same style as existing generated files
+- Export it from `packages/autumn-js/src/generated/index.ts`
+
+3. Update better-auth plugin endpoint map:
+- `packages/autumn-js/src/better-auth/index.ts`
+  - Add `createAutumnEndpoint("<routeName>", handleRoute)`
+
+4. Update client and types:
+- `packages/autumn-js/src/types/params.ts`
+  - Add client params type (usually omit protected fields, add `openInNewTab?` when redirecting)
+- `packages/autumn-js/src/types/index.ts`
+  - Re-export alias
+- `packages/autumn-js/src/react/index.ts`
+  - Export the new client params type
+- `packages/autumn-js/src/react/client/IAutumnClient.ts`
+  - Add interface method
+- `packages/autumn-js/src/react/client/AutumnClient.ts`
+  - Add HTTP route call
+
+5. Update hook actions and docs:
+- `packages/autumn-js/src/react/hooks/internal/useCustomerActions.ts`
+  - Add method implementation
+  - If redirect flow: support `openInNewTab` and default `returnUrl` to `window.location.href`
+- `packages/autumn-js/src/react/hooks/useCustomer.ts`
+  - Add method to `UseCustomerResult`
+  - Add concise JSDoc for the method and update return summary
+
+6. Add sdk-test scenario controls:
+- `apps/sdk-test/app/scenarios/core/use-autumn/page.tsx`
+  - Add new action tab/button
+  - Add compact input(s) for required params (for billing portal include `returnUrl`)
+  - Wire action through `runAction`
+
+## Billing endpoint specifics
+
+For billing endpoints with redirect URLs:
+- Add `openInNewTab?: boolean` to frontend client params type
+- In `useCustomerActions`, default `returnUrl` to `window.location.href` when missing
+- Reuse the existing `redirectToUrl` helper pattern from `attach`
+
+## Validation checklist
+
+- Run scoped Biome checks only on touched files:
+`bunx biome check <paths>`
+- If formatting/import issues appear, run:
+`bunx biome check --write <paths>`
+- Avoid running `dev` or `build` commands.
+
+## Done criteria
+
+- Route works in backend core handler and better-auth endpoints
+- Generated schema is available and imported in route config
+- React client + hook exposes the new action
+- `useCustomer` type/JSDoc includes it
+- sdk-test page has a working action button and inputs

apps/docs/CLAUDE.md

@@ -1,5 +1,16 @@
 When writing the docs, always make sure to add it to `docs.json` for it to appear
 
+## Manual API Documentation
+
+Manual documentation (explanations, examples, use cases) should go in `api-reference-generator/` folder, NOT in `mintlify/api-reference/`. The generator merges manual content from `api-reference-generator/` with auto-generated body params and outputs the final result to `mintlify/api-reference/`.
+
+**Workflow:**
+1. Create/edit manual docs in `apps/docs/api-reference-generator/<category>/<operationId>.mdx`
+2. Run the generator to merge with generated params
+3. Output goes to `apps/docs/mintlify/api-reference/<category>/<operationId>.mdx`
+
+**Never edit files directly in `mintlify/api-reference/`** - they will be overwritten by the generator.
+
 ## DynamicParamField Component
 
 **Location:** `snippets/dynamic-param-field.jsx`

apps/docs/api-reference-generator/billing/billingAttach.mdx

@@ -0,0 +1,53 @@
+---
+title: "Attach"
+openapi: "openapi POST /v1/billing.attach"
+---
+
+import { DynamicParamField } from "/components/dynamic-param-field.jsx";
+import { DynamicResponseField } from "/components/dynamic-response-field.jsx";
+import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";
+
+<Note>
+  The attach endpoint subscribes a customer to a plan. It handles new subscriptions, upgrades, and downgrades automatically. For modifying an existing subscription (like changing quantities or canceling), use [update](/api-reference/billing/billingUpdate) instead.
+</Note>
+
+### Common Use Cases
+
+<CodeGroup>
+
+```typescript Subscribe to a plan
+const response = await autumn.billing.attach({
+  customerId: "cus_123",
+  planId: "pro_plan"
+});
+
+if (response.paymentUrl) {
+  // Redirect customer to checkout
+  window.location.href = response.paymentUrl;
+}
+```
+
+```typescript Custom pricing
+const response = await autumn.billing.attach({
+  customerId: "cus_123",
+  planId: "enterprise_plan",
+  customize: {
+    price: {
+      amount: 99900, // $999.00
+      interval: "month"
+    }
+  }
+});
+```
+
+```typescript Attach plan with prepaid quantities
+const response = await autumn.billing.attach({
+  customerId: "cus_123",
+  planId: "team_plan",
+  featureQuantities: [
+    { featureId: "seats", quantity: 5 }
+  ]
+});
+```
+
+</CodeGroup>

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

@@ -0,0 +1,42 @@
+---
+title: "Update Subscription"
+openapi: "openapi POST /v1/billing.update"
+---
+
+import { DynamicParamField } from "/components/dynamic-param-field.jsx";
+import { DynamicResponseField } from "/components/dynamic-response-field.jsx";
+import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";
+
+<Note>
+  The update endpoint modifies an existing subscription. Use this to change prepaid quantities, cancel subscriptions, or modify plan configuration. For subscribing to a new plan, use [attach](/api-reference/billing/billingAttach) instead.
+</Note>
+
+### Common Use Cases
+
+<CodeGroup>
+
+```typescript Update prepaid quantity
+const response = await autumn.billing.update({
+  customerId: "cus_123",
+  planId: "pro_plan",
+  featureQuantities: [{ featureId: "seats", quantity: 10 }]
+});
+```
+
+```typescript Cancel at end of cycle
+const response = await autumn.billing.update({
+  customerId: "cus_123",
+  planId: "pro_plan",
+  cancelAction: "cancel_end_of_cycle"
+});
+```
+
+```typescript Uncancel subscription
+const response = await autumn.billing.update({
+  customerId: "cus_123",
+  planId: "pro_plan",
+  cancelAction: "uncancel"
+});
+```
+
+</CodeGroup>

apps/docs/api-reference-generator/billing/update.mdx

@@ -0,0 +1,53 @@
+---
+title: "Update Subscription"
+openapi: "openapi POST /v1/billing.update"
+---
+
+import { DynamicParamField } from "/components/dynamic-param-field.jsx";
+import { DynamicResponseField } from "/components/dynamic-response-field.jsx";
+import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";
+
+<Note>
+  The update endpoint modifies an existing subscription. Use this to change prepaid quantities, cancel subscriptions, or modify plan configuration. For subscribing to a new plan, use [attach](/api-reference/billing/attach) instead.
+</Note>
+
+## Common Use Cases
+
+<AccordionGroup>
+  <Accordion title="Update prepaid feature quantity">
+    Change the quantity of a prepaid feature (like seats) on an existing subscription.
+    
+    ```typescript
+    const response = await autumn.billing.update({
+      customerId: "cus_123",
+      planId: "pro_plan",
+      featureQuantities: [{ featureId: "seats", quantity: 10 }]
+    });
+    ```
+  </Accordion>
+
+  <Accordion title="Cancel at end of billing cycle">
+    Schedule a subscription to cancel at the end of the current billing period. The customer retains access until then.
+    
+    ```typescript
+    const response = await autumn.billing.update({
+      customerId: "cus_123",
+      planId: "pro_plan",
+      cancelAction: "cancel_end_of_cycle"
+    });
+    ```
+  </Accordion>
+
+  <Accordion title="Uncancel a subscription">
+    Reactivate a subscription that was scheduled for cancellation.
+    
+    ```typescript
+    const response = await autumn.billing.update({
+      customerId: "cus_123",
+      planId: "pro_plan",
+      cancelAction: "uncancel"
+    });
+    ```
+  </Accordion>
+</AccordionGroup>
+

apps/docs/api-reference-generator/core/check.mdx

@@ -0,0 +1,40 @@
+---
+title: "Check Permissions"
+openapi: "openapi POST /v1/balances.check"
+---
+
+import { DynamicParamField } from "/components/dynamic-param-field.jsx";
+import { DynamicResponseField } from "/components/dynamic-response-field.jsx";
+import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";
+
+<Note>
+  Check determines if a customer has access to a feature based on their current balance. Returns `allowed: true` if they have sufficient balance, the feature is unlimited, or it's a boolean feature included in their plan.
+</Note>
+
+### Common Use Cases
+
+<CodeGroup>
+
+```typescript Check feature access
+const { allowed, balance } = await autumn.check({
+  customerId: "cus_123",
+  featureId: "ai_messages"
+});
+
+if (!allowed) {
+  // Show upgrade prompt or paywall
+}
+
+console.log(`You have ${balance.remaining} messages left`);
+```
+
+```typescript Check and track atomically
+const { allowed } = await autumn.check({
+  customerId: "cus_123",
+  featureId: "api_calls",
+  requiredBalance: 1,
+  sendEvent: true // Deducts usage if allowed
+});
+```
+
+</CodeGroup>

apps/docs/api-reference-generator/core/track.mdx

@@ -0,0 +1,43 @@
+---
+title: "Track Usage"
+openapi: "openapi POST /v1/balances.track"
+---
+
+import { DynamicParamField } from "/components/dynamic-param-field.jsx";
+import { DynamicResponseField } from "/components/dynamic-response-field.jsx";
+import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";
+
+<Note>
+  Track records usage events to decrement a customer's balance. Use this to meter feature consumption like API calls, messages sent, or credits used.
+</Note>
+
+### Common Use Cases
+
+<CodeGroup>
+
+```typescript Track single usage
+await autumn.track({
+  customerId: "cus_123",
+  featureId: "ai_messages",
+  value: 1
+});
+```
+
+```typescript Track with idempotency
+await autumn.track({
+  customerId: "cus_123",
+  featureId: "api_calls",
+  value: 1,
+  idempotencyKey: "request_abc123" // Prevents duplicate tracking on retry
+});
+```
+
+```typescript Credit balance (negative value)
+await autumn.track({
+  customerId: "cus_123",
+  featureId: "seats",
+  value: -1 // Increases balance when removing a seat
+});
+```
+
+</CodeGroup>

apps/docs/api-reference-generator/events/aggregateEvents.mdx

@@ -0,0 +1,95 @@
+---
+title: "Aggregate Events"
+openapi: "openapi POST /v1/events.aggregate"
+---
+
+import { DynamicParamField } from "/components/dynamic-param-field.jsx";
+import { DynamicResponseField } from "/components/dynamic-response-field.jsx";
+import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";
+
+Aggregate usage events by time period. Returns usage totals grouped by feature and optionally by a custom property.
+
+## Working with Properties
+
+When tracking events, you can attach custom properties that can later be used for grouping aggregations:
+
+```typescript
+// Track an event with properties
+await autumn.track({
+  customerId: "cus_123",
+  featureId: "api_calls",
+  value: 1,
+  properties: {
+    model: "gpt-4",
+    source: "api",
+    region: "us-east"
+  }
+});
+```
+
+You can then aggregate events grouped by any property using the `group_by` parameter:
+
+```typescript
+const result = await autumn.events.aggregate({
+  customerId: "cus_123",
+  featureId: "api_calls",
+  range: "7d",
+  groupBy: "properties.model"  // Group by the "model" property
+});
+```
+
+## Response Format
+
+The response structure changes based on whether `group_by` is provided:
+
+### Without `group_by` (Flat Response)
+
+When no grouping is specified, `values` contains the aggregated sum for each feature:
+
+```json
+{
+  "list": [
+    {
+      "period": 1762905600000,
+      "values": {
+        "api_calls": 150,
+        "messages": 45
+      }
+    }
+  ],
+  "total": {
+    "api_calls": { "count": 10, "sum": 150 },
+    "messages": { "count": 5, "sum": 45 }
+  }
+}
+```
+
+### With `group_by` (Grouped Response)
+
+When grouping is specified, `values` contains the total sum while `grouped_values` breaks down values by group:
+
+```json
+{
+  "list": [
+    {
+      "period": 1762905600000,
+      "values": {
+        "api_calls": 150
+      },
+      "grouped_values": {
+        "api_calls": {
+          "gpt-4": 100,
+          "gpt-3.5": 50
+        }
+      }
+    }
+  ],
+  "total": {
+    "api_calls": { "count": 10, "sum": 150 }
+  }
+}
+```
+
+<Note>
+  The `grouped_values` field is only present when `group_by` is provided in the request.
+</Note>

apps/docs/mintlify/api-reference/balances/balancesTrack.mdx

@@ -1,176 +0,0 @@
----
-title: "Balances Track"
-openapi: "openapi POST /v1/balances.track"
----
-
-import { DynamicParamField } from "/components/dynamic-param-field.jsx";
-import { DynamicResponseField } from "/components/dynamic-response-field.jsx";
-import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";
-
-### Body Parameters
-
-<DynamicParamField body="customer_id" type="string" required>
-  ID which you provided when creating the customer
-</DynamicParamField>
-
-<DynamicParamField body="feature_id" type="string">
-  ID of the feature to track usage for. Required if event_name is not provided. Use this for direct feature tracking.
-</DynamicParamField>
-
-<DynamicParamField body="event_name" type="string">
-  An [event name](/features/tracking-usage#using-event-names) can be used in place of feature_id. This can be used if multiple features are tracked in the same event.
-</DynamicParamField>
-
-<DynamicParamField body="value" type="number">
-  The amount of usage to record. Defaults to 1. Can be negative to increase the balance (e.g., when removing a seat).
-</DynamicParamField>
-
-<DynamicParamField body="properties" type="object">
-  Additional properties to attach to this usage event.
-</DynamicParamField>
-
-<DynamicParamField body="idempotency_key" type="string">
-  Unique key to prevent duplicate event recording. Use this to safely retry requests without creating duplicate usage records.
-</DynamicParamField>
-
-<DynamicParamField body="entity_id" type="string">
-  If using [entity balances](/features/feature-entities) (eg, seats), the entity ID to track usage for.
-</DynamicParamField>
-
-
-### Response
-
-<DynamicResponseField name="customer_id" type="string">
-  The ID of the customer
-</DynamicResponseField>
-
-<DynamicResponseField name="entity_id" type="string">
-  The ID of the entity (if provided)
-</DynamicResponseField>
-
-<DynamicResponseField name="event_name" type="string">
-  The name of the event
-</DynamicResponseField>
-
-<DynamicResponseField name="value" type="number" />
-
-<DynamicResponseField name="balance" type="object | null">
-  <Expandable title="properties">
-    <DynamicResponseField name="feature_id" type="string" />
-
-    <DynamicResponseField name="feature" type="object">
-      <Expandable title="properties">
-        <DynamicResponseField name="id" type="string" />
-
-        <DynamicResponseField name="name" type="string" />
-
-        <DynamicResponseField name="type" type="'boolean' | 'metered' | 'credit_system'" />
-
-        <DynamicResponseField name="consumable" type="boolean" />
-
-        <DynamicResponseField name="event_names" type="string[]" />
-
-        <DynamicResponseField name="credit_schema" type="object[]">
-          <Expandable title="properties">
-            <DynamicResponseField name="metered_feature_id" type="string" />
-
-            <DynamicResponseField name="credit_cost" type="number" />
-
-          </Expandable>
-        </DynamicResponseField>
-
-        <DynamicResponseField name="display" type="object">
-          <Expandable title="properties">
-            <DynamicResponseField name="singular" type="string | null" />
-
-            <DynamicResponseField name="plural" type="string | null" />
-
-          </Expandable>
-        </DynamicResponseField>
-
-        <DynamicResponseField name="archived" type="boolean" />
-
-      </Expandable>
-    </DynamicResponseField>
-
-    <DynamicResponseField name="granted" type="number" />
-
-    <DynamicResponseField name="remaining" type="number" />
-
-    <DynamicResponseField name="usage" type="number" />
-
-    <DynamicResponseField name="unlimited" type="boolean" />
-
-    <DynamicResponseField name="overage_allowed" type="boolean" />
-
-    <DynamicResponseField name="max_purchase" type="number | null" />
-
-    <DynamicResponseField name="next_reset_at" type="number | null" />
-
-    <DynamicResponseField name="breakdown" type="object[]">
-      <Expandable title="properties">
-        <DynamicResponseField name="id" type="string" />
-
-        <DynamicResponseField name="plan_id" type="string | null" />
-
-        <DynamicResponseField name="included_grant" type="number" />
-
-        <DynamicResponseField name="prepaid_grant" type="number" />
-
-        <DynamicResponseField name="remaining" type="number" />
-
-        <DynamicResponseField name="usage" type="number" />
-
-        <DynamicResponseField name="unlimited" type="boolean" />
-
-        <DynamicResponseField name="reset" type="object | null">
-          <Expandable title="properties">
-            <DynamicResponseField name="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" />
-
-            <DynamicResponseField name="interval_count" type="number" />
-
-            <DynamicResponseField name="resets_at" type="number | null" />
-
-          </Expandable>
-        </DynamicResponseField>
-
-        <DynamicResponseField name="price" type="object | null">
-          <Expandable title="properties">
-            <DynamicResponseField name="amount" type="number" />
-
-            <DynamicResponseField name="tiers" type="object[]">
-              <Expandable title="properties">
-                <DynamicResponseField name="to" type="number" />
-
-                <DynamicResponseField name="amount" type="number" />
-
-              </Expandable>
-            </DynamicResponseField>
-
-            <DynamicResponseField name="billing_units" type="number" />
-
-            <DynamicResponseField name="billing_method" type="'prepaid' | 'usage_based'" />
-
-            <DynamicResponseField name="max_purchase" type="number | null" />
-
-          </Expandable>
-        </DynamicResponseField>
-
-        <DynamicResponseField name="expires_at" type="number | null" />
-
-      </Expandable>
-    </DynamicResponseField>
-
-    <DynamicResponseField name="rollovers" type="object[]">
-      <Expandable title="properties">
-        <DynamicResponseField name="balance" type="number" />
-
-        <DynamicResponseField name="expires_at" type="number" />
-
-      </Expandable>
-    </DynamicResponseField>
-
-  </Expandable>
-</DynamicResponseField>
-
-<DynamicResponseField name="balances" type="object" />

apps/docs/mintlify/api-reference/balances/check.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Balances Check"
+title: "Check Permissions"
 openapi: "openapi POST /v1/balances.check"
 ---
 
@@ -7,50 +7,106 @@ import { DynamicParamField } from "/components/dynamic-param-field.jsx";
 import { DynamicResponseField } from "/components/dynamic-response-field.jsx";
 import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";
 
+<Note>
+  Check determines if a customer has access to a feature based on their current balance. Returns `allowed: true` if they have sufficient balance, the feature is unlimited, or it's a boolean feature included in their plan.
+</Note>
+
+### Common Use Cases
+
+<CodeGroup>
+
+```typescript Check feature access
+const { allowed, balance } = await autumn.balances.check({
+  customerId: "cus_123",
+  featureId: "ai_messages"
+});
+
+if (!allowed) {
+  // Show upgrade prompt or paywall
+}
+```
+
+```typescript Check and track atomically
+const { allowed } = await autumn.balances.check({
+  customerId: "cus_123",
+  featureId: "api_calls",
+  requiredBalance: 1,
+  sendEvent: true // Deducts usage if allowed
+});
+```
+
+```typescript Get upgrade options when denied
+const { allowed, preview } = await autumn.balances.check({
+  customerId: "cus_123",
+  featureId: "advanced_analytics",
+  withPreview: true
+});
+
+if (!allowed && preview) {
+  // Display preview.products as upgrade options
+}
+```
+
+</CodeGroup>
+
 ### Body Parameters
 
 <DynamicParamField body="customer_id" type="string" required>
-  ID which you provided when creating the customer
+  The ID of the customer.
 </DynamicParamField>
 
 <DynamicParamField body="feature_id" type="string" required>
-  ID of the feature to check access to.
+  The ID of the feature.
 </DynamicParamField>
 
 <DynamicParamField body="entity_id" type="string">
-  If using entity balances (eg, seats), the entity ID to check access for.
+  The ID of the entity for entity-scoped balances (e.g., per-seat limits).
 </DynamicParamField>
 
 <DynamicParamField body="required_balance" type="number">
-  If you know the amount of the feature the end user is consuming in advance. If their balance is below this quantity, allowed will be false.
+  Minimum balance required for access. Returns allowed: false if the customer's balance is below this value. Defaults to 1.
 </DynamicParamField>
 
-<DynamicParamField body="properties" type="object" />
+<DynamicParamField body="properties" type="object">
+  Additional properties to attach to the usage event if send_event is true.
+</DynamicParamField>
 
 <DynamicParamField body="send_event" type="boolean">
-  If true, a usage event will be recorded together with checking access. The required_balance field will be used as the usage value.
+  If true, atomically records a usage event while checking access. The required_balance value is used as the usage amount. Combines check + track in one call.
 </DynamicParamField>
 
 <DynamicParamField body="with_preview" type="boolean">
-  If true, the response will include a preview object, which can be used to display information such as a paywall or upgrade confirmation.
+  If true, includes upgrade/upsell information in the response when access is denied. Useful for displaying paywalls.
 </DynamicParamField>
 
 
 ### Response
 
-<DynamicResponseField name="allowed" type="boolean" />
+<DynamicResponseField name="allowed" type="boolean">
+  Whether the customer is allowed to use the feature. True if they have sufficient balance or the feature is unlimited/boolean.
+</DynamicResponseField>
 
-<DynamicResponseField name="customer_id" type="string" />
+<DynamicResponseField name="customer_id" type="string">
+  The ID of the customer that was checked.
+</DynamicResponseField>
 
-<DynamicResponseField name="entity_id" type="string | null" />
+<DynamicResponseField name="entity_id" type="string | null">
+  The ID of the entity, if an entity-scoped check was performed.
+</DynamicResponseField>
 
-<DynamicResponseField name="required_balance" type="number" />
+<DynamicResponseField name="required_balance" type="number">
+  The required balance that was checked against.
+</DynamicResponseField>
 
 <DynamicResponseField name="balance" type="object | null">
+  The customer's balance for this feature. Null if the customer has no balance for this feature.
   <Expandable title="properties">
-    <DynamicResponseField name="feature_id" type="string" />
+    <DynamicResponseField name="feature_id" type="string">
+      The feature ID this balance is for.
+    </DynamicResponseField>
 
     <DynamicResponseField name="feature" type="object">
+      The full feature object if expanded.
       <Expandable title="properties">
         <DynamicResponseField name="id" type="string" />
 
@@ -85,52 +141,92 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
       </Expandable>
     </DynamicResponseField>
 
-    <DynamicResponseField name="granted" type="number" />
+    <DynamicResponseField name="granted" type="number">
+      Total balance granted (included + prepaid).
+    </DynamicResponseField>
 
-    <DynamicResponseField name="remaining" type="number" />
+    <DynamicResponseField name="remaining" type="number">
+      Remaining balance available for use.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="usage" type="number" />
+    <DynamicResponseField name="usage" type="number">
+      Total usage consumed in the current period.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="unlimited" type="boolean" />
+    <DynamicResponseField name="unlimited" type="boolean">
+      Whether this feature has unlimited usage.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="overage_allowed" type="boolean" />
+    <DynamicResponseField name="overage_allowed" type="boolean">
+      Whether usage beyond the granted balance is allowed (with overage charges).
+    </DynamicResponseField>
 
-    <DynamicResponseField name="max_purchase" type="number | null" />
+    <DynamicResponseField name="max_purchase" type="number | null">
+      Maximum quantity that can be purchased as a top-up, or null for unlimited.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="next_reset_at" type="number | null" />
+    <DynamicResponseField name="next_reset_at" type="number | null">
+      Timestamp when the balance will reset, or null for no reset.
+    </DynamicResponseField>
 
     <DynamicResponseField name="breakdown" type="object[]">
+      Detailed breakdown of balance sources when stacking multiple plans or grants.
       <Expandable title="properties">
-        <DynamicResponseField name="id" type="string" />
+        <DynamicResponseField name="id" type="string">
+          The unique identifier for this balance breakdown.
+        </DynamicResponseField>
 
-        <DynamicResponseField name="plan_id" type="string | null" />
+        <DynamicResponseField name="plan_id" type="string | null">
+          The plan ID this balance originates from, or null for standalone balances.
+        </DynamicResponseField>
 
-        <DynamicResponseField name="included_grant" type="number" />
+        <DynamicResponseField name="included_grant" type="number">
+          Amount granted from the plan's included usage.
+        </DynamicResponseField>
 
-        <DynamicResponseField name="prepaid_grant" type="number" />
+        <DynamicResponseField name="prepaid_grant" type="number">
+          Amount granted from prepaid purchases or top-ups.
+        </DynamicResponseField>
 
-        <DynamicResponseField name="remaining" type="number" />
+        <DynamicResponseField name="remaining" type="number">
+          Remaining balance available for use.
+        </DynamicResponseField>
 
-        <DynamicResponseField name="usage" type="number" />
+        <DynamicResponseField name="usage" type="number">
+          Amount consumed in the current period.
+        </DynamicResponseField>
 
-        <DynamicResponseField name="unlimited" type="boolean" />
+        <DynamicResponseField name="unlimited" type="boolean">
+          Whether this balance has unlimited usage.
+        </DynamicResponseField>
 
         <DynamicResponseField name="reset" type="object | null">
+          Reset configuration for this balance, or null if no reset.
           <Expandable title="properties">
-            <DynamicResponseField name="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" />
+            <DynamicResponseField name="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
+              The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
+            </DynamicResponseField>
 
-            <DynamicResponseField name="interval_count" type="number" />
+            <DynamicResponseField name="interval_count" type="number">
+              Number of intervals between resets (eg. 2 for bi-monthly).
+            </DynamicResponseField>
 
-            <DynamicResponseField name="resets_at" type="number | null" />
+            <DynamicResponseField name="resets_at" type="number | null">
+              Timestamp when the balance will next reset.
+            </DynamicResponseField>
 
           </Expandable>
         </DynamicResponseField>
 
         <DynamicResponseField name="price" type="object | null">
+          Pricing configuration if this balance has usage-based pricing.
           <Expandable title="properties">
-            <DynamicResponseField name="amount" type="number" />
+            <DynamicResponseField name="amount" type="number">
+              The per-unit price amount.
+            </DynamicResponseField>
 
             <DynamicResponseField name="tiers" type="object[]">
+              Tiered pricing configuration if applicable.
               <Expandable title="properties">
                 <DynamicResponseField name="to" type="number" />
 
@@ -139,25 +235,38 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
               </Expandable>
             </DynamicResponseField>
 
-            <DynamicResponseField name="billing_units" type="number" />
+            <DynamicResponseField name="billing_units" type="number">
+              The number of units per billing increment (eg. $9 / 250 units).
+            </DynamicResponseField>
 
-            <DynamicResponseField name="billing_method" type="'prepaid' | 'usage_based'" />
+            <DynamicResponseField name="billing_method" type="'prepaid' | 'usage_based'">
+              Whether usage is prepaid or billed pay-per-use.
+            </DynamicResponseField>
 
-            <DynamicResponseField name="max_purchase" type="number | null" />
+            <DynamicResponseField name="max_purchase" type="number | null">
+              Maximum quantity that can be purchased, or null for unlimited.
+            </DynamicResponseField>
 
           </Expandable>
         </DynamicResponseField>
 
-        <DynamicResponseField name="expires_at" type="number | null" />
+        <DynamicResponseField name="expires_at" type="number | null">
+          Timestamp when this balance expires, or null for no expiration.
+        </DynamicResponseField>
 
       </Expandable>
     </DynamicResponseField>
 
     <DynamicResponseField name="rollovers" type="object[]">
+      Rollover balances carried over from previous periods.
       <Expandable title="properties">
-        <DynamicResponseField name="balance" type="number" />
+        <DynamicResponseField name="balance" type="number">
+          Amount of balance rolled over from a previous period.
+        </DynamicResponseField>
 
-        <DynamicResponseField name="expires_at" type="number" />
+        <DynamicResponseField name="expires_at" type="number">
+          Timestamp when the rollover balance expires.
+        </DynamicResponseField>
 
       </Expandable>
     </DynamicResponseField>
@@ -166,18 +275,30 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
 </DynamicResponseField>
 
 <DynamicResponseField name="preview" type="object">
+  Upgrade/upsell information when access is denied. Only present if with_preview was true and allowed is false.
   <Expandable title="properties">
-    <DynamicResponseField name="scenario" type="'usage_limit' | 'feature_flag'" />
+    <DynamicResponseField name="scenario" type="'usage_limit' | 'feature_flag'">
+      The reason access was denied. 'usage_limit' means the customer exceeded their balance, 'feature_flag' means the feature is not included in their plan.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="title" type="string" />
+    <DynamicResponseField name="title" type="string">
+      A title suitable for displaying in a paywall or upgrade modal.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="message" type="string" />
+    <DynamicResponseField name="message" type="string">
+      A message explaining why access was denied.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="feature_id" type="string" />
+    <DynamicResponseField name="feature_id" type="string">
+      The ID of the feature that was checked.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="feature_name" type="string" />
+    <DynamicResponseField name="feature_name" type="string">
+      The display name of the feature.
+    </DynamicResponseField>
 
     <DynamicResponseField name="products" type="object[]">
+      Products that would grant access to this feature. Use to display upgrade options.
       <Expandable title="properties">
         <DynamicResponseField name="id" type="string">
           The ID of the product you set when creating the product
@@ -382,3 +503,42 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
 
   </Expandable>
 </DynamicResponseField>
+
+
+<ResponseExample>
+```json 200
+{
+  "allowed": true,
+  "customer_id": "cus_123",
+  "entity_id": null,
+  "required_balance": 1,
+  "balance": {
+    "feature_id": "messages",
+    "granted": 100,
+    "remaining": 72,
+    "usage": 28,
+    "unlimited": false,
+    "overage_allowed": false,
+    "max_purchase": null,
+    "next_reset_at": 1773851121437,
+    "breakdown": [
+      {
+        "id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
+        "plan_id": "pro_plan",
+        "included_grant": 100,
+        "prepaid_grant": 0,
+        "remaining": 72,
+        "usage": 28,
+        "unlimited": false,
+        "reset": {
+          "interval": "month",
+          "resets_at": 1773851121437
+        },
+        "price": null,
+        "expires_at": null
+      }
+    ]
+  }
+}
+```
+</ResponseExample>

apps/docs/mintlify/api-reference/balances/createBalance.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Balances Create"
+title: "Create Balance"
 openapi: "openapi POST /v1/balances.create"
 ---
 
@@ -9,38 +9,42 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
 
 ### Body Parameters
 
-<DynamicParamField body="feature_id" type="string" required>
-  The feature ID to create the balance for
+<DynamicParamField body="customer_id" type="string" required>
+  The ID of the customer.
 </DynamicParamField>
 
-<DynamicParamField body="customer_id" type="string" required>
-  The customer ID to assign the balance to
+<DynamicParamField body="feature_id" type="string" required>
+  The ID of the feature.
 </DynamicParamField>
 
 <DynamicParamField body="entity_id" type="string">
-  Entity ID for entity-scoped balances
+  The ID of the entity for entity-scoped balances (e.g., per-seat limits).
 </DynamicParamField>
 
 <DynamicParamField body="included" type="number">
-  The initial balance amount to grant
+  The initial balance amount to grant. For metered features, this is the number of units the customer can use.
 </DynamicParamField>
 
 <DynamicParamField body="unlimited" type="boolean">
-  Whether the balance is unlimited
+  If true, the balance has unlimited usage. Cannot be combined with 'included'.
 </DynamicParamField>
 
 <DynamicParamField body="reset" type="object">
-  Reset configuration for the balance
+  Reset configuration for the balance. If not provided, the balance is a one-time grant that never resets.
   <Expandable title="properties">
-    <DynamicParamField body="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" required />
+    <DynamicParamField body="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" required>
+      The interval at which the balance resets (e.g., 'month', 'day', 'year').
+    </DynamicParamField>
 
-    <DynamicParamField body="interval_count" type="number" />
+    <DynamicParamField body="interval_count" type="number">
+      Number of intervals between resets. Defaults to 1 (e.g., interval_count: 2 with interval: 'month' resets every 2 months).
+    </DynamicParamField>
 
   </Expandable>
 </DynamicParamField>
 
 <DynamicParamField body="expires_at" type="number">
-  Unix timestamp (milliseconds) when the balance expires
+  Unix timestamp (milliseconds) when the balance expires. Mutually exclusive with reset.
 </DynamicParamField>
 
 <DynamicParamField body="granted_balance" type="number" />

apps/docs/mintlify/api-reference/balances/track.mdx

@@ -0,0 +1,481 @@
+---
+title: "Track Usage"
+openapi: "openapi POST /v1/balances.track"
+---
+
+import { DynamicParamField } from "/components/dynamic-param-field.jsx";
+import { DynamicResponseField } from "/components/dynamic-response-field.jsx";
+import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";
+
+<Note>
+  Track records usage events to decrement a customer's balance. Use this to meter feature consumption like API calls, messages sent, or credits used.
+</Note>
+
+### Common Use Cases
+
+<CodeGroup>
+
+```typescript Track single usage
+await autumn.balances.track({
+  customerId: "cus_123",
+  featureId: "ai_messages",
+  value: 1
+});
+```
+
+```typescript Track with idempotency
+await autumn.balances.track({
+  customerId: "cus_123",
+  featureId: "api_calls",
+  value: 1,
+  idempotencyKey: "request_abc123" // Prevents duplicate tracking on retry
+});
+```
+
+```typescript Credit balance (negative value)
+await autumn.balances.track({
+  customerId: "cus_123",
+  featureId: "seats",
+  value: -1 // Increases balance when removing a seat
+});
+```
+
+</CodeGroup>
+
+### Body Parameters
+
+<DynamicParamField body="customer_id" type="string" required>
+  The ID of the customer.
+</DynamicParamField>
+
+<DynamicParamField body="feature_id" type="string">
+  The ID of the feature to track usage for. Required if event_name is not provided.
+</DynamicParamField>
+
+<DynamicParamField body="entity_id" type="string">
+  The ID of the entity for entity-scoped balances (e.g., per-seat limits).
+</DynamicParamField>
+
+<DynamicParamField body="event_name" type="string">
+  Event name to track usage for. Use instead of feature_id when multiple features should be tracked from a single event.
+</DynamicParamField>
+
+<DynamicParamField body="value" type="number">
+  The amount of usage to record. Defaults to 1. Use negative values to credit balance (e.g., when removing a seat).
+</DynamicParamField>
+
+<DynamicParamField body="properties" type="object">
+  Additional properties to attach to this usage event.
+</DynamicParamField>
+
+<DynamicParamField body="idempotency_key" type="string">
+  Unique key to prevent duplicate event recording. Safely retry requests without creating duplicate usage.
+</DynamicParamField>
+
+
+### Response
+
+<DynamicResponseField name="customer_id" type="string">
+  The ID of the customer whose usage was tracked.
+</DynamicResponseField>
+
+<DynamicResponseField name="entity_id" type="string">
+  The ID of the entity, if entity-scoped tracking was performed.
+</DynamicResponseField>
+
+<DynamicResponseField name="event_name" type="string">
+  The event name that was tracked, if event_name was used instead of feature_id.
+</DynamicResponseField>
+
+<DynamicResponseField name="value" type="number">
+  The amount of usage that was recorded.
+</DynamicResponseField>
+
+<DynamicResponseField name="balance" type="object | null">
+  The updated balance for the tracked feature. Null if tracking by event_name that affects multiple features.
+  <Expandable title="properties">
+    <DynamicResponseField name="feature_id" type="string">
+      The feature ID this balance is for.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="feature" type="object">
+      The full feature object if expanded.
+      <Expandable title="properties">
+        <DynamicResponseField name="id" type="string" />
+
+        <DynamicResponseField name="name" type="string" />
+
+        <DynamicResponseField name="type" type="'boolean' | 'metered' | 'credit_system'" />
+
+        <DynamicResponseField name="consumable" type="boolean" />
+
+        <DynamicResponseField name="event_names" type="string[]" />
+
+        <DynamicResponseField name="credit_schema" type="object[]">
+          <Expandable title="properties">
+            <DynamicResponseField name="metered_feature_id" type="string" />
+
+            <DynamicResponseField name="credit_cost" type="number" />
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="display" type="object">
+          <Expandable title="properties">
+            <DynamicResponseField name="singular" type="string | null" />
+
+            <DynamicResponseField name="plural" type="string | null" />
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="archived" type="boolean" />
+
+      </Expandable>
+    </DynamicResponseField>
+
+    <DynamicResponseField name="granted" type="number">
+      Total balance granted (included + prepaid).
+    </DynamicResponseField>
+
+    <DynamicResponseField name="remaining" type="number">
+      Remaining balance available for use.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="usage" type="number">
+      Total usage consumed in the current period.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="unlimited" type="boolean">
+      Whether this feature has unlimited usage.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="overage_allowed" type="boolean">
+      Whether usage beyond the granted balance is allowed (with overage charges).
+    </DynamicResponseField>
+
+    <DynamicResponseField name="max_purchase" type="number | null">
+      Maximum quantity that can be purchased as a top-up, or null for unlimited.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="next_reset_at" type="number | null">
+      Timestamp when the balance will reset, or null for no reset.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="breakdown" type="object[]">
+      Detailed breakdown of balance sources when stacking multiple plans or grants.
+      <Expandable title="properties">
+        <DynamicResponseField name="id" type="string">
+          The unique identifier for this balance breakdown.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="plan_id" type="string | null">
+          The plan ID this balance originates from, or null for standalone balances.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="included_grant" type="number">
+          Amount granted from the plan's included usage.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="prepaid_grant" type="number">
+          Amount granted from prepaid purchases or top-ups.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="remaining" type="number">
+          Remaining balance available for use.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="usage" type="number">
+          Amount consumed in the current period.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="unlimited" type="boolean">
+          Whether this balance has unlimited usage.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="reset" type="object | null">
+          Reset configuration for this balance, or null if no reset.
+          <Expandable title="properties">
+            <DynamicResponseField name="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
+              The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="interval_count" type="number">
+              Number of intervals between resets (eg. 2 for bi-monthly).
+            </DynamicResponseField>
+
+            <DynamicResponseField name="resets_at" type="number | null">
+              Timestamp when the balance will next reset.
+            </DynamicResponseField>
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="price" type="object | null">
+          Pricing configuration if this balance has usage-based pricing.
+          <Expandable title="properties">
+            <DynamicResponseField name="amount" type="number">
+              The per-unit price amount.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="tiers" type="object[]">
+              Tiered pricing configuration if applicable.
+              <Expandable title="properties">
+                <DynamicResponseField name="to" type="number" />
+
+                <DynamicResponseField name="amount" type="number" />
+
+              </Expandable>
+            </DynamicResponseField>
+
+            <DynamicResponseField name="billing_units" type="number">
+              The number of units per billing increment (eg. $9 / 250 units).
+            </DynamicResponseField>
+
+            <DynamicResponseField name="billing_method" type="'prepaid' | 'usage_based'">
+              Whether usage is prepaid or billed pay-per-use.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="max_purchase" type="number | null">
+              Maximum quantity that can be purchased, or null for unlimited.
+            </DynamicResponseField>
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="expires_at" type="number | null">
+          Timestamp when this balance expires, or null for no expiration.
+        </DynamicResponseField>
+
+      </Expandable>
+    </DynamicResponseField>
+
+    <DynamicResponseField name="rollovers" type="object[]">
+      Rollover balances carried over from previous periods.
+      <Expandable title="properties">
+        <DynamicResponseField name="balance" type="number">
+          Amount of balance rolled over from a previous period.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="expires_at" type="number">
+          Timestamp when the rollover balance expires.
+        </DynamicResponseField>
+
+      </Expandable>
+    </DynamicResponseField>
+
+  </Expandable>
+</DynamicResponseField>
+
+<DynamicResponseField name="balances.{key}" type="object">
+  Map of feature_id to updated balance when tracking by event_name affects multiple features.
+  <Expandable title="properties">
+    <DynamicResponseField name="feature_id" type="string">
+      The feature ID this balance is for.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="feature" type="object">
+      The full feature object if expanded.
+      <Expandable title="properties">
+        <DynamicResponseField name="id" type="string" />
+
+        <DynamicResponseField name="name" type="string" />
+
+        <DynamicResponseField name="type" type="'boolean' | 'metered' | 'credit_system'" />
+
+        <DynamicResponseField name="consumable" type="boolean" />
+
+        <DynamicResponseField name="event_names" type="string[]" />
+
+        <DynamicResponseField name="credit_schema" type="object[]">
+          <Expandable title="properties">
+            <DynamicResponseField name="metered_feature_id" type="string" />
+
+            <DynamicResponseField name="credit_cost" type="number" />
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="display" type="object">
+          <Expandable title="properties">
+            <DynamicResponseField name="singular" type="string | null" />
+
+            <DynamicResponseField name="plural" type="string | null" />
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="archived" type="boolean" />
+
+      </Expandable>
+    </DynamicResponseField>
+
+    <DynamicResponseField name="granted" type="number">
+      Total balance granted (included + prepaid).
+    </DynamicResponseField>
+
+    <DynamicResponseField name="remaining" type="number">
+      Remaining balance available for use.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="usage" type="number">
+      Total usage consumed in the current period.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="unlimited" type="boolean">
+      Whether this feature has unlimited usage.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="overage_allowed" type="boolean">
+      Whether usage beyond the granted balance is allowed (with overage charges).
+    </DynamicResponseField>
+
+    <DynamicResponseField name="max_purchase" type="number | null">
+      Maximum quantity that can be purchased as a top-up, or null for unlimited.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="next_reset_at" type="number | null">
+      Timestamp when the balance will reset, or null for no reset.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="breakdown" type="object[]">
+      Detailed breakdown of balance sources when stacking multiple plans or grants.
+      <Expandable title="properties">
+        <DynamicResponseField name="id" type="string">
+          The unique identifier for this balance breakdown.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="plan_id" type="string | null">
+          The plan ID this balance originates from, or null for standalone balances.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="included_grant" type="number">
+          Amount granted from the plan's included usage.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="prepaid_grant" type="number">
+          Amount granted from prepaid purchases or top-ups.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="remaining" type="number">
+          Remaining balance available for use.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="usage" type="number">
+          Amount consumed in the current period.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="unlimited" type="boolean">
+          Whether this balance has unlimited usage.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="reset" type="object | null">
+          Reset configuration for this balance, or null if no reset.
+          <Expandable title="properties">
+            <DynamicResponseField name="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
+              The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="interval_count" type="number">
+              Number of intervals between resets (eg. 2 for bi-monthly).
+            </DynamicResponseField>
+
+            <DynamicResponseField name="resets_at" type="number | null">
+              Timestamp when the balance will next reset.
+            </DynamicResponseField>
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="price" type="object | null">
+          Pricing configuration if this balance has usage-based pricing.
+          <Expandable title="properties">
+            <DynamicResponseField name="amount" type="number">
+              The per-unit price amount.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="tiers" type="object[]">
+              Tiered pricing configuration if applicable.
+              <Expandable title="properties">
+                <DynamicResponseField name="to" type="number" />
+
+                <DynamicResponseField name="amount" type="number" />
+
+              </Expandable>
+            </DynamicResponseField>
+
+            <DynamicResponseField name="billing_units" type="number">
+              The number of units per billing increment (eg. $9 / 250 units).
+            </DynamicResponseField>
+
+            <DynamicResponseField name="billing_method" type="'prepaid' | 'usage_based'">
+              Whether usage is prepaid or billed pay-per-use.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="max_purchase" type="number | null">
+              Maximum quantity that can be purchased, or null for unlimited.
+            </DynamicResponseField>
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="expires_at" type="number | null">
+          Timestamp when this balance expires, or null for no expiration.
+        </DynamicResponseField>
+
+      </Expandable>
+    </DynamicResponseField>
+
+    <DynamicResponseField name="rollovers" type="object[]">
+      Rollover balances carried over from previous periods.
+      <Expandable title="properties">
+        <DynamicResponseField name="balance" type="number">
+          Amount of balance rolled over from a previous period.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="expires_at" type="number">
+          Timestamp when the rollover balance expires.
+        </DynamicResponseField>
+
+      </Expandable>
+    </DynamicResponseField>
+
+  </Expandable>
+</DynamicResponseField>
+
+
+<ResponseExample>
+```json 200
+{
+  "customer_id": "cus_123",
+  "value": 1,
+  "balance": {
+    "feature_id": "messages",
+    "granted": 100,
+    "remaining": 72,
+    "usage": 28,
+    "unlimited": false,
+    "overage_allowed": false,
+    "max_purchase": null,
+    "next_reset_at": 1773851121437,
+    "breakdown": [
+      {
+        "id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
+        "plan_id": "pro_plan",
+        "included_grant": 100,
+        "prepaid_grant": 0,
+        "remaining": 72,
+        "usage": 28,
+        "unlimited": false,
+        "reset": {
+          "interval": "month",
+          "resets_at": 1773851121437
+        },
+        "price": null,
+        "expires_at": null
+      }
+    ]
+  }
+}
+```
+</ResponseExample>

apps/docs/mintlify/api-reference/balances/updateBalance.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Balances Update"
+title: "Update Balance"
 openapi: "openapi POST /v1/balances.update"
 ---
 
@@ -13,32 +13,26 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
   The ID of the customer.
 </DynamicParamField>
 
-<DynamicParamField body="entity_id" type="string">
-  The ID of the entity to update balance for (if using entity balances).
-</DynamicParamField>
-
 <DynamicParamField body="feature_id" type="string" required>
-  The ID of the feature to update balance for.
+  The ID of the feature.
 </DynamicParamField>
 
-<DynamicParamField body="current_balance" type="number">
-  The new balance value to set.
+<DynamicParamField body="entity_id" type="string">
+  The ID of the entity for entity-scoped balances (e.g., per-seat limits).
+</DynamicParamField>
+
+<DynamicParamField body="remaining" type="number">
+  Set the remaining balance to this exact value. Cannot be combined with add_to_balance.
+</DynamicParamField>
+
+<DynamicParamField body="add_to_balance" type="number">
+  Add this amount to the current balance. Use negative values to subtract. Cannot be combined with current_balance.
 </DynamicParamField>
 
 <DynamicParamField body="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
-  The interval to update balance for.
+  Target a specific balance by its reset interval. Use when the customer has multiple balances for the same feature with different reset intervals.
 </DynamicParamField>
 
-<DynamicParamField body="granted_balance" type="number" />
-
-<DynamicParamField body="usage" type="number" />
-
-<DynamicParamField body="customer_entitlement_id" type="string" />
-
-<DynamicParamField body="next_reset_at" type="number" />
-
-<DynamicParamField body="add_to_balance" type="number" />
-
 
 ### Response
 

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

@@ -1,6 +1,6 @@
 ---
 title: "Attach"
-openapi: "openapi POST /v1/attach"
+openapi: "openapi POST /v1/billing.attach"
 ---
 
 import { DynamicParamField } from "/components/dynamic-param-field.jsx";
@@ -9,111 +9,138 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
 
 ### Body Parameters
 
-<DynamicParamField body="entity_id" type="string | null" />
-
-<DynamicParamField body="entity_data" type="object">
-  <Expandable title="properties">
-    <DynamicParamField body="feature_id" type="string" required>
-      The feature ID that this entity is associated with
+<DynamicParamField body="customer_id" type="string" required>
+  The ID of the customer to attach the plan to.
 </DynamicParamField>
 
-    <DynamicParamField body="name" type="string">
-      Name of the entity
+<DynamicParamField body="entity_id" type="string | null">
+  The ID of the entity to attach the plan to.
 </DynamicParamField>
 
-  </Expandable>
-</DynamicParamField>
-
-<DynamicParamField body="options" type="object[] | null">
+<DynamicParamField body="feature_quantities" type="object[] | null">
+  If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan.
   <Expandable title="properties">
     <DynamicParamField body="feature_id" type="string" required />
 
     <DynamicParamField body="quantity" type="number" />
 
-    <DynamicParamField body="reset_after_trial_end" type="boolean" />
+    <DynamicParamField body="adjustable" type="boolean" />
 
   </Expandable>
 </DynamicParamField>
 
-<DynamicParamField body="version" type="number" />
+<DynamicParamField body="version" type="number">
+  The version of the plan to attach.
+</DynamicParamField>
 
 <DynamicParamField body="free_trial" type="object | null">
   <Expandable title="properties">
-    <DynamicParamField body="length" type="number" required />
+    <DynamicParamField body="duration_length" type="number" required />
 
-    <DynamicParamField body="duration" type="'day' | 'month' | 'year'" required />
+    <DynamicParamField body="duration_type" type="'day' | 'month' | 'year'" />
 
     <DynamicParamField body="card_required" type="boolean" />
 
   </Expandable>
 </DynamicParamField>
 
+<DynamicParamField body="customize" type="object">
+  Customize the plan to attach. Can either override the price of the plan, the items in the plan, or both.
+  <Expandable title="properties">
+    <DynamicParamField body="price" type="object | null">
+      <Expandable title="properties">
+        <DynamicParamField body="amount" type="number" required />
+
+        <DynamicParamField body="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" required />
+
+        <DynamicParamField body="interval_count" type="number" />
+
+      </Expandable>
+    </DynamicParamField>
+
     <DynamicParamField body="items" type="object[]">
       <Expandable title="properties">
-    <DynamicParamField body="type" type="'feature' | 'priced_feature' | 'price'">
-      The type of the product item.
-    </DynamicParamField>
+        <DynamicParamField body="feature_id" type="string" required />
 
-    <DynamicParamField body="feature_id" type="string | null">
-      The feature ID of the product item. Should be null for fixed price items.
-    </DynamicParamField>
+        <DynamicParamField body="included" type="number" />
 
-    <DynamicParamField body="included_usage" type="number | null">
-      The amount of usage included for this feature (per interval).
-    </DynamicParamField>
+        <DynamicParamField body="unlimited" type="boolean" />
 
-    <DynamicParamField body="interval" type="'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
-      The reset or billing interval of the product item. If null, feature will have no reset date, and if there's a price, it will be billed one-off.
-    </DynamicParamField>
-
-    <DynamicParamField body="interval_count" type="number | null">
-      Interval count of the feature.
-    </DynamicParamField>
-
-    <DynamicParamField body="entity_feature_id" type="string | null">
-      The feature ID of the entity (like seats) to track sub-balances for.
-    </DynamicParamField>
-
-    <DynamicParamField body="usage_model" type="'prepaid' | 'pay_per_use'">
-      Whether the feature should be prepaid upfront or billed for how much they use end of billing period.
-    </DynamicParamField>
-
-    <DynamicParamField body="price" type="number | null">
-      The price of the product item. Should be null if tiered pricing is set.
-    </DynamicParamField>
-
-    <DynamicParamField body="tiers" type="object[] | null">
-      Tiered pricing for the product item. Not applicable for fixed price items.
+        <DynamicParamField body="reset" type="object">
           <Expandable title="properties">
-        <DynamicParamField body="to" type="number" required>
-          The maximum amount of usage for this tier.
+            <DynamicParamField body="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" required />
+
+            <DynamicParamField body="interval_count" type="number" />
+
+          </Expandable>
         </DynamicParamField>
 
-        <DynamicParamField body="amount" type="number" required>
-          The price of the product item for this tier.
+        <DynamicParamField body="price" type="object">
+          <Expandable title="properties">
+            <DynamicParamField body="amount" type="number" />
+
+            <DynamicParamField body="tiers" type="object[]">
+              <Expandable title="properties">
+                <DynamicParamField body="to" type="number" required />
+
+                <DynamicParamField body="amount" type="number" required />
+
+              </Expandable>
+            </DynamicParamField>
+
+            <DynamicParamField body="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" required />
+
+            <DynamicParamField body="interval_count" type="number" />
+
+            <DynamicParamField body="billing_units" type="number" />
+
+            <DynamicParamField body="billing_method" type="'prepaid' | 'usage_based'" required />
+
+            <DynamicParamField body="max_purchase" type="number" />
+
+          </Expandable>
+        </DynamicParamField>
+
+        <DynamicParamField body="proration" type="object">
+          <Expandable title="properties">
+            <DynamicParamField body="on_increase" type="'bill_immediately' | 'prorate_immediately' | 'prorate_next_cycle' | 'bill_next_cycle'" required />
+
+            <DynamicParamField body="on_decrease" type="'prorate' | 'prorate_immediately' | 'prorate_next_cycle' | 'none' | 'no_prorations'" required />
+
+          </Expandable>
+        </DynamicParamField>
+
+        <DynamicParamField body="rollover" type="object">
+          <Expandable title="properties">
+            <DynamicParamField body="max" type="number" />
+
+            <DynamicParamField body="expiry_duration_type" type="'month' | 'forever'" required />
+
+            <DynamicParamField body="expiry_duration_length" type="number" />
+
+          </Expandable>
         </DynamicParamField>
 
       </Expandable>
     </DynamicParamField>
 
-    <DynamicParamField body="billing_units" type="number | null">
-      The billing units of the product item (eg $1 for 30 credits).
+  </Expandable>
 </DynamicParamField>
 
-    <DynamicParamField body="reset_usage_when_enabled" type="boolean | null">
-      Whether the usage should be reset when the product is enabled.
-    </DynamicParamField>
+<DynamicParamField body="plan_id" type="string" required />
+
+<DynamicParamField body="invoice_mode" type="object">
+  <Expandable title="properties">
+    <DynamicParamField body="enabled" type="boolean" required />
+
+    <DynamicParamField body="enable_plan_immediately" type="boolean" />
+
+    <DynamicParamField body="finalize" type="boolean" />
 
   </Expandable>
 </DynamicParamField>
 
-<DynamicParamField body="product_id" type="string" required />
-
-<DynamicParamField body="invoice" type="boolean" />
-
-<DynamicParamField body="enable_product_immediately" type="boolean" />
-
-<DynamicParamField body="finalize_invoice" type="boolean" />
+<DynamicParamField body="discounts" type="object[]" />
 
 <DynamicParamField body="redirect_mode" type="'always' | 'if_required' | 'never'" />
 
@@ -125,8 +152,6 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
 
 <DynamicParamField body="billing_behavior" type="'prorate_immediately' | 'next_cycle_only'" />
 
-<DynamicParamField body="adjustable_quantity" type="boolean" />
-
 
 ### Response
 
@@ -159,3 +184,13 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
 
   </Expandable>
 </DynamicResponseField>
+
+
+<ResponseExample>
+```json 200
+{
+  "customer_id": "cus_123",
+  "payment_url": null
+}
+```
+</ResponseExample>

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

@@ -1,5 +1,5 @@
 ---
-title: "Billing Attach"
+title: "Attach"
 openapi: "openapi POST /v1/billing.attach"
 ---
 
@@ -7,17 +7,66 @@ import { DynamicParamField } from "/components/dynamic-param-field.jsx";
 import { DynamicResponseField } from "/components/dynamic-response-field.jsx";
 import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";
 
+<Note>
+  The attach endpoint subscribes a customer to a plan. It handles new subscriptions, upgrades, and downgrades automatically. For modifying an existing subscription (like changing quantities or canceling), use [update](/api-reference/billing/billingUpdate) instead.
+</Note>
+
+### Common Use Cases
+
+<CodeGroup>
+
+```typescript Subscribe to a plan
+const response = await autumn.billing.attach({
+  customerId: "cus_123",
+  planId: "pro_plan"
+});
+
+if (response.paymentUrl) {
+  // Redirect customer to checkout
+  window.location.href = response.paymentUrl;
+}
+```
+
+```typescript Custom pricing
+const response = await autumn.billing.attach({
+  customerId: "cus_123",
+  planId: "enterprise_plan",
+  customize: {
+    price: {
+      amount: 99900, // $999.00
+      interval: "month"
+    }
+  }
+});
+```
+
+```typescript Attach plan with prepaid quantities
+const response = await autumn.billing.attach({
+  customerId: "cus_123",
+  planId: "team_plan",
+  featureQuantities: [
+    { featureId: "seats", quantity: 5 }
+  ]
+});
+```
+
+</CodeGroup>
+
 ### Body Parameters
 
 <DynamicParamField body="customer_id" type="string" required>
   The ID of the customer to attach the plan to.
 </DynamicParamField>
 
-<DynamicParamField body="entity_id" type="string | null">
+<DynamicParamField body="entity_id" type="string">
   The ID of the entity to attach the plan to.
 </DynamicParamField>
 
-<DynamicParamField body="feature_quantities" type="object[] | null">
+<DynamicParamField body="plan_id" type="string" required>
+  The ID of the plan.
+</DynamicParamField>
+
+<DynamicParamField body="feature_quantities" type="object[]">
   If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan.
   <Expandable title="properties">
     <DynamicParamField body="feature_id" type="string" required />
@@ -34,6 +83,7 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
 </DynamicParamField>
 
 <DynamicParamField body="free_trial" type="object | null">
+  Override the plan's default free trial. Pass an object to set a custom trial, or null to remove the trial entirely.
   <Expandable title="properties">
     <DynamicParamField body="duration_length" type="number" required />
 
@@ -127,60 +177,115 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
   </Expandable>
 </DynamicParamField>
 
-<DynamicParamField body="plan_id" type="string" required />
-
 <DynamicParamField body="invoice_mode" type="object">
+  Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. This uses Stripe's send_invoice collection method.
   <Expandable title="properties">
-    <DynamicParamField body="enabled" type="boolean" required />
+    <DynamicParamField body="enabled" type="boolean" required>
+      When true, creates an invoice and sends it to the customer instead of charging their card immediately. Uses Stripe's send_invoice collection method.
+    </DynamicParamField>
 
-    <DynamicParamField body="enable_plan_immediately" type="boolean" />
+    <DynamicParamField body="enable_plan_immediately" type="boolean">
+      If true, enables the plan immediately even though the invoice is not paid yet.
+    </DynamicParamField>
 
-    <DynamicParamField body="finalize" type="boolean" />
+    <DynamicParamField body="finalize" type="boolean">
+      If true, finalizes the invoice so it can be sent to the customer. If false, keeps it as a draft for manual review.
+    </DynamicParamField>
 
   </Expandable>
 </DynamicParamField>
 
-<DynamicParamField body="discounts" type="object[]" />
+<DynamicParamField body="billing_behavior" type="'prorate_immediately' | 'next_cycle_only'">
+  How to handle billing when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'next_cycle_only' skips creating any charges and applies the change at the next billing cycle.
+</DynamicParamField>
 
-<DynamicParamField body="redirect_mode" type="'always' | 'if_required' | 'never'" />
+<DynamicParamField body="discounts" type="object[]">
+  List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code.
+  <Expandable title="properties">
+    <DynamicParamField body="reward_id" type="string">
+      The ID of the reward to apply as a discount.
+    </DynamicParamField>
 
-<DynamicParamField body="success_url" type="string" />
+    <DynamicParamField body="promotion_code" type="string">
+      The promotion code to apply as a discount.
+    </DynamicParamField>
 
-<DynamicParamField body="new_billing_subscription" type="boolean" />
+  </Expandable>
+</DynamicParamField>
 
-<DynamicParamField body="plan_schedule" type="'immediate' | 'end_of_cycle'" />
+<DynamicParamField body="success_url" type="string">
+  URL to redirect to after successful checkout.
+</DynamicParamField>
 
-<DynamicParamField body="billing_behavior" type="'prorate_immediately' | 'next_cycle_only'" />
+<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.
+</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.
+</DynamicParamField>
 
 
 ### Response
 
-<DynamicResponseField name="customer_id" type="string" />
+<DynamicResponseField name="customer_id" type="string">
+  The ID of the customer.
+</DynamicResponseField>
 
-<DynamicResponseField name="entity_id" type="string" />
+<DynamicResponseField name="entity_id" type="string">
+  The ID of the entity, if the plan was attached to an entity.
+</DynamicResponseField>
 
 <DynamicResponseField name="invoice" type="object">
+  Invoice details if an invoice was created. Only present when a charge was made.
   <Expandable title="properties">
-    <DynamicResponseField name="status" type="string | null" />
+    <DynamicResponseField name="status" type="string | null">
+      The status of the invoice (e.g., 'paid', 'open', 'draft').
+    </DynamicResponseField>
 
-    <DynamicResponseField name="stripe_id" type="string" />
+    <DynamicResponseField name="stripe_id" type="string">
+      The Stripe invoice ID.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="total" type="number" />
+    <DynamicResponseField name="total" type="number">
+      The total amount of the invoice in cents.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="currency" type="string" />
+    <DynamicResponseField name="currency" type="string">
+      The three-letter ISO currency code (e.g., 'usd').
+    </DynamicResponseField>
 
-    <DynamicResponseField name="hosted_invoice_url" type="string | null" />
+    <DynamicResponseField name="hosted_invoice_url" type="string | null">
+      URL to the hosted invoice page where the customer can view and pay the invoice.
+    </DynamicResponseField>
 
   </Expandable>
 </DynamicResponseField>
 
-<DynamicResponseField name="payment_url" type="string | null" />
+<DynamicResponseField name="payment_url" type="string | null">
+  URL to redirect the customer to complete payment. Null if no payment action is required.
+</DynamicResponseField>
 
 <DynamicResponseField name="required_action" type="object">
+  Details about any action required to complete the payment. Present when the payment could not be processed automatically.
   <Expandable title="properties">
-    <DynamicResponseField name="code" type="'3ds_required' | 'payment_method_required' | 'payment_failed'" />
+    <DynamicResponseField name="code" type="'3ds_required' | 'payment_method_required' | 'payment_failed'">
+      The type of action required to complete the payment.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="reason" type="string" />
+    <DynamicResponseField name="reason" type="string">
+      A human-readable explanation of why this action is required.
+    </DynamicResponseField>
 
   </Expandable>
 </DynamicResponseField>
+
+
+<ResponseExample>
+```json 200
+{
+  "customer_id": "cus_123",
+  "payment_url": "https://checkout.stripe.com/..."
+}
+```
+</ResponseExample>

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

@@ -1,5 +1,5 @@
 ---
-title: "Billing Update"
+title: "Update Subscription"
 openapi: "openapi POST /v1/billing.update"
 ---
 
@@ -7,17 +7,55 @@ import { DynamicParamField } from "/components/dynamic-param-field.jsx";
 import { DynamicResponseField } from "/components/dynamic-response-field.jsx";
 import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";
 
+<Note>
+  The update endpoint modifies an existing subscription. Use this to change prepaid quantities, cancel subscriptions, or modify plan configuration. For subscribing to a new plan, use [attach](/api-reference/billing/billingAttach) instead.
+</Note>
+
+### Common Use Cases
+
+<CodeGroup>
+
+```typescript Update prepaid quantity
+const response = await autumn.billing.update({
+  customerId: "cus_123",
+  planId: "pro_plan",
+  featureQuantities: [{ featureId: "seats", quantity: 10 }]
+});
+```
+
+```typescript Cancel at end of cycle
+const response = await autumn.billing.update({
+  customerId: "cus_123",
+  planId: "pro_plan",
+  cancelAction: "cancel_end_of_cycle"
+});
+```
+
+```typescript Uncancel subscription
+const response = await autumn.billing.update({
+  customerId: "cus_123",
+  planId: "pro_plan",
+  cancelAction: "uncancel"
+});
+```
+
+</CodeGroup>
+
 ### Body Parameters
 
 <DynamicParamField body="customer_id" type="string" required>
   The ID of the customer to attach the plan to.
 </DynamicParamField>
 
-<DynamicParamField body="entity_id" type="string | null">
+<DynamicParamField body="entity_id" type="string">
   The ID of the entity to attach the plan to.
 </DynamicParamField>
 
-<DynamicParamField body="feature_quantities" type="object[] | null">
+<DynamicParamField body="plan_id" type="string" required>
+  The ID of the plan.
+</DynamicParamField>
+
+<DynamicParamField body="feature_quantities" type="object[]">
   If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan.
   <Expandable title="properties">
     <DynamicParamField body="feature_id" type="string" required />
@@ -34,6 +72,7 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
 </DynamicParamField>
 
 <DynamicParamField body="free_trial" type="object | null">
+  Override the plan's default free trial. Pass an object to set a custom trial, or null to remove the trial entirely.
   <Expandable title="properties">
     <DynamicParamField body="duration_length" type="number" required />
 
@@ -127,52 +166,100 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
   </Expandable>
 </DynamicParamField>
 
-<DynamicParamField body="plan_id" type="string" />
-
 <DynamicParamField body="invoice_mode" type="object">
+  Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. This uses Stripe's send_invoice collection method.
   <Expandable title="properties">
-    <DynamicParamField body="enabled" type="boolean" required />
+    <DynamicParamField body="enabled" type="boolean" required>
+      When true, creates an invoice and sends it to the customer instead of charging their card immediately. Uses Stripe's send_invoice collection method.
+    </DynamicParamField>
 
-    <DynamicParamField body="enable_plan_immediately" type="boolean" />
+    <DynamicParamField body="enable_plan_immediately" type="boolean">
+      If true, enables the plan immediately even though the invoice is not paid yet.
+    </DynamicParamField>
 
-    <DynamicParamField body="finalize" type="boolean" />
+    <DynamicParamField body="finalize" type="boolean">
+      If true, finalizes the invoice so it can be sent to the customer. If false, keeps it as a draft for manual review.
+    </DynamicParamField>
 
   </Expandable>
 </DynamicParamField>
 
-<DynamicParamField body="cancel_action" type="'cancel_immediately' | 'cancel_end_of_cycle' | 'uncancel'" />
+<DynamicParamField body="billing_behavior" type="'prorate_immediately' | 'next_cycle_only'">
+  How to handle billing when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'next_cycle_only' skips creating any charges and applies the change at the next billing cycle.
+</DynamicParamField>
 
-<DynamicParamField body="billing_behavior" type="'prorate_immediately' | 'next_cycle_only'" />
+<DynamicParamField body="cancel_action" type="'cancel_immediately' | 'cancel_end_of_cycle' | 'uncancel'">
+  Action to perform for cancellation. 'cancel_immediately' cancels now with prorated refund, 'cancel_end_of_cycle' cancels at period end, 'uncancel' reverses a pending cancellation.
+</DynamicParamField>
 
 
 ### Response
 
-<DynamicResponseField name="customer_id" type="string" />
+<DynamicResponseField name="customer_id" type="string">
+  The ID of the customer.
+</DynamicResponseField>
 
-<DynamicResponseField name="entity_id" type="string" />
+<DynamicResponseField name="entity_id" type="string">
+  The ID of the entity, if the plan was attached to an entity.
+</DynamicResponseField>
 
 <DynamicResponseField name="invoice" type="object">
+  Invoice details if an invoice was created. Only present when a charge was made.
   <Expandable title="properties">
-    <DynamicResponseField name="status" type="string | null" />
+    <DynamicResponseField name="status" type="string | null">
+      The status of the invoice (e.g., 'paid', 'open', 'draft').
+    </DynamicResponseField>
 
-    <DynamicResponseField name="stripe_id" type="string" />
+    <DynamicResponseField name="stripe_id" type="string">
+      The Stripe invoice ID.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="total" type="number" />
+    <DynamicResponseField name="total" type="number">
+      The total amount of the invoice in cents.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="currency" type="string" />
+    <DynamicResponseField name="currency" type="string">
+      The three-letter ISO currency code (e.g., 'usd').
+    </DynamicResponseField>
 
-    <DynamicResponseField name="hosted_invoice_url" type="string | null" />
+    <DynamicResponseField name="hosted_invoice_url" type="string | null">
+      URL to the hosted invoice page where the customer can view and pay the invoice.
+    </DynamicResponseField>
 
   </Expandable>
 </DynamicResponseField>
 
-<DynamicResponseField name="payment_url" type="string | null" />
+<DynamicResponseField name="payment_url" type="string | null">
+  URL to redirect the customer to complete payment. Null if no payment action is required.
+</DynamicResponseField>
 
 <DynamicResponseField name="required_action" type="object">
+  Details about any action required to complete the payment. Present when the payment could not be processed automatically.
   <Expandable title="properties">
-    <DynamicResponseField name="code" type="'3ds_required' | 'payment_method_required' | 'payment_failed'" />
+    <DynamicResponseField name="code" type="'3ds_required' | 'payment_method_required' | 'payment_failed'">
+      The type of action required to complete the payment.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="reason" type="string" />
+    <DynamicResponseField name="reason" type="string">
+      A human-readable explanation of why this action is required.
+    </DynamicResponseField>
 
   </Expandable>
 </DynamicResponseField>
+
+
+<ResponseExample>
+```json 200
+{
+  "customer_id": "cus_123",
+  "invoice": {
+    "status": "paid",
+    "stripe_id": "in_1234",
+    "total": 1500,
+    "currency": "usd",
+    "hosted_invoice_url": "https://invoice.stripe.com/..."
+  },
+  "payment_url": null
+}
+```
+</ResponseExample>

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

@@ -0,0 +1,43 @@
+---
+title: "Open Customer Portal"
+openapi: "openapi POST /v1/billing.open_customer_portal"
+---
+
+import { DynamicParamField } from "/components/dynamic-param-field.jsx";
+import { DynamicResponseField } from "/components/dynamic-response-field.jsx";
+import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";
+
+### Body Parameters
+
+<DynamicParamField body="customer_id" type="string" required>
+  The ID of the customer to open the billing portal for.
+</DynamicParamField>
+
+<DynamicParamField body="configuration_id" type="string">
+  Stripe billing portal configuration ID. Create configurations in your Stripe dashboard.
+</DynamicParamField>
+
+<DynamicParamField body="return_url" type="string">
+  URL to redirect to when back button is clicked in the billing portal
+</DynamicParamField>
+
+
+### Response
+
+<DynamicResponseField name="customer_id" type="string">
+  The ID of the billing portal session
+</DynamicResponseField>
+
+<DynamicResponseField name="url" type="string">
+  URL to the billing portal
+</DynamicResponseField>
+
+
+<ResponseExample>
+```json 200
+{
+  "customer_id": "cus_123",
+  "url": "https://billing.stripe.com/session/..."
+}
+```
+</ResponseExample>

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

@@ -0,0 +1,261 @@
+---
+title: "Preview Attach"
+openapi: "openapi POST /v1/billing.preview_attach"
+---
+
+import { DynamicParamField } from "/components/dynamic-param-field.jsx";
+import { DynamicResponseField } from "/components/dynamic-response-field.jsx";
+import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";
+
+### Body Parameters
+
+<DynamicParamField body="customer_id" type="string" required>
+  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.
+</DynamicParamField>
+
+<DynamicParamField body="plan_id" type="string" required>
+  The ID of the plan.
+</DynamicParamField>
+
+<DynamicParamField body="feature_quantities" type="object[]">
+  If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan.
+  <Expandable title="properties">
+    <DynamicParamField body="feature_id" type="string" required />
+
+    <DynamicParamField body="quantity" type="number" />
+
+    <DynamicParamField body="adjustable" type="boolean" />
+
+  </Expandable>
+</DynamicParamField>
+
+<DynamicParamField body="version" type="number">
+  The version of the plan to attach.
+</DynamicParamField>
+
+<DynamicParamField body="free_trial" type="object | null">
+  Override the plan's default free trial. Pass an object to set a custom trial, or null to remove the trial entirely.
+  <Expandable title="properties">
+    <DynamicParamField body="duration_length" type="number" required />
+
+    <DynamicParamField body="duration_type" type="'day' | 'month' | 'year'" />
+
+    <DynamicParamField body="card_required" type="boolean" />
+
+  </Expandable>
+</DynamicParamField>
+
+<DynamicParamField body="customize" type="object">
+  Customize the plan to attach. Can either override the price of the plan, the items in the plan, or both.
+  <Expandable title="properties">
+    <DynamicParamField body="price" type="object | null">
+      <Expandable title="properties">
+        <DynamicParamField body="amount" type="number" required />
+
+        <DynamicParamField body="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" required />
+
+        <DynamicParamField body="interval_count" type="number" />
+
+      </Expandable>
+    </DynamicParamField>
+
+    <DynamicParamField body="items" type="object[]">
+      <Expandable title="properties">
+        <DynamicParamField body="feature_id" type="string" required />
+
+        <DynamicParamField body="included" type="number" />
+
+        <DynamicParamField body="unlimited" type="boolean" />
+
+        <DynamicParamField body="reset" type="object">
+          <Expandable title="properties">
+            <DynamicParamField body="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" required />
+
+            <DynamicParamField body="interval_count" type="number" />
+
+          </Expandable>
+        </DynamicParamField>
+
+        <DynamicParamField body="price" type="object">
+          <Expandable title="properties">
+            <DynamicParamField body="amount" type="number" />
+
+            <DynamicParamField body="tiers" type="object[]">
+              <Expandable title="properties">
+                <DynamicParamField body="to" type="number" required />
+
+                <DynamicParamField body="amount" type="number" required />
+
+              </Expandable>
+            </DynamicParamField>
+
+            <DynamicParamField body="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" required />
+
+            <DynamicParamField body="interval_count" type="number" />
+
+            <DynamicParamField body="billing_units" type="number" />
+
+            <DynamicParamField body="billing_method" type="'prepaid' | 'usage_based'" required />
+
+            <DynamicParamField body="max_purchase" type="number" />
+
+          </Expandable>
+        </DynamicParamField>
+
+        <DynamicParamField body="proration" type="object">
+          <Expandable title="properties">
+            <DynamicParamField body="on_increase" type="'bill_immediately' | 'prorate_immediately' | 'prorate_next_cycle' | 'bill_next_cycle'" required />
+
+            <DynamicParamField body="on_decrease" type="'prorate' | 'prorate_immediately' | 'prorate_next_cycle' | 'none' | 'no_prorations'" required />
+
+          </Expandable>
+        </DynamicParamField>
+
+        <DynamicParamField body="rollover" type="object">
+          <Expandable title="properties">
+            <DynamicParamField body="max" type="number" />
+
+            <DynamicParamField body="expiry_duration_type" type="'month' | 'forever'" required />
+
+            <DynamicParamField body="expiry_duration_length" type="number" />
+
+          </Expandable>
+        </DynamicParamField>
+
+      </Expandable>
+    </DynamicParamField>
+
+  </Expandable>
+</DynamicParamField>
+
+<DynamicParamField body="invoice_mode" type="object">
+  Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. This uses Stripe's send_invoice collection method.
+  <Expandable title="properties">
+    <DynamicParamField body="enabled" type="boolean" required>
+      When true, creates an invoice and sends it to the customer instead of charging their card immediately. Uses Stripe's send_invoice collection method.
+    </DynamicParamField>
+
+    <DynamicParamField body="enable_plan_immediately" type="boolean">
+      If true, enables the plan immediately even though the invoice is not paid yet.
+    </DynamicParamField>
+
+    <DynamicParamField body="finalize" type="boolean">
+      If true, finalizes the invoice so it can be sent to the customer. If false, keeps it as a draft for manual review.
+    </DynamicParamField>
+
+  </Expandable>
+</DynamicParamField>
+
+<DynamicParamField body="billing_behavior" type="'prorate_immediately' | 'next_cycle_only'">
+  How to handle billing when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'next_cycle_only' skips creating any charges and applies the change at the next billing cycle.
+</DynamicParamField>
+
+<DynamicParamField body="discounts" type="object[]">
+  List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code.
+  <Expandable title="properties">
+    <DynamicParamField body="reward_id" type="string">
+      The ID of the reward to apply as a discount.
+    </DynamicParamField>
+
+    <DynamicParamField body="promotion_code" type="string">
+      The promotion code to apply as a discount.
+    </DynamicParamField>
+
+  </Expandable>
+</DynamicParamField>
+
+<DynamicParamField body="success_url" type="string">
+  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.
+</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.
+</DynamicParamField>
+
+
+### Response
+
+<DynamicResponseField name="customer_id" type="string">
+  The ID of the customer.
+</DynamicResponseField>
+
+<DynamicResponseField name="line_items" type="object[]">
+  List of line items for the current billing period.
+  <Expandable title="properties">
+    <DynamicResponseField name="title" type="string">
+      The title of the line item.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="description" type="string">
+      A detailed description of the line item.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="amount" type="number">
+      The amount in cents for this line item.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="discounts" type="object[]">
+      List of discounts applied to this line item.
+      <Expandable title="properties">
+        <DynamicResponseField name="amountOff" type="number" />
+
+        <DynamicResponseField name="percentOff" type="number" />
+
+        <DynamicResponseField name="stripeCouponId" type="string" />
+
+        <DynamicResponseField name="couponName" type="string" />
+
+      </Expandable>
+    </DynamicResponseField>
+
+  </Expandable>
+</DynamicResponseField>
+
+<DynamicResponseField name="total" type="number">
+  The total amount in cents for the current billing period.
+</DynamicResponseField>
+
+<DynamicResponseField name="currency" type="string">
+  The three-letter ISO currency code (e.g., 'usd').
+</DynamicResponseField>
+
+<DynamicResponseField name="next_cycle" type="object">
+  Preview of the next billing cycle, if applicable. This shows what the customer will be charged in subsequent cycles.
+  <Expandable title="properties">
+    <DynamicResponseField name="starts_at" type="number">
+      Unix timestamp (milliseconds) when the next billing cycle starts.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="total" type="number">
+      The total amount in cents for the next cycle.
+    </DynamicResponseField>
+
+  </Expandable>
+</DynamicResponseField>
+
+
+<ResponseExample>
+```json 200
+{
+  "customerId": "charles",
+  "lineItems": [
+    {
+      "title": "Pro seed",
+      "description": "Pro seed - Base Price (from 18 Feb 2026 to 18 Mar 2026)",
+      "amount": 20,
+      "discounts": []
+    }
+  ],
+  "total": 20,
+  "currency": "usd"
+}
+```
+</ResponseExample>

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

@@ -1,5 +1,5 @@
 ---
-title: "Billing Preview Update"
+title: "Preview Update"
 openapi: "openapi POST /v1/billing.preview_update"
 ---
 
@@ -13,11 +13,15 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
   The ID of the customer to attach the plan to.
 </DynamicParamField>
 
-<DynamicParamField body="entity_id" type="string | null">
+<DynamicParamField body="entity_id" type="string">
   The ID of the entity to attach the plan to.
 </DynamicParamField>
 
-<DynamicParamField body="feature_quantities" type="object[] | null">
+<DynamicParamField body="plan_id" type="string" required>
+  The ID of the plan.
+</DynamicParamField>
+
+<DynamicParamField body="feature_quantities" type="object[]">
   If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan.
   <Expandable title="properties">
     <DynamicParamField body="feature_id" type="string" required />
@@ -34,6 +38,7 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
 </DynamicParamField>
 
 <DynamicParamField body="free_trial" type="object | null">
+  Override the plan's default free trial. Pass an object to set a custom trial, or null to remove the trial entirely.
   <Expandable title="properties">
     <DynamicParamField body="duration_length" type="number" required />
 
@@ -127,37 +132,56 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
   </Expandable>
 </DynamicParamField>
 
-<DynamicParamField body="plan_id" type="string" />
-
 <DynamicParamField body="invoice_mode" type="object">
+  Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. This uses Stripe's send_invoice collection method.
   <Expandable title="properties">
-    <DynamicParamField body="enabled" type="boolean" required />
+    <DynamicParamField body="enabled" type="boolean" required>
+      When true, creates an invoice and sends it to the customer instead of charging their card immediately. Uses Stripe's send_invoice collection method.
+    </DynamicParamField>
 
-    <DynamicParamField body="enable_plan_immediately" type="boolean" />
+    <DynamicParamField body="enable_plan_immediately" type="boolean">
+      If true, enables the plan immediately even though the invoice is not paid yet.
+    </DynamicParamField>
 
-    <DynamicParamField body="finalize" type="boolean" />
+    <DynamicParamField body="finalize" type="boolean">
+      If true, finalizes the invoice so it can be sent to the customer. If false, keeps it as a draft for manual review.
+    </DynamicParamField>
 
   </Expandable>
 </DynamicParamField>
 
-<DynamicParamField body="cancel_action" type="'cancel_immediately' | 'cancel_end_of_cycle' | 'uncancel'" />
+<DynamicParamField body="billing_behavior" type="'prorate_immediately' | 'next_cycle_only'">
+  How to handle billing when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'next_cycle_only' skips creating any charges and applies the change at the next billing cycle.
+</DynamicParamField>
 
-<DynamicParamField body="billing_behavior" type="'prorate_immediately' | 'next_cycle_only'" />
+<DynamicParamField body="cancel_action" type="'cancel_immediately' | 'cancel_end_of_cycle' | 'uncancel'">
+  Action to perform for cancellation. 'cancel_immediately' cancels now with prorated refund, 'cancel_end_of_cycle' cancels at period end, 'uncancel' reverses a pending cancellation.
+</DynamicParamField>
 
 
 ### Response
 
-<DynamicResponseField name="customer_id" type="string" />
+<DynamicResponseField name="customer_id" type="string">
+  The ID of the customer.
+</DynamicResponseField>
 
 <DynamicResponseField name="line_items" type="object[]">
+  List of line items for the current billing period.
   <Expandable title="properties">
-    <DynamicResponseField name="title" type="string" />
+    <DynamicResponseField name="title" type="string">
+      The title of the line item.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="description" type="string" />
+    <DynamicResponseField name="description" type="string">
+      A detailed description of the line item.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="amount" type="number" />
+    <DynamicResponseField name="amount" type="number">
+      The amount in cents for this line item.
+    </DynamicResponseField>
 
     <DynamicResponseField name="discounts" type="object[]">
+      List of discounts applied to this line item.
       <Expandable title="properties">
         <DynamicResponseField name="amountOff" type="number" />
 
@@ -170,84 +194,46 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
       </Expandable>
     </DynamicResponseField>
 
-    <DynamicResponseField name="plan_id" type="string" />
-
-    <DynamicResponseField name="total_quantity" type="number" />
-
-    <DynamicResponseField name="paid_quantity" type="number" />
-
-    <DynamicResponseField name="deferred_for_trial" type="boolean" />
-
-    <DynamicResponseField name="effective_period" type="object">
-      <Expandable title="properties">
-        <DynamicResponseField name="start" type="number" />
-
-        <DynamicResponseField name="end" type="number" />
-
   </Expandable>
 </DynamicResponseField>
 
-    <DynamicResponseField name="is_base" type="boolean" />
-
-  </Expandable>
+<DynamicResponseField name="total" type="number">
+  The total amount in cents for the current billing period.
 </DynamicResponseField>
 
-<DynamicResponseField name="total" type="number" />
-
-<DynamicResponseField name="currency" type="string" />
-
-<DynamicResponseField name="period_start" type="number" />
-
-<DynamicResponseField name="period_end" type="number" />
+<DynamicResponseField name="currency" type="string">
+  The three-letter ISO currency code (e.g., 'usd').
+</DynamicResponseField>
 
 <DynamicResponseField name="next_cycle" type="object">
+  Preview of the next billing cycle, if applicable. This shows what the customer will be charged in subsequent cycles.
   <Expandable title="properties">
-    <DynamicResponseField name="starts_at" type="number" />
-
-    <DynamicResponseField name="total" type="number" />
-
-    <DynamicResponseField name="line_items" type="object[]">
-      <Expandable title="properties">
-        <DynamicResponseField name="title" type="string" />
-
-        <DynamicResponseField name="description" type="string" />
-
-        <DynamicResponseField name="amount" type="number" />
-
-        <DynamicResponseField name="discounts" type="object[]">
-          <Expandable title="properties">
-            <DynamicResponseField name="amountOff" type="number" />
-
-            <DynamicResponseField name="percentOff" type="number" />
-
-            <DynamicResponseField name="stripeCouponId" type="string" />
-
-            <DynamicResponseField name="couponName" type="string" />
-
-          </Expandable>
+    <DynamicResponseField name="starts_at" type="number">
+      Unix timestamp (milliseconds) when the next billing cycle starts.
     </DynamicResponseField>
 
-        <DynamicResponseField name="plan_id" type="string" />
-
-        <DynamicResponseField name="total_quantity" type="number" />
-
-        <DynamicResponseField name="paid_quantity" type="number" />
-
-        <DynamicResponseField name="deferred_for_trial" type="boolean" />
-
-        <DynamicResponseField name="effective_period" type="object">
-          <Expandable title="properties">
-            <DynamicResponseField name="start" type="number" />
-
-            <DynamicResponseField name="end" type="number" />
-
-          </Expandable>
-        </DynamicResponseField>
-
-        <DynamicResponseField name="is_base" type="boolean" />
-
-      </Expandable>
+    <DynamicResponseField name="total" type="number">
+      The total amount in cents for the next cycle.
     </DynamicResponseField>
 
   </Expandable>
 </DynamicResponseField>
+
+
+<ResponseExample>
+```json 200
+{
+  "customerId": "charles",
+  "lineItems": [
+    {
+      "title": "Pro seed",
+      "description": "Pro seed - Base Price (from 18 Feb 2026 to 18 Mar 2026)",
+      "amount": 20,
+      "discounts": []
+    }
+  ],
+  "total": 20,
+  "currency": "usd"
+}
+```
+</ResponseExample>

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

@@ -1,5 +1,5 @@
 ---
-title: "Billing Setup Payment"
+title: "Setup Payment"
 openapi: "openapi POST /v1/billing.setup_payment"
 ---
 

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

@@ -1,13 +0,0 @@
----
-title: "Attach Product"
-openapi: "coreapi POST /attach"
----
-
-{/* If payment is required, a Stripe `checkout_url` will be returned. If the customer's card is already on file, any upgrade or downgrade logic will be handled by default, and a `success: true` response will be returned. */}
-
-<Tip>
-  {" "}
-  If the `customer_id` you send doesn't already exist, Autumn will automatically
-  create a new customer. You can optionally set the properties of this new customer
-  through the `customer_data` field.
-</Tip>

apps/docs/mintlify/api-reference/core/cancel.mdx

@@ -1,6 +0,0 @@
----
-title: "Cancel Product"
-openapi: "coreapi POST /cancel"
----
-
-{/* If payment is required, a Stripe `checkout_url` will be returned. If the customer's card is already on file, any upgrade or downgrade logic will be handled by default, and a `success: true` response will be returned. */}

apps/docs/mintlify/api-reference/core/check.mdx

@@ -1,11 +1,534 @@
 ---
 title: "Check Permissions"
-openapi: "openapi-1.2.0 POST /check"
+openapi: "openapi POST /v1/balances.check"
 ---
 
-<Tip>
-  {" "}
-  If the `customer_id` you send doesn't already exist, Autumn will automatically
-  create a new customer. You can optionally set the properties of this new customer
-  through the `customer_data` field.
-</Tip>
+import { DynamicParamField } from "/components/dynamic-param-field.jsx";
+import { DynamicResponseField } from "/components/dynamic-response-field.jsx";
+import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";
+
+<Note>
+  Check determines if a customer has access to a feature based on their current balance. Returns `allowed: true` if they have sufficient balance, the feature is unlimited, or it's a boolean feature included in their plan.
+</Note>
+
+### Common Use Cases
+
+<CodeGroup>
+
+```typescript Check feature access
+const { allowed, balance } = await autumn.check({
+  customerId: "cus_123",
+  featureId: "ai_messages"
+});
+
+if (!allowed) {
+  // Show upgrade prompt or paywall
+}
+
+console.log(`You have ${balance.remaining} messages left`);
+```
+
+```typescript Check and track atomically
+const { allowed } = await autumn.check({
+  customerId: "cus_123",
+  featureId: "api_calls",
+  requiredBalance: 1,
+  sendEvent: true // Deducts usage if allowed
+});
+```
+
+</CodeGroup>
+
+### Body Parameters
+
+<DynamicParamField body="customer_id" type="string" required>
+  The ID of the customer.
+</DynamicParamField>
+
+<DynamicParamField body="feature_id" type="string" required>
+  The ID of the feature.
+</DynamicParamField>
+
+<DynamicParamField body="entity_id" type="string">
+  The ID of the entity for entity-scoped balances (e.g., per-seat limits).
+</DynamicParamField>
+
+<DynamicParamField body="required_balance" type="number">
+  Minimum balance required for access. Returns allowed: false if the customer's balance is below this value. Defaults to 1.
+</DynamicParamField>
+
+<DynamicParamField body="properties" type="object">
+  Additional properties to attach to the usage event if send_event is true.
+</DynamicParamField>
+
+<DynamicParamField body="send_event" type="boolean">
+  If true, atomically records a usage event while checking access. The required_balance value is used as the usage amount. Combines check + track in one call.
+</DynamicParamField>
+
+<DynamicParamField body="with_preview" type="boolean">
+  If true, includes upgrade/upsell information in the response when access is denied. Useful for displaying paywalls.
+</DynamicParamField>
+
+
+### Response
+
+<DynamicResponseField name="allowed" type="boolean">
+  Whether the customer is allowed to use the feature. True if they have sufficient balance or the feature is unlimited/boolean.
+</DynamicResponseField>
+
+<DynamicResponseField name="customer_id" type="string">
+  The ID of the customer that was checked.
+</DynamicResponseField>
+
+<DynamicResponseField name="entity_id" type="string | null">
+  The ID of the entity, if an entity-scoped check was performed.
+</DynamicResponseField>
+
+<DynamicResponseField name="required_balance" type="number">
+  The required balance that was checked against.
+</DynamicResponseField>
+
+<DynamicResponseField name="balance" type="object | null">
+  The customer's balance for this feature. Null if the customer has no balance for this feature.
+  <Expandable title="properties">
+    <DynamicResponseField name="feature_id" type="string">
+      The feature ID this balance is for.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="feature" type="object">
+      The full feature object if expanded.
+      <Expandable title="properties">
+        <DynamicResponseField name="id" type="string" />
+
+        <DynamicResponseField name="name" type="string" />
+
+        <DynamicResponseField name="type" type="'boolean' | 'metered' | 'credit_system'" />
+
+        <DynamicResponseField name="consumable" type="boolean" />
+
+        <DynamicResponseField name="event_names" type="string[]" />
+
+        <DynamicResponseField name="credit_schema" type="object[]">
+          <Expandable title="properties">
+            <DynamicResponseField name="metered_feature_id" type="string" />
+
+            <DynamicResponseField name="credit_cost" type="number" />
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="display" type="object">
+          <Expandable title="properties">
+            <DynamicResponseField name="singular" type="string | null" />
+
+            <DynamicResponseField name="plural" type="string | null" />
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="archived" type="boolean" />
+
+      </Expandable>
+    </DynamicResponseField>
+
+    <DynamicResponseField name="granted" type="number">
+      Total balance granted (included + prepaid).
+    </DynamicResponseField>
+
+    <DynamicResponseField name="remaining" type="number">
+      Remaining balance available for use.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="usage" type="number">
+      Total usage consumed in the current period.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="unlimited" type="boolean">
+      Whether this feature has unlimited usage.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="overage_allowed" type="boolean">
+      Whether usage beyond the granted balance is allowed (with overage charges).
+    </DynamicResponseField>
+
+    <DynamicResponseField name="max_purchase" type="number | null">
+      Maximum quantity that can be purchased as a top-up, or null for unlimited.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="next_reset_at" type="number | null">
+      Timestamp when the balance will reset, or null for no reset.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="breakdown" type="object[]">
+      Detailed breakdown of balance sources when stacking multiple plans or grants.
+      <Expandable title="properties">
+        <DynamicResponseField name="id" type="string">
+          The unique identifier for this balance breakdown.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="plan_id" type="string | null">
+          The plan ID this balance originates from, or null for standalone balances.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="included_grant" type="number">
+          Amount granted from the plan's included usage.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="prepaid_grant" type="number">
+          Amount granted from prepaid purchases or top-ups.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="remaining" type="number">
+          Remaining balance available for use.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="usage" type="number">
+          Amount consumed in the current period.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="unlimited" type="boolean">
+          Whether this balance has unlimited usage.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="reset" type="object | null">
+          Reset configuration for this balance, or null if no reset.
+          <Expandable title="properties">
+            <DynamicResponseField name="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
+              The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="interval_count" type="number">
+              Number of intervals between resets (eg. 2 for bi-monthly).
+            </DynamicResponseField>
+
+            <DynamicResponseField name="resets_at" type="number | null">
+              Timestamp when the balance will next reset.
+            </DynamicResponseField>
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="price" type="object | null">
+          Pricing configuration if this balance has usage-based pricing.
+          <Expandable title="properties">
+            <DynamicResponseField name="amount" type="number">
+              The per-unit price amount.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="tiers" type="object[]">
+              Tiered pricing configuration if applicable.
+              <Expandable title="properties">
+                <DynamicResponseField name="to" type="number" />
+
+                <DynamicResponseField name="amount" type="number" />
+
+              </Expandable>
+            </DynamicResponseField>
+
+            <DynamicResponseField name="billing_units" type="number">
+              The number of units per billing increment (eg. $9 / 250 units).
+            </DynamicResponseField>
+
+            <DynamicResponseField name="billing_method" type="'prepaid' | 'usage_based'">
+              Whether usage is prepaid or billed pay-per-use.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="max_purchase" type="number | null">
+              Maximum quantity that can be purchased, or null for unlimited.
+            </DynamicResponseField>
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="expires_at" type="number | null">
+          Timestamp when this balance expires, or null for no expiration.
+        </DynamicResponseField>
+
+      </Expandable>
+    </DynamicResponseField>
+
+    <DynamicResponseField name="rollovers" type="object[]">
+      Rollover balances carried over from previous periods.
+      <Expandable title="properties">
+        <DynamicResponseField name="balance" type="number">
+          Amount of balance rolled over from a previous period.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="expires_at" type="number">
+          Timestamp when the rollover balance expires.
+        </DynamicResponseField>
+
+      </Expandable>
+    </DynamicResponseField>
+
+  </Expandable>
+</DynamicResponseField>
+
+<DynamicResponseField name="preview" type="object">
+  Upgrade/upsell information when access is denied. Only present if with_preview was true and allowed is false.
+  <Expandable title="properties">
+    <DynamicResponseField name="scenario" type="'usage_limit' | 'feature_flag'">
+      The reason access was denied. 'usage_limit' means the customer exceeded their balance, 'feature_flag' means the feature is not included in their plan.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="title" type="string">
+      A title suitable for displaying in a paywall or upgrade modal.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="message" type="string">
+      A message explaining why access was denied.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="feature_id" type="string">
+      The ID of the feature that was checked.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="feature_name" type="string">
+      The display name of the feature.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="products" type="object[]">
+      Products that would grant access to this feature. Use to display upgrade options.
+      <Expandable title="properties">
+        <DynamicResponseField name="id" type="string">
+          The ID of the product you set when creating the product
+        </DynamicResponseField>
+
+        <DynamicResponseField name="name" type="string">
+          The name of the product
+        </DynamicResponseField>
+
+        <DynamicResponseField name="group" type="string | null">
+          Product group which this product belongs to
+        </DynamicResponseField>
+
+        <DynamicResponseField name="env" type="'sandbox' | 'live'">
+          The environment of the product
+        </DynamicResponseField>
+
+        <DynamicResponseField name="is_add_on" type="boolean">
+          Whether the product is an add-on and can be purchased alongside other products
+        </DynamicResponseField>
+
+        <DynamicResponseField name="is_default" type="boolean">
+          Whether the product is the default product
+        </DynamicResponseField>
+
+        <DynamicResponseField name="archived" type="boolean">
+          Whether this product has been archived and is no longer available
+        </DynamicResponseField>
+
+        <DynamicResponseField name="version" type="number">
+          The current version of the product
+        </DynamicResponseField>
+
+        <DynamicResponseField name="created_at" type="number">
+          The timestamp of when the product was created in milliseconds since epoch
+        </DynamicResponseField>
+
+        <DynamicResponseField name="items" type="object[]">
+          Array of product items that define the product's features and pricing
+          <Expandable title="properties">
+            <DynamicResponseField name="type" type="'feature' | 'priced_feature' | 'price'">
+              The type of the product item
+            </DynamicResponseField>
+
+            <DynamicResponseField name="feature_id" type="string | null">
+              The feature ID of the product item. If the item is a fixed price, should be `null`
+            </DynamicResponseField>
+
+            <DynamicResponseField name="feature_type" type="'single_use' | 'continuous_use' | 'boolean' | 'static'">
+              Single use features are used once and then depleted, like API calls or credits. Continuous use features are those being used on an ongoing-basis, like storage or seats.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="included_usage" type="number | null">
+              The amount of usage included for this feature.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="interval" type="'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
+              The reset or billing interval of the product item. If null, feature will have no reset date, and if there's a price, it will be billed one-off.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="interval_count" type="number | null">
+              The interval count of the product item.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="price" type="number | null">
+              The price of the product item. Should be `null` if tiered pricing is set.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="tiers" type="object[] | null">
+              Tiered pricing for the product item. Not applicable for fixed price items.
+              <Expandable title="properties">
+                <DynamicResponseField name="to" type="number">
+                  The maximum amount of usage for this tier.
+                </DynamicResponseField>
+
+                <DynamicResponseField name="amount" type="number">
+                  The price of the product item for this tier.
+                </DynamicResponseField>
+
+              </Expandable>
+            </DynamicResponseField>
+
+            <DynamicResponseField name="usage_model" type="'prepaid' | 'pay_per_use'">
+              Whether the feature should be prepaid upfront or billed for how much they use end of billing period.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="billing_units" type="number | null">
+              The amount per billing unit (eg. $9 / 250 units)
+            </DynamicResponseField>
+
+            <DynamicResponseField name="reset_usage_when_enabled" type="boolean | null">
+              Whether the usage should be reset when the product is enabled.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="entity_feature_id" type="string | null">
+              The entity feature ID of the product item if applicable.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="display" type="object | null">
+              The display of the product item.
+              <Expandable title="properties">
+                <DynamicResponseField name="primary_text" type="string" />
+
+                <DynamicResponseField name="secondary_text" type="string | null" />
+
+              </Expandable>
+            </DynamicResponseField>
+
+            <DynamicResponseField name="quantity" type="number | null">
+              Used in customer context. Quantity of the feature the customer has prepaid for.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="next_cycle_quantity" type="number | null">
+              Used in customer context. Quantity of the feature the customer will prepay for in the next cycle.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="config" type="object | null">
+              Configuration for rollover and proration behavior of the feature.
+              <Expandable title="properties">
+                <DynamicResponseField name="rollover" type="object | null">
+                  <Expandable title="properties">
+                    <DynamicResponseField name="max" type="number | null" />
+
+                    <DynamicResponseField name="duration" type="'month' | 'forever'" />
+
+                    <DynamicResponseField name="length" type="number" />
+
+                  </Expandable>
+                </DynamicResponseField>
+
+                <DynamicResponseField name="on_increase" type="'bill_immediately' | 'prorate_immediately' | 'prorate_next_cycle' | 'bill_next_cycle'" />
+
+                <DynamicResponseField name="on_decrease" type="'prorate' | 'prorate_immediately' | 'prorate_next_cycle' | 'none' | 'no_prorations'" />
+
+              </Expandable>
+            </DynamicResponseField>
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="free_trial" type="object | null">
+          Free trial configuration for this product, if available
+          <Expandable title="properties">
+            <DynamicResponseField name="duration" type="'day' | 'month' | 'year'">
+              The duration type of the free trial
+            </DynamicResponseField>
+
+            <DynamicResponseField name="length" type="number">
+              The length of the duration type specified
+            </DynamicResponseField>
+
+            <DynamicResponseField name="unique_fingerprint" type="boolean">
+              Whether the free trial is limited to one per customer fingerprint
+            </DynamicResponseField>
+
+            <DynamicResponseField name="card_required" type="boolean">
+              Whether the free trial requires a card. If false, the customer can attach the product without going through a checkout flow or having a card on file.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="trial_available" type="boolean | null">
+              Used in customer context. Whether the free trial is available for the customer if they were to attach the product.
+            </DynamicResponseField>
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="base_variant_id" type="string | null">
+          ID of the base variant this product is derived from
+        </DynamicResponseField>
+
+        <DynamicResponseField name="scenario" type="'scheduled' | 'active' | 'new' | 'renew' | 'upgrade' | 'downgrade' | 'cancel' | 'expired' | 'past_due'">
+          Scenario for when this product is used in attach flows
+        </DynamicResponseField>
+
+        <DynamicResponseField name="properties" type="object">
+          <Expandable title="properties">
+            <DynamicResponseField name="is_free" type="boolean">
+              True if the product has no base price or usage prices
+            </DynamicResponseField>
+
+            <DynamicResponseField name="is_one_off" type="boolean">
+              True if the product only contains a one-time price
+            </DynamicResponseField>
+
+            <DynamicResponseField name="interval_group" type="string | null">
+              The billing interval group for recurring products (e.g., 'monthly', 'yearly')
+            </DynamicResponseField>
+
+            <DynamicResponseField name="has_trial" type="boolean | null">
+              True if the product includes a free trial
+            </DynamicResponseField>
+
+            <DynamicResponseField name="updateable" type="boolean | null">
+              True if the product can be updated after creation (only applicable if there are prepaid recurring prices)
+            </DynamicResponseField>
+
+          </Expandable>
+        </DynamicResponseField>
+
+      </Expandable>
+    </DynamicResponseField>
+
+  </Expandable>
+</DynamicResponseField>
+
+
+<ResponseExample>
+```json 200
+{
+  "allowed": true,
+  "customer_id": "cus_123",
+  "entity_id": null,
+  "required_balance": 1,
+  "balance": {
+    "feature_id": "messages",
+    "granted": 100,
+    "remaining": 72,
+    "usage": 28,
+    "unlimited": false,
+    "overage_allowed": false,
+    "max_purchase": null,
+    "next_reset_at": 1773851121437,
+    "breakdown": [
+      {
+        "id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
+        "plan_id": "pro_plan",
+        "included_grant": 100,
+        "prepaid_grant": 0,
+        "remaining": 72,
+        "usage": 28,
+        "unlimited": false,
+        "reset": {
+          "interval": "month",
+          "resets_at": 1773851121437
+        },
+        "price": null,
+        "expires_at": null
+      }
+    ]
+  }
+}
+```
+</ResponseExample>

apps/docs/mintlify/api-reference/core/checkout.mdx

@@ -1,13 +0,0 @@
----
-title: "Checkout"
-openapi: "coreapi POST /checkout"
----
-
-{/* If payment is required, a Stripe `checkout_url` will be returned. If the customer's card is already on file, any upgrade or downgrade logic will be handled by default, and a `success: true` response will be returned. */}
-
-<Tip>
-  {" "}
-  If the `customer_id` you send doesn't already exist, Autumn will automatically
-  create a new customer. You can optionally set the properties of this new customer
-  through the `customer_data` field.
-</Tip>

apps/docs/mintlify/api-reference/core/query.mdx

@@ -1,55 +0,0 @@
----
-title: "Query Usage Data"
-openapi: "coreapi POST /query"
----
-
-This endpoint allows you to query usage data for specific features over various time ranges. It returns historical usage information that can be used for analytics, reporting, or displaying usage graphs to customers.
-
-<Tip>
-  You can query usage for a single feature or multiple features in one request by passing an array of feature IDs.
-</Tip>
-
-<Note>
-The response returns a list of objects. Each object includes a `period` timestamp and one key per requested feature ID with its usage value.
-</Note>
-
-{/* 
-## Example Usage
-
-### Single Feature Query
-
-Query usage for the "messages" feature over the last 30 days:
-
-```javascript
-const response = await autumn.query({
-  customer_id: 'user_123',
-  feature_id: 'messages',
-  range: '30d'
-});
-
-console.log(response.list);
-// [
-//   { period: 1672531200000, messages: 45 },
-//   { period: 1672617600000, messages: 32 },
-//   { period: 1672704000000, messages: 18 }
-// ]
-```
-
-### Multiple Features Query
-
-Query usage for both "credits" and "messages" features over the last 7 days:
-
-```javascript  
-const response = await autumn.query({
-  customer_id: 'user_123',
-  feature_id: ['credits', 'messages'],
-  range: '7d'
-});
-
-console.log(response.list);
-// [
-//   { period: 1672531200000, credits: 20, messages: 45 },
-//   { period: 1672617600000, credits: 15, messages: 32 },
-//   { period: 1672704000000, credits: 30, messages: 18 }
-// ]
-``` */}

apps/docs/mintlify/api-reference/core/track.mdx

@@ -1,13 +1,477 @@
 ---
 title: "Track Usage"
-openapi: "openapi-1.2.0 POST /track"
+openapi: "openapi POST /v1/balances.track"
 ---
 
-This endpoint is for tracking usage events in Autumn, so feature usage can be limited or billed for.
+import { DynamicParamField } from "/components/dynamic-param-field.jsx";
+import { DynamicResponseField } from "/components/dynamic-response-field.jsx";
+import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";
 
-<Tip>
-  {" "}
-  If the `customer_id` you send doesn't already exist, Autumn will automatically
-  create a new customer. You can optionally set the properties of this new customer
-  through the `customer_data` field.
-</Tip>
+<Note>
+  Track records usage events to decrement a customer's balance. Use this to meter feature consumption like API calls, messages sent, or credits used.
+</Note>
+
+### Common Use Cases
+
+<CodeGroup>
+
+```typescript Track single usage
+await autumn.track({
+  customerId: "cus_123",
+  featureId: "ai_messages",
+  value: 1
+});
+```
+
+```typescript Track with idempotency
+await autumn.track({
+  customerId: "cus_123",
+  featureId: "api_calls",
+  value: 1,
+  idempotencyKey: "request_abc123" // Prevents duplicate tracking on retry
+});
+```
+
+```typescript Credit balance (negative value)
+await autumn.track({
+  customerId: "cus_123",
+  featureId: "seats",
+  value: -1 // Increases balance when removing a seat
+});
+```
+
+</CodeGroup>
+
+### Body Parameters
+
+<DynamicParamField body="customer_id" type="string" required>
+  The ID of the customer.
+</DynamicParamField>
+
+<DynamicParamField body="feature_id" type="string">
+  The ID of the feature to track usage for. Required if event_name is not provided.
+</DynamicParamField>
+
+<DynamicParamField body="entity_id" type="string">
+  The ID of the entity for entity-scoped balances (e.g., per-seat limits).
+</DynamicParamField>
+
+<DynamicParamField body="event_name" type="string">
+  Event name to track usage for. Use instead of feature_id when multiple features should be tracked from a single event.
+</DynamicParamField>
+
+<DynamicParamField body="value" type="number">
+  The amount of usage to record. Defaults to 1. Use negative values to credit balance (e.g., when removing a seat).
+</DynamicParamField>
+
+<DynamicParamField body="properties" type="object">
+  Additional properties to attach to this usage event.
+</DynamicParamField>
+
+
+### Response
+
+<DynamicResponseField name="customer_id" type="string">
+  The ID of the customer whose usage was tracked.
+</DynamicResponseField>
+
+<DynamicResponseField name="entity_id" type="string">
+  The ID of the entity, if entity-scoped tracking was performed.
+</DynamicResponseField>
+
+<DynamicResponseField name="event_name" type="string">
+  The event name that was tracked, if event_name was used instead of feature_id.
+</DynamicResponseField>
+
+<DynamicResponseField name="value" type="number">
+  The amount of usage that was recorded.
+</DynamicResponseField>
+
+<DynamicResponseField name="balance" type="object | null">
+  The updated balance for the tracked feature. Null if tracking by event_name that affects multiple features.
+  <Expandable title="properties">
+    <DynamicResponseField name="feature_id" type="string">
+      The feature ID this balance is for.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="feature" type="object">
+      The full feature object if expanded.
+      <Expandable title="properties">
+        <DynamicResponseField name="id" type="string" />
+
+        <DynamicResponseField name="name" type="string" />
+
+        <DynamicResponseField name="type" type="'boolean' | 'metered' | 'credit_system'" />
+
+        <DynamicResponseField name="consumable" type="boolean" />
+
+        <DynamicResponseField name="event_names" type="string[]" />
+
+        <DynamicResponseField name="credit_schema" type="object[]">
+          <Expandable title="properties">
+            <DynamicResponseField name="metered_feature_id" type="string" />
+
+            <DynamicResponseField name="credit_cost" type="number" />
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="display" type="object">
+          <Expandable title="properties">
+            <DynamicResponseField name="singular" type="string | null" />
+
+            <DynamicResponseField name="plural" type="string | null" />
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="archived" type="boolean" />
+
+      </Expandable>
+    </DynamicResponseField>
+
+    <DynamicResponseField name="granted" type="number">
+      Total balance granted (included + prepaid).
+    </DynamicResponseField>
+
+    <DynamicResponseField name="remaining" type="number">
+      Remaining balance available for use.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="usage" type="number">
+      Total usage consumed in the current period.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="unlimited" type="boolean">
+      Whether this feature has unlimited usage.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="overage_allowed" type="boolean">
+      Whether usage beyond the granted balance is allowed (with overage charges).
+    </DynamicResponseField>
+
+    <DynamicResponseField name="max_purchase" type="number | null">
+      Maximum quantity that can be purchased as a top-up, or null for unlimited.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="next_reset_at" type="number | null">
+      Timestamp when the balance will reset, or null for no reset.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="breakdown" type="object[]">
+      Detailed breakdown of balance sources when stacking multiple plans or grants.
+      <Expandable title="properties">
+        <DynamicResponseField name="id" type="string">
+          The unique identifier for this balance breakdown.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="plan_id" type="string | null">
+          The plan ID this balance originates from, or null for standalone balances.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="included_grant" type="number">
+          Amount granted from the plan's included usage.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="prepaid_grant" type="number">
+          Amount granted from prepaid purchases or top-ups.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="remaining" type="number">
+          Remaining balance available for use.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="usage" type="number">
+          Amount consumed in the current period.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="unlimited" type="boolean">
+          Whether this balance has unlimited usage.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="reset" type="object | null">
+          Reset configuration for this balance, or null if no reset.
+          <Expandable title="properties">
+            <DynamicResponseField name="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
+              The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="interval_count" type="number">
+              Number of intervals between resets (eg. 2 for bi-monthly).
+            </DynamicResponseField>
+
+            <DynamicResponseField name="resets_at" type="number | null">
+              Timestamp when the balance will next reset.
+            </DynamicResponseField>
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="price" type="object | null">
+          Pricing configuration if this balance has usage-based pricing.
+          <Expandable title="properties">
+            <DynamicResponseField name="amount" type="number">
+              The per-unit price amount.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="tiers" type="object[]">
+              Tiered pricing configuration if applicable.
+              <Expandable title="properties">
+                <DynamicResponseField name="to" type="number" />
+
+                <DynamicResponseField name="amount" type="number" />
+
+              </Expandable>
+            </DynamicResponseField>
+
+            <DynamicResponseField name="billing_units" type="number">
+              The number of units per billing increment (eg. $9 / 250 units).
+            </DynamicResponseField>
+
+            <DynamicResponseField name="billing_method" type="'prepaid' | 'usage_based'">
+              Whether usage is prepaid or billed pay-per-use.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="max_purchase" type="number | null">
+              Maximum quantity that can be purchased, or null for unlimited.
+            </DynamicResponseField>
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="expires_at" type="number | null">
+          Timestamp when this balance expires, or null for no expiration.
+        </DynamicResponseField>
+
+      </Expandable>
+    </DynamicResponseField>
+
+    <DynamicResponseField name="rollovers" type="object[]">
+      Rollover balances carried over from previous periods.
+      <Expandable title="properties">
+        <DynamicResponseField name="balance" type="number">
+          Amount of balance rolled over from a previous period.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="expires_at" type="number">
+          Timestamp when the rollover balance expires.
+        </DynamicResponseField>
+
+      </Expandable>
+    </DynamicResponseField>
+
+  </Expandable>
+</DynamicResponseField>
+
+<DynamicResponseField name="balances.{key}" type="object">
+  Map of feature_id to updated balance when tracking by event_name affects multiple features.
+  <Expandable title="properties">
+    <DynamicResponseField name="feature_id" type="string">
+      The feature ID this balance is for.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="feature" type="object">
+      The full feature object if expanded.
+      <Expandable title="properties">
+        <DynamicResponseField name="id" type="string" />
+
+        <DynamicResponseField name="name" type="string" />
+
+        <DynamicResponseField name="type" type="'boolean' | 'metered' | 'credit_system'" />
+
+        <DynamicResponseField name="consumable" type="boolean" />
+
+        <DynamicResponseField name="event_names" type="string[]" />
+
+        <DynamicResponseField name="credit_schema" type="object[]">
+          <Expandable title="properties">
+            <DynamicResponseField name="metered_feature_id" type="string" />
+
+            <DynamicResponseField name="credit_cost" type="number" />
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="display" type="object">
+          <Expandable title="properties">
+            <DynamicResponseField name="singular" type="string | null" />
+
+            <DynamicResponseField name="plural" type="string | null" />
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="archived" type="boolean" />
+
+      </Expandable>
+    </DynamicResponseField>
+
+    <DynamicResponseField name="granted" type="number">
+      Total balance granted (included + prepaid).
+    </DynamicResponseField>
+
+    <DynamicResponseField name="remaining" type="number">
+      Remaining balance available for use.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="usage" type="number">
+      Total usage consumed in the current period.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="unlimited" type="boolean">
+      Whether this feature has unlimited usage.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="overage_allowed" type="boolean">
+      Whether usage beyond the granted balance is allowed (with overage charges).
+    </DynamicResponseField>
+
+    <DynamicResponseField name="max_purchase" type="number | null">
+      Maximum quantity that can be purchased as a top-up, or null for unlimited.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="next_reset_at" type="number | null">
+      Timestamp when the balance will reset, or null for no reset.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="breakdown" type="object[]">
+      Detailed breakdown of balance sources when stacking multiple plans or grants.
+      <Expandable title="properties">
+        <DynamicResponseField name="id" type="string">
+          The unique identifier for this balance breakdown.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="plan_id" type="string | null">
+          The plan ID this balance originates from, or null for standalone balances.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="included_grant" type="number">
+          Amount granted from the plan's included usage.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="prepaid_grant" type="number">
+          Amount granted from prepaid purchases or top-ups.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="remaining" type="number">
+          Remaining balance available for use.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="usage" type="number">
+          Amount consumed in the current period.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="unlimited" type="boolean">
+          Whether this balance has unlimited usage.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="reset" type="object | null">
+          Reset configuration for this balance, or null if no reset.
+          <Expandable title="properties">
+            <DynamicResponseField name="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
+              The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="interval_count" type="number">
+              Number of intervals between resets (eg. 2 for bi-monthly).
+            </DynamicResponseField>
+
+            <DynamicResponseField name="resets_at" type="number | null">
+              Timestamp when the balance will next reset.
+            </DynamicResponseField>
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="price" type="object | null">
+          Pricing configuration if this balance has usage-based pricing.
+          <Expandable title="properties">
+            <DynamicResponseField name="amount" type="number">
+              The per-unit price amount.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="tiers" type="object[]">
+              Tiered pricing configuration if applicable.
+              <Expandable title="properties">
+                <DynamicResponseField name="to" type="number" />
+
+                <DynamicResponseField name="amount" type="number" />
+
+              </Expandable>
+            </DynamicResponseField>
+
+            <DynamicResponseField name="billing_units" type="number">
+              The number of units per billing increment (eg. $9 / 250 units).
+            </DynamicResponseField>
+
+            <DynamicResponseField name="billing_method" type="'prepaid' | 'usage_based'">
+              Whether usage is prepaid or billed pay-per-use.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="max_purchase" type="number | null">
+              Maximum quantity that can be purchased, or null for unlimited.
+            </DynamicResponseField>
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="expires_at" type="number | null">
+          Timestamp when this balance expires, or null for no expiration.
+        </DynamicResponseField>
+
+      </Expandable>
+    </DynamicResponseField>
+
+    <DynamicResponseField name="rollovers" type="object[]">
+      Rollover balances carried over from previous periods.
+      <Expandable title="properties">
+        <DynamicResponseField name="balance" type="number">
+          Amount of balance rolled over from a previous period.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="expires_at" type="number">
+          Timestamp when the rollover balance expires.
+        </DynamicResponseField>
+
+      </Expandable>
+    </DynamicResponseField>
+
+  </Expandable>
+</DynamicResponseField>
+
+
+<ResponseExample>
+```json 200
+{
+  "customer_id": "cus_123",
+  "value": 1,
+  "balance": {
+    "feature_id": "messages",
+    "granted": 100,
+    "remaining": 72,
+    "usage": 28,
+    "unlimited": false,
+    "overage_allowed": false,
+    "max_purchase": null,
+    "next_reset_at": 1773851121437,
+    "breakdown": [
+      {
+        "id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
+        "plan_id": "pro_plan",
+        "included_grant": 100,
+        "prepaid_grant": 0,
+        "remaining": 72,
+        "usage": 28,
+        "unlimited": false,
+        "reset": {
+          "interval": "month",
+          "resets_at": 1773851121437
+        },
+        "price": null,
+        "expires_at": null
+      }
+    ]
+  }
+}
+```
+</ResponseExample>

apps/docs/mintlify/api-reference/customers/getOrCreateCustomer.mdx

@@ -93,8 +93,10 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
 </DynamicResponseField>
 
 <DynamicResponseField name="subscriptions" type="object[]">
+  Active and scheduled recurring plans that this customer has attached.
   <Expandable title="properties">
     <DynamicResponseField name="plan" type="object">
+      The full plan object if expanded.
       <Expandable title="properties">
         <DynamicResponseField name="id" type="string" />
 
@@ -285,36 +287,62 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
       </Expandable>
     </DynamicResponseField>
 
-    <DynamicResponseField name="plan_id" type="string" />
+    <DynamicResponseField name="plan_id" type="string">
+      The unique identifier of the subscribed plan.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="auto_enable" type="boolean" />
+    <DynamicResponseField name="auto_enable" type="boolean">
+      Whether the plan was automatically enabled for the customer.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="add_on" type="boolean" />
+    <DynamicResponseField name="add_on" type="boolean">
+      Whether this is an add-on plan rather than a base subscription.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="status" type="'active' | 'scheduled' | 'expired'" />
+    <DynamicResponseField name="status" type="'active' | 'scheduled'">
+      Current status of the subscription.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="past_due" type="boolean" />
+    <DynamicResponseField name="past_due" type="boolean">
+      Whether the subscription has overdue payments.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="canceled_at" type="number | null" />
+    <DynamicResponseField name="canceled_at" type="number | null">
+      Timestamp when the subscription was canceled, or null if not canceled.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="expires_at" type="number | null" />
+    <DynamicResponseField name="expires_at" type="number | null">
+      Timestamp when the subscription will expire, or null if no expiry set.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="trial_ends_at" type="number | null" />
+    <DynamicResponseField name="trial_ends_at" type="number | null">
+      Timestamp when the trial period ends, or null if not on trial.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="started_at" type="number" />
+    <DynamicResponseField name="started_at" type="number">
+      Timestamp when the subscription started.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="current_period_start" type="number | null" />
+    <DynamicResponseField name="current_period_start" type="number | null">
+      Start timestamp of the current billing period.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="current_period_end" type="number | null" />
+    <DynamicResponseField name="current_period_end" type="number | null">
+      End timestamp of the current billing period.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="quantity" type="number" />
+    <DynamicResponseField name="quantity" type="number">
+      Number of units of this subscription (for per-seat plans).
+    </DynamicResponseField>
 
   </Expandable>
 </DynamicResponseField>
 
 <DynamicResponseField name="purchases" type="object[]">
+  One-time purchases made by the customer.
   <Expandable title="properties">
     <DynamicResponseField name="plan" type="object">
+      The full plan object if expanded.
       <Expandable title="properties">
         <DynamicResponseField name="id" type="string" />
 
@@ -505,18 +533,200 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
       </Expandable>
     </DynamicResponseField>
 
-    <DynamicResponseField name="plan_id" type="string" />
+    <DynamicResponseField name="plan_id" type="string">
+      The unique identifier of the purchased plan.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="expires_at" type="number | null" />
+    <DynamicResponseField name="expires_at" type="number | null">
+      Timestamp when the purchase expires, or null for lifetime access.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="started_at" type="number" />
+    <DynamicResponseField name="started_at" type="number">
+      Timestamp when the purchase was made.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="quantity" type="number" />
+    <DynamicResponseField name="quantity" type="number">
+      Number of units purchased.
+    </DynamicResponseField>
 
   </Expandable>
 </DynamicResponseField>
 
-<DynamicResponseField name="balances" type="object" />
+<DynamicResponseField name="balances.{key}" type="object">
+  Feature balances keyed by feature ID, showing usage limits and remaining amounts.
+  <Expandable title="properties">
+    <DynamicResponseField name="feature_id" type="string">
+      The feature ID this balance is for.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="feature" type="object">
+      The full feature object if expanded.
+      <Expandable title="properties">
+        <DynamicResponseField name="id" type="string" />
+
+        <DynamicResponseField name="name" type="string" />
+
+        <DynamicResponseField name="type" type="'boolean' | 'metered' | 'credit_system'" />
+
+        <DynamicResponseField name="consumable" type="boolean" />
+
+        <DynamicResponseField name="event_names" type="string[]" />
+
+        <DynamicResponseField name="credit_schema" type="object[]">
+          <Expandable title="properties">
+            <DynamicResponseField name="metered_feature_id" type="string" />
+
+            <DynamicResponseField name="credit_cost" type="number" />
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="display" type="object">
+          <Expandable title="properties">
+            <DynamicResponseField name="singular" type="string | null" />
+
+            <DynamicResponseField name="plural" type="string | null" />
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="archived" type="boolean" />
+
+      </Expandable>
+    </DynamicResponseField>
+
+    <DynamicResponseField name="granted" type="number">
+      Total balance granted (included + prepaid).
+    </DynamicResponseField>
+
+    <DynamicResponseField name="remaining" type="number">
+      Remaining balance available for use.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="usage" type="number">
+      Total usage consumed in the current period.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="unlimited" type="boolean">
+      Whether this feature has unlimited usage.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="overage_allowed" type="boolean">
+      Whether usage beyond the granted balance is allowed (with overage charges).
+    </DynamicResponseField>
+
+    <DynamicResponseField name="max_purchase" type="number | null">
+      Maximum quantity that can be purchased as a top-up, or null for unlimited.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="next_reset_at" type="number | null">
+      Timestamp when the balance will reset, or null for no reset.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="breakdown" type="object[]">
+      Detailed breakdown of balance sources when stacking multiple plans or grants.
+      <Expandable title="properties">
+        <DynamicResponseField name="id" type="string">
+          The unique identifier for this balance breakdown.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="plan_id" type="string | null">
+          The plan ID this balance originates from, or null for standalone balances.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="included_grant" type="number">
+          Amount granted from the plan's included usage.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="prepaid_grant" type="number">
+          Amount granted from prepaid purchases or top-ups.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="remaining" type="number">
+          Remaining balance available for use.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="usage" type="number">
+          Amount consumed in the current period.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="unlimited" type="boolean">
+          Whether this balance has unlimited usage.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="reset" type="object | null">
+          Reset configuration for this balance, or null if no reset.
+          <Expandable title="properties">
+            <DynamicResponseField name="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
+              The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="interval_count" type="number">
+              Number of intervals between resets (eg. 2 for bi-monthly).
+            </DynamicResponseField>
+
+            <DynamicResponseField name="resets_at" type="number | null">
+              Timestamp when the balance will next reset.
+            </DynamicResponseField>
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="price" type="object | null">
+          Pricing configuration if this balance has usage-based pricing.
+          <Expandable title="properties">
+            <DynamicResponseField name="amount" type="number">
+              The per-unit price amount.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="tiers" type="object[]">
+              Tiered pricing configuration if applicable.
+              <Expandable title="properties">
+                <DynamicResponseField name="to" type="number" />
+
+                <DynamicResponseField name="amount" type="number" />
+
+              </Expandable>
+            </DynamicResponseField>
+
+            <DynamicResponseField name="billing_units" type="number">
+              The number of units per billing increment (eg. $9 / 250 units).
+            </DynamicResponseField>
+
+            <DynamicResponseField name="billing_method" type="'prepaid' | 'usage_based'">
+              Whether usage is prepaid or billed pay-per-use.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="max_purchase" type="number | null">
+              Maximum quantity that can be purchased, or null for unlimited.
+            </DynamicResponseField>
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="expires_at" type="number | null">
+          Timestamp when this balance expires, or null for no expiration.
+        </DynamicResponseField>
+
+      </Expandable>
+    </DynamicResponseField>
+
+    <DynamicResponseField name="rollovers" type="object[]">
+      Rollover balances carried over from previous periods.
+      <Expandable title="properties">
+        <DynamicResponseField name="balance" type="number">
+          Amount of balance rolled over from a previous period.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="expires_at" type="number">
+          Timestamp when the rollover balance expires.
+        </DynamicResponseField>
+
+      </Expandable>
+    </DynamicResponseField>
+
+  </Expandable>
+</DynamicResponseField>
 
 <DynamicResponseField name="invoices" type="object[]">
   <Expandable title="properties">
@@ -676,33 +886,59 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
 <ResponseExample>
 ```json 200
 {
-  "id": "cus_123",
-  "created_at": 1717000000,
-  "name": "John Doe",
-  "email": "john@example.com",
-  "fingerprint": "1234567890",
-  "stripe_id": "cus_123",
+  "id": "2ee25a41-0d81-4ad2-8451-ec1aadaefe58",
+  "name": "Patrick",
+  "email": "patrick@useautumn.com",
+  "createdAt": 1771409161016,
+  "fingerprint": null,
+  "stripeId": "cus_U0BKxpq1mFhuJO",
   "env": "sandbox",
   "metadata": {},
+  "sendEmailReceipts": false,
   "subscriptions": [
     {
-      "id": "sub_123",
-      "created_at": 1717000000,
-      "plan_id": "plan_123",
+      "planId": "pro_plan",
+      "autoEnable": true,
+      "addOn": false,
       "status": "active",
-      "quantity": 1,
-      "interval": "month",
-      "interval_count": 1
+      "pastDue": false,
+      "canceledAt": null,
+      "expiresAt": null,
+      "trialEndsAt": null,
+      "startedAt": 1771431921437,
+      "currentPeriodStart": 1771431921437,
+      "currentPeriodEnd": 1771999921437,
+      "quantity": 1
     }
   ],
   "purchases": [],
   "balances": {
-    "balance_1": {
-      "id": "balance_1",
-      "amount": 100,
-      "currency": "USD",
-      "created_at": 1717000000,
-      "updated_at": 1717000000
+    "messages": {
+      "featureId": "messages",
+      "granted": 100,
+      "remaining": 0,
+      "usage": 100,
+      "unlimited": false,
+      "overageAllowed": false,
+      "maxPurchase": null,
+      "nextResetAt": 1773851121437,
+      "breakdown": [
+        {
+          "id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
+          "planId": "pro_plan",
+          "includedGrant": 100,
+          "prepaidGrant": 0,
+          "remaining": 0,
+          "usage": 100,
+          "unlimited": false,
+          "reset": {
+            "interval": "month",
+            "resetsAt": 1773851121437
+          },
+          "price": null,
+          "expiresAt": null
+        }
+      ]
     }
   }
 }

apps/docs/mintlify/api-reference/customers/listCustomers.mdx

@@ -78,8 +78,10 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
     </DynamicResponseField>
 
     <DynamicResponseField name="subscriptions" type="object[]">
+      Active and scheduled recurring plans that this customer has attached.
       <Expandable title="properties">
         <DynamicResponseField name="plan" type="object">
+          The full plan object if expanded.
           <Expandable title="properties">
             <DynamicResponseField name="id" type="string" />
 
@@ -270,36 +272,62 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
           </Expandable>
         </DynamicResponseField>
 
-        <DynamicResponseField name="plan_id" type="string" />
+        <DynamicResponseField name="plan_id" type="string">
+          The unique identifier of the subscribed plan.
+        </DynamicResponseField>
 
-        <DynamicResponseField name="auto_enable" type="boolean" />
+        <DynamicResponseField name="auto_enable" type="boolean">
+          Whether the plan was automatically enabled for the customer.
+        </DynamicResponseField>
 
-        <DynamicResponseField name="add_on" type="boolean" />
+        <DynamicResponseField name="add_on" type="boolean">
+          Whether this is an add-on plan rather than a base subscription.
+        </DynamicResponseField>
 
-        <DynamicResponseField name="status" type="'active' | 'scheduled' | 'expired'" />
+        <DynamicResponseField name="status" type="'active' | 'scheduled'">
+          Current status of the subscription.
+        </DynamicResponseField>
 
-        <DynamicResponseField name="past_due" type="boolean" />
+        <DynamicResponseField name="past_due" type="boolean">
+          Whether the subscription has overdue payments.
+        </DynamicResponseField>
 
-        <DynamicResponseField name="canceled_at" type="number | null" />
+        <DynamicResponseField name="canceled_at" type="number | null">
+          Timestamp when the subscription was canceled, or null if not canceled.
+        </DynamicResponseField>
 
-        <DynamicResponseField name="expires_at" type="number | null" />
+        <DynamicResponseField name="expires_at" type="number | null">
+          Timestamp when the subscription will expire, or null if no expiry set.
+        </DynamicResponseField>
 
-        <DynamicResponseField name="trial_ends_at" type="number | null" />
+        <DynamicResponseField name="trial_ends_at" type="number | null">
+          Timestamp when the trial period ends, or null if not on trial.
+        </DynamicResponseField>
 
-        <DynamicResponseField name="started_at" type="number" />
+        <DynamicResponseField name="started_at" type="number">
+          Timestamp when the subscription started.
+        </DynamicResponseField>
 
-        <DynamicResponseField name="current_period_start" type="number | null" />
+        <DynamicResponseField name="current_period_start" type="number | null">
+          Start timestamp of the current billing period.
+        </DynamicResponseField>
 
-        <DynamicResponseField name="current_period_end" type="number | null" />
+        <DynamicResponseField name="current_period_end" type="number | null">
+          End timestamp of the current billing period.
+        </DynamicResponseField>
 
-        <DynamicResponseField name="quantity" type="number" />
+        <DynamicResponseField name="quantity" type="number">
+          Number of units of this subscription (for per-seat plans).
+        </DynamicResponseField>
 
       </Expandable>
     </DynamicResponseField>
 
     <DynamicResponseField name="purchases" type="object[]">
+      One-time purchases made by the customer.
       <Expandable title="properties">
         <DynamicResponseField name="plan" type="object">
+          The full plan object if expanded.
           <Expandable title="properties">
             <DynamicResponseField name="id" type="string" />
 
@@ -490,18 +518,200 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
           </Expandable>
         </DynamicResponseField>
 
-        <DynamicResponseField name="plan_id" type="string" />
+        <DynamicResponseField name="plan_id" type="string">
+          The unique identifier of the purchased plan.
+        </DynamicResponseField>
 
-        <DynamicResponseField name="expires_at" type="number | null" />
+        <DynamicResponseField name="expires_at" type="number | null">
+          Timestamp when the purchase expires, or null for lifetime access.
+        </DynamicResponseField>
 
-        <DynamicResponseField name="started_at" type="number" />
+        <DynamicResponseField name="started_at" type="number">
+          Timestamp when the purchase was made.
+        </DynamicResponseField>
 
-        <DynamicResponseField name="quantity" type="number" />
+        <DynamicResponseField name="quantity" type="number">
+          Number of units purchased.
+        </DynamicResponseField>
 
       </Expandable>
     </DynamicResponseField>
 
-    <DynamicResponseField name="balances" type="object" />
+    <DynamicResponseField name="balances.{key}" type="object">
+      Feature balances keyed by feature ID, showing usage limits and remaining amounts.
+      <Expandable title="properties">
+        <DynamicResponseField name="feature_id" type="string">
+          The feature ID this balance is for.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="feature" type="object">
+          The full feature object if expanded.
+          <Expandable title="properties">
+            <DynamicResponseField name="id" type="string" />
+
+            <DynamicResponseField name="name" type="string" />
+
+            <DynamicResponseField name="type" type="'boolean' | 'metered' | 'credit_system'" />
+
+            <DynamicResponseField name="consumable" type="boolean" />
+
+            <DynamicResponseField name="event_names" type="string[]" />
+
+            <DynamicResponseField name="credit_schema" type="object[]">
+              <Expandable title="properties">
+                <DynamicResponseField name="metered_feature_id" type="string" />
+
+                <DynamicResponseField name="credit_cost" type="number" />
+
+              </Expandable>
+            </DynamicResponseField>
+
+            <DynamicResponseField name="display" type="object">
+              <Expandable title="properties">
+                <DynamicResponseField name="singular" type="string | null" />
+
+                <DynamicResponseField name="plural" type="string | null" />
+
+              </Expandable>
+            </DynamicResponseField>
+
+            <DynamicResponseField name="archived" type="boolean" />
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="granted" type="number">
+          Total balance granted (included + prepaid).
+        </DynamicResponseField>
+
+        <DynamicResponseField name="remaining" type="number">
+          Remaining balance available for use.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="usage" type="number">
+          Total usage consumed in the current period.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="unlimited" type="boolean">
+          Whether this feature has unlimited usage.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="overage_allowed" type="boolean">
+          Whether usage beyond the granted balance is allowed (with overage charges).
+        </DynamicResponseField>
+
+        <DynamicResponseField name="max_purchase" type="number | null">
+          Maximum quantity that can be purchased as a top-up, or null for unlimited.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="next_reset_at" type="number | null">
+          Timestamp when the balance will reset, or null for no reset.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="breakdown" type="object[]">
+          Detailed breakdown of balance sources when stacking multiple plans or grants.
+          <Expandable title="properties">
+            <DynamicResponseField name="id" type="string">
+              The unique identifier for this balance breakdown.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="plan_id" type="string | null">
+              The plan ID this balance originates from, or null for standalone balances.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="included_grant" type="number">
+              Amount granted from the plan's included usage.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="prepaid_grant" type="number">
+              Amount granted from prepaid purchases or top-ups.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="remaining" type="number">
+              Remaining balance available for use.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="usage" type="number">
+              Amount consumed in the current period.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="unlimited" type="boolean">
+              Whether this balance has unlimited usage.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="reset" type="object | null">
+              Reset configuration for this balance, or null if no reset.
+              <Expandable title="properties">
+                <DynamicResponseField name="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
+                  The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
+                </DynamicResponseField>
+
+                <DynamicResponseField name="interval_count" type="number">
+                  Number of intervals between resets (eg. 2 for bi-monthly).
+                </DynamicResponseField>
+
+                <DynamicResponseField name="resets_at" type="number | null">
+                  Timestamp when the balance will next reset.
+                </DynamicResponseField>
+
+              </Expandable>
+            </DynamicResponseField>
+
+            <DynamicResponseField name="price" type="object | null">
+              Pricing configuration if this balance has usage-based pricing.
+              <Expandable title="properties">
+                <DynamicResponseField name="amount" type="number">
+                  The per-unit price amount.
+                </DynamicResponseField>
+
+                <DynamicResponseField name="tiers" type="object[]">
+                  Tiered pricing configuration if applicable.
+                  <Expandable title="properties">
+                    <DynamicResponseField name="to" type="any" />
+
+                    <DynamicResponseField name="amount" type="number" />
+
+                  </Expandable>
+                </DynamicResponseField>
+
+                <DynamicResponseField name="billing_units" type="number">
+                  The number of units per billing increment (eg. $9 / 250 units).
+                </DynamicResponseField>
+
+                <DynamicResponseField name="billing_method" type="'prepaid' | 'usage_based'">
+                  Whether usage is prepaid or billed pay-per-use.
+                </DynamicResponseField>
+
+                <DynamicResponseField name="max_purchase" type="number | null">
+                  Maximum quantity that can be purchased, or null for unlimited.
+                </DynamicResponseField>
+
+              </Expandable>
+            </DynamicResponseField>
+
+            <DynamicResponseField name="expires_at" type="number | null">
+              Timestamp when this balance expires, or null for no expiration.
+            </DynamicResponseField>
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="rollovers" type="object[]">
+          Rollover balances carried over from previous periods.
+          <Expandable title="properties">
+            <DynamicResponseField name="balance" type="number">
+              Amount of balance rolled over from a previous period.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="expires_at" type="number">
+              Timestamp when the rollover balance expires.
+            </DynamicResponseField>
+
+          </Expandable>
+        </DynamicResponseField>
+
+      </Expandable>
+    </DynamicResponseField>
 
   </Expandable>
 </DynamicResponseField>
@@ -521,3 +731,74 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
 <DynamicResponseField name="total" type="number">
   Total number of items returned in the current page
 </DynamicResponseField>
+
+
+<ResponseExample>
+```json 200
+{
+  "list": [
+    {
+      "id": "2ee25a41-0d81-4ad2-8451-ec1aadaefe58",
+      "name": "Patrick",
+      "email": "patrick@useautumn.com",
+      "createdAt": 1771409161016,
+      "fingerprint": null,
+      "stripeId": "cus_U0BKxpq1mFhuJO",
+      "env": "sandbox",
+      "metadata": {},
+      "sendEmailReceipts": false,
+      "subscriptions": [
+        {
+          "planId": "pro_plan",
+          "autoEnable": true,
+          "addOn": false,
+          "status": "active",
+          "pastDue": false,
+          "canceledAt": null,
+          "expiresAt": null,
+          "trialEndsAt": null,
+          "startedAt": 1771431921437,
+          "currentPeriodStart": 1771431921437,
+          "currentPeriodEnd": 1771999921437,
+          "quantity": 1
+        }
+      ],
+      "purchases": [],
+      "balances": {
+        "messages": {
+          "featureId": "messages",
+          "granted": 100,
+          "remaining": 0,
+          "usage": 100,
+          "unlimited": false,
+          "overageAllowed": false,
+          "maxPurchase": null,
+          "nextResetAt": 1773851121437,
+          "breakdown": [
+            {
+              "id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
+              "planId": "pro_plan",
+              "includedGrant": 100,
+              "prepaidGrant": 0,
+              "remaining": 0,
+              "usage": 100,
+              "unlimited": false,
+              "reset": {
+                "interval": "month",
+                "resetsAt": 1773851121437
+              },
+              "price": null,
+              "expiresAt": null
+            }
+          ]
+        }
+      }
+    }
+  ],
+  "has_more": false,
+  "offset": 0,
+  "total": 1,
+  "limit": 10
+}
+```
+</ResponseExample>

apps/docs/mintlify/api-reference/customers/updateCustomer.mdx

@@ -81,8 +81,10 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
 </DynamicResponseField>
 
 <DynamicResponseField name="subscriptions" type="object[]">
+  Active and scheduled recurring plans that this customer has attached.
   <Expandable title="properties">
     <DynamicResponseField name="plan" type="object">
+      The full plan object if expanded.
       <Expandable title="properties">
         <DynamicResponseField name="id" type="string" />
 
@@ -273,36 +275,62 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
       </Expandable>
     </DynamicResponseField>
 
-    <DynamicResponseField name="plan_id" type="string" />
+    <DynamicResponseField name="plan_id" type="string">
+      The unique identifier of the subscribed plan.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="auto_enable" type="boolean" />
+    <DynamicResponseField name="auto_enable" type="boolean">
+      Whether the plan was automatically enabled for the customer.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="add_on" type="boolean" />
+    <DynamicResponseField name="add_on" type="boolean">
+      Whether this is an add-on plan rather than a base subscription.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="status" type="'active' | 'scheduled' | 'expired'" />
+    <DynamicResponseField name="status" type="'active' | 'scheduled'">
+      Current status of the subscription.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="past_due" type="boolean" />
+    <DynamicResponseField name="past_due" type="boolean">
+      Whether the subscription has overdue payments.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="canceled_at" type="number | null" />
+    <DynamicResponseField name="canceled_at" type="number | null">
+      Timestamp when the subscription was canceled, or null if not canceled.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="expires_at" type="number | null" />
+    <DynamicResponseField name="expires_at" type="number | null">
+      Timestamp when the subscription will expire, or null if no expiry set.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="trial_ends_at" type="number | null" />
+    <DynamicResponseField name="trial_ends_at" type="number | null">
+      Timestamp when the trial period ends, or null if not on trial.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="started_at" type="number" />
+    <DynamicResponseField name="started_at" type="number">
+      Timestamp when the subscription started.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="current_period_start" type="number | null" />
+    <DynamicResponseField name="current_period_start" type="number | null">
+      Start timestamp of the current billing period.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="current_period_end" type="number | null" />
+    <DynamicResponseField name="current_period_end" type="number | null">
+      End timestamp of the current billing period.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="quantity" type="number" />
+    <DynamicResponseField name="quantity" type="number">
+      Number of units of this subscription (for per-seat plans).
+    </DynamicResponseField>
 
   </Expandable>
 </DynamicResponseField>
 
 <DynamicResponseField name="purchases" type="object[]">
+  One-time purchases made by the customer.
   <Expandable title="properties">
     <DynamicResponseField name="plan" type="object">
+      The full plan object if expanded.
       <Expandable title="properties">
         <DynamicResponseField name="id" type="string" />
 
@@ -493,15 +521,260 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
       </Expandable>
     </DynamicResponseField>
 
-    <DynamicResponseField name="plan_id" type="string" />
+    <DynamicResponseField name="plan_id" type="string">
+      The unique identifier of the purchased plan.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="expires_at" type="number | null" />
+    <DynamicResponseField name="expires_at" type="number | null">
+      Timestamp when the purchase expires, or null for lifetime access.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="started_at" type="number" />
+    <DynamicResponseField name="started_at" type="number">
+      Timestamp when the purchase was made.
+    </DynamicResponseField>
 
-    <DynamicResponseField name="quantity" type="number" />
+    <DynamicResponseField name="quantity" type="number">
+      Number of units purchased.
+    </DynamicResponseField>
 
   </Expandable>
 </DynamicResponseField>
 
-<DynamicResponseField name="balances" type="object" />
+<DynamicResponseField name="balances.{key}" type="object">
+  Feature balances keyed by feature ID, showing usage limits and remaining amounts.
+  <Expandable title="properties">
+    <DynamicResponseField name="feature_id" type="string">
+      The feature ID this balance is for.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="feature" type="object">
+      The full feature object if expanded.
+      <Expandable title="properties">
+        <DynamicResponseField name="id" type="string" />
+
+        <DynamicResponseField name="name" type="string" />
+
+        <DynamicResponseField name="type" type="'boolean' | 'metered' | 'credit_system'" />
+
+        <DynamicResponseField name="consumable" type="boolean" />
+
+        <DynamicResponseField name="event_names" type="string[]" />
+
+        <DynamicResponseField name="credit_schema" type="object[]">
+          <Expandable title="properties">
+            <DynamicResponseField name="metered_feature_id" type="string" />
+
+            <DynamicResponseField name="credit_cost" type="number" />
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="display" type="object">
+          <Expandable title="properties">
+            <DynamicResponseField name="singular" type="string | null" />
+
+            <DynamicResponseField name="plural" type="string | null" />
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="archived" type="boolean" />
+
+      </Expandable>
+    </DynamicResponseField>
+
+    <DynamicResponseField name="granted" type="number">
+      Total balance granted (included + prepaid).
+    </DynamicResponseField>
+
+    <DynamicResponseField name="remaining" type="number">
+      Remaining balance available for use.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="usage" type="number">
+      Total usage consumed in the current period.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="unlimited" type="boolean">
+      Whether this feature has unlimited usage.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="overage_allowed" type="boolean">
+      Whether usage beyond the granted balance is allowed (with overage charges).
+    </DynamicResponseField>
+
+    <DynamicResponseField name="max_purchase" type="number | null">
+      Maximum quantity that can be purchased as a top-up, or null for unlimited.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="next_reset_at" type="number | null">
+      Timestamp when the balance will reset, or null for no reset.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="breakdown" type="object[]">
+      Detailed breakdown of balance sources when stacking multiple plans or grants.
+      <Expandable title="properties">
+        <DynamicResponseField name="id" type="string">
+          The unique identifier for this balance breakdown.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="plan_id" type="string | null">
+          The plan ID this balance originates from, or null for standalone balances.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="included_grant" type="number">
+          Amount granted from the plan's included usage.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="prepaid_grant" type="number">
+          Amount granted from prepaid purchases or top-ups.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="remaining" type="number">
+          Remaining balance available for use.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="usage" type="number">
+          Amount consumed in the current period.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="unlimited" type="boolean">
+          Whether this balance has unlimited usage.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="reset" type="object | null">
+          Reset configuration for this balance, or null if no reset.
+          <Expandable title="properties">
+            <DynamicResponseField name="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
+              The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="interval_count" type="number">
+              Number of intervals between resets (eg. 2 for bi-monthly).
+            </DynamicResponseField>
+
+            <DynamicResponseField name="resets_at" type="number | null">
+              Timestamp when the balance will next reset.
+            </DynamicResponseField>
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="price" type="object | null">
+          Pricing configuration if this balance has usage-based pricing.
+          <Expandable title="properties">
+            <DynamicResponseField name="amount" type="number">
+              The per-unit price amount.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="tiers" type="object[]">
+              Tiered pricing configuration if applicable.
+              <Expandable title="properties">
+                <DynamicResponseField name="to" type="number" />
+
+                <DynamicResponseField name="amount" type="number" />
+
+              </Expandable>
+            </DynamicResponseField>
+
+            <DynamicResponseField name="billing_units" type="number">
+              The number of units per billing increment (eg. $9 / 250 units).
+            </DynamicResponseField>
+
+            <DynamicResponseField name="billing_method" type="'prepaid' | 'usage_based'">
+              Whether usage is prepaid or billed pay-per-use.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="max_purchase" type="number | null">
+              Maximum quantity that can be purchased, or null for unlimited.
+            </DynamicResponseField>
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="expires_at" type="number | null">
+          Timestamp when this balance expires, or null for no expiration.
+        </DynamicResponseField>
+
+      </Expandable>
+    </DynamicResponseField>
+
+    <DynamicResponseField name="rollovers" type="object[]">
+      Rollover balances carried over from previous periods.
+      <Expandable title="properties">
+        <DynamicResponseField name="balance" type="number">
+          Amount of balance rolled over from a previous period.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="expires_at" type="number">
+          Timestamp when the rollover balance expires.
+        </DynamicResponseField>
+
+      </Expandable>
+    </DynamicResponseField>
+
+  </Expandable>
+</DynamicResponseField>
+
+
+<ResponseExample>
+```json 200
+{
+  "id": "2ee25a41-0d81-4ad2-8451-ec1aadaefe58",
+  "name": "Patrick",
+  "email": "patrick@useautumn.com",
+  "createdAt": 1771409161016,
+  "fingerprint": null,
+  "stripeId": "cus_U0BKxpq1mFhuJO",
+  "env": "sandbox",
+  "metadata": {},
+  "sendEmailReceipts": false,
+  "subscriptions": [
+    {
+      "planId": "pro_plan",
+      "autoEnable": true,
+      "addOn": false,
+      "status": "active",
+      "pastDue": false,
+      "canceledAt": null,
+      "expiresAt": null,
+      "trialEndsAt": null,
+      "startedAt": 1771431921437,
+      "currentPeriodStart": 1771431921437,
+      "currentPeriodEnd": 1771999921437,
+      "quantity": 1
+    }
+  ],
+  "purchases": [],
+  "balances": {
+    "messages": {
+      "featureId": "messages",
+      "granted": 100,
+      "remaining": 0,
+      "usage": 100,
+      "unlimited": false,
+      "overageAllowed": false,
+      "maxPurchase": null,
+      "nextResetAt": 1773851121437,
+      "breakdown": [
+        {
+          "id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
+          "planId": "pro_plan",
+          "includedGrant": 100,
+          "prepaidGrant": 0,
+          "remaining": 0,
+          "usage": 100,
+          "unlimited": false,
+          "reset": {
+            "interval": "month",
+            "resetsAt": 1773851121437
+          },
+          "price": null,
+          "expiresAt": null
+        }
+      ]
+    }
+  }
+}
+```
+</ResponseExample>

apps/docs/mintlify/api-reference/entities/create-entity.mdx

@@ -1,8 +0,0 @@
----
-title: "Create an entity"
-openapi: "openapi-1.2.0 POST /customers/{customer_id}/entities"
----
-
-<Check>
-  You can create multiple entities at once by passing an array of entities.
-</Check>

apps/docs/mintlify/api-reference/entities/createEntity.mdx

@@ -0,0 +1,821 @@
+---
+title: "Create Entity"
+openapi: "openapi POST /v1/entities.create"
+---
+
+import { DynamicParamField } from "/components/dynamic-param-field.jsx";
+import { DynamicResponseField } from "/components/dynamic-response-field.jsx";
+import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";
+
+### Body Parameters
+
+<DynamicParamField body="name" type="string | null">
+  The name of the entity
+</DynamicParamField>
+
+<DynamicParamField body="feature_id" type="string" required>
+  The ID of the feature this entity is associated with
+</DynamicParamField>
+
+<DynamicParamField body="customer_data" type="object">
+  Customer attributes used to resolve the customer when customer_id is not provided.
+  <Expandable title="properties">
+    <DynamicParamField body="name" type="string | null">
+      Customer's name
+    </DynamicParamField>
+
+    <DynamicParamField body="email" type="string | null">
+      Customer's email address
+    </DynamicParamField>
+
+    <DynamicParamField body="fingerprint" type="string | null">
+      Unique identifier (eg, serial number) to detect duplicate customers and prevent free trial abuse
+    </DynamicParamField>
+
+    <DynamicParamField body="metadata" type="object | null">
+      Additional metadata for the customer
+    </DynamicParamField>
+
+    <DynamicParamField body="stripe_id" type="string | null">
+      Stripe customer ID if you already have one
+    </DynamicParamField>
+
+    <DynamicParamField body="create_in_stripe" type="boolean">
+      Whether to create the customer in Stripe
+    </DynamicParamField>
+
+    <DynamicParamField body="auto_enable_plan_id" type="string">
+      The ID of the free plan to auto-enable for the customer
+    </DynamicParamField>
+
+    <DynamicParamField body="send_email_receipts" type="boolean">
+      Whether to send email receipts to this customer
+    </DynamicParamField>
+
+  </Expandable>
+</DynamicParamField>
+
+<DynamicParamField body="customer_id" type="string" required>
+  The ID of the customer to create the entity for.
+</DynamicParamField>
+
+<DynamicParamField body="entity_id" type="string" required>
+  The ID of the entity.
+</DynamicParamField>
+
+
+### Response
+
+<DynamicResponseField name="autumn_id" type="string" />
+
+<DynamicResponseField name="id" type="string | null">
+  The unique identifier of the entity
+</DynamicResponseField>
+
+<DynamicResponseField name="name" type="string | null">
+  The name of the entity
+</DynamicResponseField>
+
+<DynamicResponseField name="customer_id" type="string | null">
+  The customer ID this entity belongs to
+</DynamicResponseField>
+
+<DynamicResponseField name="feature_id" type="string | null">
+  The feature ID this entity belongs to
+</DynamicResponseField>
+
+<DynamicResponseField name="created_at" type="number">
+  Unix timestamp when the entity was created
+</DynamicResponseField>
+
+<DynamicResponseField name="env" type="'sandbox' | 'live'">
+  The environment (sandbox/live)
+</DynamicResponseField>
+
+<DynamicResponseField name="subscriptions" type="object[]">
+  <Expandable title="properties">
+    <DynamicResponseField name="plan" type="object">
+      The full plan object if expanded.
+      <Expandable title="properties">
+        <DynamicResponseField name="id" type="string" />
+
+        <DynamicResponseField name="name" type="string" />
+
+        <DynamicResponseField name="description" type="string | null" />
+
+        <DynamicResponseField name="group" type="string | null" />
+
+        <DynamicResponseField name="version" type="number" />
+
+        <DynamicResponseField name="add_on" type="boolean" />
+
+        <DynamicResponseField name="auto_enable" type="boolean" />
+
+        <DynamicResponseField name="price" type="object | null">
+          <Expandable title="properties">
+            <DynamicResponseField name="amount" type="number" />
+
+            <DynamicResponseField name="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" />
+
+            <DynamicResponseField name="interval_count" type="number" />
+
+            <DynamicResponseField name="display" type="object">
+              <Expandable title="properties">
+                <DynamicResponseField name="primary_text" type="string" />
+
+                <DynamicResponseField name="secondary_text" type="string" />
+
+              </Expandable>
+            </DynamicResponseField>
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="items" type="object[]">
+          <Expandable title="properties">
+            <DynamicResponseField name="feature_id" type="string" />
+
+            <DynamicResponseField name="feature" type="object">
+              <Expandable title="properties">
+                <DynamicResponseField name="id" type="string">
+                  The ID of the feature, used to refer to it in other API calls like /track or /check.
+                </DynamicResponseField>
+
+                <DynamicResponseField name="name" type="string | null">
+                  The name of the feature.
+                </DynamicResponseField>
+
+                <DynamicResponseField name="type" type="'static' | 'boolean' | 'single_use' | 'continuous_use' | 'credit_system'">
+                  The type of the feature
+                </DynamicResponseField>
+
+                <DynamicResponseField name="display" type="object | null">
+                  Singular and plural display names for the feature.
+                  <Expandable title="properties">
+                    <DynamicResponseField name="singular" type="string">
+                      The singular display name for the feature.
+                    </DynamicResponseField>
+
+                    <DynamicResponseField name="plural" type="string">
+                      The plural display name for the feature.
+                    </DynamicResponseField>
+
+                  </Expandable>
+                </DynamicResponseField>
+
+                <DynamicResponseField name="credit_schema" type="object[] | null">
+                  Credit cost schema for credit system features.
+                  <Expandable title="properties">
+                    <DynamicResponseField name="metered_feature_id" type="string">
+                      The ID of the metered feature (should be a single_use feature).
+                    </DynamicResponseField>
+
+                    <DynamicResponseField name="credit_cost" type="number">
+                      The credit cost of the metered feature.
+                    </DynamicResponseField>
+
+                  </Expandable>
+                </DynamicResponseField>
+
+                <DynamicResponseField name="archived" type="boolean | null">
+                  Whether or not the feature is archived.
+                </DynamicResponseField>
+
+              </Expandable>
+            </DynamicResponseField>
+
+            <DynamicResponseField name="included" type="number" />
+
+            <DynamicResponseField name="unlimited" type="boolean" />
+
+            <DynamicResponseField name="reset" type="object | null">
+              <Expandable title="properties">
+                <DynamicResponseField name="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" />
+
+                <DynamicResponseField name="interval_count" type="number" />
+
+              </Expandable>
+            </DynamicResponseField>
+
+            <DynamicResponseField name="price" type="object | null">
+              <Expandable title="properties">
+                <DynamicResponseField name="amount" type="number" />
+
+                <DynamicResponseField name="tiers" type="object[]">
+                  <Expandable title="properties">
+                    <DynamicResponseField name="to" type="number" />
+
+                    <DynamicResponseField name="amount" type="number" />
+
+                  </Expandable>
+                </DynamicResponseField>
+
+                <DynamicResponseField name="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" />
+
+                <DynamicResponseField name="interval_count" type="number" />
+
+                <DynamicResponseField name="billing_units" type="number" />
+
+                <DynamicResponseField name="billing_method" type="'prepaid' | 'usage_based'" />
+
+                <DynamicResponseField name="max_purchase" type="number | null" />
+
+              </Expandable>
+            </DynamicResponseField>
+
+            <DynamicResponseField name="display" type="object">
+              <Expandable title="properties">
+                <DynamicResponseField name="primary_text" type="string" />
+
+                <DynamicResponseField name="secondary_text" type="string" />
+
+              </Expandable>
+            </DynamicResponseField>
+
+            <DynamicResponseField name="rollover" type="object">
+              <Expandable title="properties">
+                <DynamicResponseField name="max" type="number | null" />
+
+                <DynamicResponseField name="expiry_duration_type" type="'month' | 'forever'" />
+
+                <DynamicResponseField name="expiry_duration_length" type="number" />
+
+              </Expandable>
+            </DynamicResponseField>
+
+            <DynamicResponseField name="proration" type="object">
+              <Expandable title="properties">
+                <DynamicResponseField name="on_increase" type="'bill_immediately' | 'prorate_immediately' | 'prorate_next_cycle' | 'bill_next_cycle'" />
+
+                <DynamicResponseField name="on_decrease" type="'prorate' | 'prorate_immediately' | 'prorate_next_cycle' | 'none' | 'no_prorations'" />
+
+              </Expandable>
+            </DynamicResponseField>
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="free_trial" type="object">
+          <Expandable title="properties">
+            <DynamicResponseField name="duration_length" type="number" />
+
+            <DynamicResponseField name="duration_type" type="'day' | 'month' | 'year'" />
+
+            <DynamicResponseField name="card_required" type="boolean" />
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="created_at" type="number" />
+
+        <DynamicResponseField name="env" type="'sandbox' | 'live'" />
+
+        <DynamicResponseField name="archived" type="boolean" />
+
+        <DynamicResponseField name="base_variant_id" type="string | null" />
+
+        <DynamicResponseField name="customer_eligibility" type="object">
+          <Expandable title="properties">
+            <DynamicResponseField name="trial_available" type="boolean" />
+
+            <DynamicResponseField name="scenario" type="'scheduled' | 'active' | 'new' | 'renew' | 'upgrade' | 'downgrade' | 'cancel' | 'expired' | 'past_due'" />
+
+          </Expandable>
+        </DynamicResponseField>
+
+      </Expandable>
+    </DynamicResponseField>
+
+    <DynamicResponseField name="plan_id" type="string">
+      The unique identifier of the subscribed plan.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="auto_enable" type="boolean">
+      Whether the plan was automatically enabled for the customer.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="add_on" type="boolean">
+      Whether this is an add-on plan rather than a base subscription.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="status" type="'active' | 'scheduled'">
+      Current status of the subscription.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="past_due" type="boolean">
+      Whether the subscription has overdue payments.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="canceled_at" type="number | null">
+      Timestamp when the subscription was canceled, or null if not canceled.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="expires_at" type="number | null">
+      Timestamp when the subscription will expire, or null if no expiry set.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="trial_ends_at" type="number | null">
+      Timestamp when the trial period ends, or null if not on trial.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="started_at" type="number">
+      Timestamp when the subscription started.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="current_period_start" type="number | null">
+      Start timestamp of the current billing period.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="current_period_end" type="number | null">
+      End timestamp of the current billing period.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="quantity" type="number">
+      Number of units of this subscription (for per-seat plans).
+    </DynamicResponseField>
+
+  </Expandable>
+</DynamicResponseField>
+
+<DynamicResponseField name="purchases" type="object[]">
+  <Expandable title="properties">
+    <DynamicResponseField name="plan" type="object">
+      The full plan object if expanded.
+      <Expandable title="properties">
+        <DynamicResponseField name="id" type="string" />
+
+        <DynamicResponseField name="name" type="string" />
+
+        <DynamicResponseField name="description" type="string | null" />
+
+        <DynamicResponseField name="group" type="string | null" />
+
+        <DynamicResponseField name="version" type="number" />
+
+        <DynamicResponseField name="add_on" type="boolean" />
+
+        <DynamicResponseField name="auto_enable" type="boolean" />
+
+        <DynamicResponseField name="price" type="object | null">
+          <Expandable title="properties">
+            <DynamicResponseField name="amount" type="number" />
+
+            <DynamicResponseField name="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" />
+
+            <DynamicResponseField name="interval_count" type="number" />
+
+            <DynamicResponseField name="display" type="object">
+              <Expandable title="properties">
+                <DynamicResponseField name="primary_text" type="string" />
+
+                <DynamicResponseField name="secondary_text" type="string" />
+
+              </Expandable>
+            </DynamicResponseField>
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="items" type="object[]">
+          <Expandable title="properties">
+            <DynamicResponseField name="feature_id" type="string" />
+
+            <DynamicResponseField name="feature" type="object">
+              <Expandable title="properties">
+                <DynamicResponseField name="id" type="string">
+                  The ID of the feature, used to refer to it in other API calls like /track or /check.
+                </DynamicResponseField>
+
+                <DynamicResponseField name="name" type="string | null">
+                  The name of the feature.
+                </DynamicResponseField>
+
+                <DynamicResponseField name="type" type="'static' | 'boolean' | 'single_use' | 'continuous_use' | 'credit_system'">
+                  The type of the feature
+                </DynamicResponseField>
+
+                <DynamicResponseField name="display" type="object | null">
+                  Singular and plural display names for the feature.
+                  <Expandable title="properties">
+                    <DynamicResponseField name="singular" type="string">
+                      The singular display name for the feature.
+                    </DynamicResponseField>
+
+                    <DynamicResponseField name="plural" type="string">
+                      The plural display name for the feature.
+                    </DynamicResponseField>
+
+                  </Expandable>
+                </DynamicResponseField>
+
+                <DynamicResponseField name="credit_schema" type="object[] | null">
+                  Credit cost schema for credit system features.
+                  <Expandable title="properties">
+                    <DynamicResponseField name="metered_feature_id" type="string">
+                      The ID of the metered feature (should be a single_use feature).
+                    </DynamicResponseField>
+
+                    <DynamicResponseField name="credit_cost" type="number">
+                      The credit cost of the metered feature.
+                    </DynamicResponseField>
+
+                  </Expandable>
+                </DynamicResponseField>
+
+                <DynamicResponseField name="archived" type="boolean | null">
+                  Whether or not the feature is archived.
+                </DynamicResponseField>
+
+              </Expandable>
+            </DynamicResponseField>
+
+            <DynamicResponseField name="included" type="number" />
+
+            <DynamicResponseField name="unlimited" type="boolean" />
+
+            <DynamicResponseField name="reset" type="object | null">
+              <Expandable title="properties">
+                <DynamicResponseField name="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" />
+
+                <DynamicResponseField name="interval_count" type="number" />
+
+              </Expandable>
+            </DynamicResponseField>
+
+            <DynamicResponseField name="price" type="object | null">
+              <Expandable title="properties">
+                <DynamicResponseField name="amount" type="number" />
+
+                <DynamicResponseField name="tiers" type="object[]">
+                  <Expandable title="properties">
+                    <DynamicResponseField name="to" type="number" />
+
+                    <DynamicResponseField name="amount" type="number" />
+
+                  </Expandable>
+                </DynamicResponseField>
+
+                <DynamicResponseField name="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" />
+
+                <DynamicResponseField name="interval_count" type="number" />
+
+                <DynamicResponseField name="billing_units" type="number" />
+
+                <DynamicResponseField name="billing_method" type="'prepaid' | 'usage_based'" />
+
+                <DynamicResponseField name="max_purchase" type="number | null" />
+
+              </Expandable>
+            </DynamicResponseField>
+
+            <DynamicResponseField name="display" type="object">
+              <Expandable title="properties">
+                <DynamicResponseField name="primary_text" type="string" />
+
+                <DynamicResponseField name="secondary_text" type="string" />
+
+              </Expandable>
+            </DynamicResponseField>
+
+            <DynamicResponseField name="rollover" type="object">
+              <Expandable title="properties">
+                <DynamicResponseField name="max" type="number | null" />
+
+                <DynamicResponseField name="expiry_duration_type" type="'month' | 'forever'" />
+
+                <DynamicResponseField name="expiry_duration_length" type="number" />
+
+              </Expandable>
+            </DynamicResponseField>
+
+            <DynamicResponseField name="proration" type="object">
+              <Expandable title="properties">
+                <DynamicResponseField name="on_increase" type="'bill_immediately' | 'prorate_immediately' | 'prorate_next_cycle' | 'bill_next_cycle'" />
+
+                <DynamicResponseField name="on_decrease" type="'prorate' | 'prorate_immediately' | 'prorate_next_cycle' | 'none' | 'no_prorations'" />
+
+              </Expandable>
+            </DynamicResponseField>
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="free_trial" type="object">
+          <Expandable title="properties">
+            <DynamicResponseField name="duration_length" type="number" />
+
+            <DynamicResponseField name="duration_type" type="'day' | 'month' | 'year'" />
+
+            <DynamicResponseField name="card_required" type="boolean" />
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="created_at" type="number" />
+
+        <DynamicResponseField name="env" type="'sandbox' | 'live'" />
+
+        <DynamicResponseField name="archived" type="boolean" />
+
+        <DynamicResponseField name="base_variant_id" type="string | null" />
+
+        <DynamicResponseField name="customer_eligibility" type="object">
+          <Expandable title="properties">
+            <DynamicResponseField name="trial_available" type="boolean" />
+
+            <DynamicResponseField name="scenario" type="'scheduled' | 'active' | 'new' | 'renew' | 'upgrade' | 'downgrade' | 'cancel' | 'expired' | 'past_due'" />
+
+          </Expandable>
+        </DynamicResponseField>
+
+      </Expandable>
+    </DynamicResponseField>
+
+    <DynamicResponseField name="plan_id" type="string">
+      The unique identifier of the purchased plan.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="expires_at" type="number | null">
+      Timestamp when the purchase expires, or null for lifetime access.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="started_at" type="number">
+      Timestamp when the purchase was made.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="quantity" type="number">
+      Number of units purchased.
+    </DynamicResponseField>
+
+  </Expandable>
+</DynamicResponseField>
+
+<DynamicResponseField name="balances.{key}" type="object">
+  <Expandable title="properties">
+    <DynamicResponseField name="feature_id" type="string">
+      The feature ID this balance is for.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="feature" type="object">
+      The full feature object if expanded.
+      <Expandable title="properties">
+        <DynamicResponseField name="id" type="string" />
+
+        <DynamicResponseField name="name" type="string" />
+
+        <DynamicResponseField name="type" type="'boolean' | 'metered' | 'credit_system'" />
+
+        <DynamicResponseField name="consumable" type="boolean" />
+
+        <DynamicResponseField name="event_names" type="string[]" />
+
+        <DynamicResponseField name="credit_schema" type="object[]">
+          <Expandable title="properties">
+            <DynamicResponseField name="metered_feature_id" type="string" />
+
+            <DynamicResponseField name="credit_cost" type="number" />
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="display" type="object">
+          <Expandable title="properties">
+            <DynamicResponseField name="singular" type="string | null" />
+
+            <DynamicResponseField name="plural" type="string | null" />
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="archived" type="boolean" />
+
+      </Expandable>
+    </DynamicResponseField>
+
+    <DynamicResponseField name="granted" type="number">
+      Total balance granted (included + prepaid).
+    </DynamicResponseField>
+
+    <DynamicResponseField name="remaining" type="number">
+      Remaining balance available for use.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="usage" type="number">
+      Total usage consumed in the current period.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="unlimited" type="boolean">
+      Whether this feature has unlimited usage.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="overage_allowed" type="boolean">
+      Whether usage beyond the granted balance is allowed (with overage charges).
+    </DynamicResponseField>
+
+    <DynamicResponseField name="max_purchase" type="number | null">
+      Maximum quantity that can be purchased as a top-up, or null for unlimited.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="next_reset_at" type="number | null">
+      Timestamp when the balance will reset, or null for no reset.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="breakdown" type="object[]">
+      Detailed breakdown of balance sources when stacking multiple plans or grants.
+      <Expandable title="properties">
+        <DynamicResponseField name="id" type="string">
+          The unique identifier for this balance breakdown.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="plan_id" type="string | null">
+          The plan ID this balance originates from, or null for standalone balances.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="included_grant" type="number">
+          Amount granted from the plan's included usage.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="prepaid_grant" type="number">
+          Amount granted from prepaid purchases or top-ups.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="remaining" type="number">
+          Remaining balance available for use.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="usage" type="number">
+          Amount consumed in the current period.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="unlimited" type="boolean">
+          Whether this balance has unlimited usage.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="reset" type="object | null">
+          Reset configuration for this balance, or null if no reset.
+          <Expandable title="properties">
+            <DynamicResponseField name="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
+              The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="interval_count" type="number">
+              Number of intervals between resets (eg. 2 for bi-monthly).
+            </DynamicResponseField>
+
+            <DynamicResponseField name="resets_at" type="number | null">
+              Timestamp when the balance will next reset.
+            </DynamicResponseField>
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="price" type="object | null">
+          Pricing configuration if this balance has usage-based pricing.
+          <Expandable title="properties">
+            <DynamicResponseField name="amount" type="number">
+              The per-unit price amount.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="tiers" type="object[]">
+              Tiered pricing configuration if applicable.
+              <Expandable title="properties">
+                <DynamicResponseField name="to" type="number" />
+
+                <DynamicResponseField name="amount" type="number" />
+
+              </Expandable>
+            </DynamicResponseField>
+
+            <DynamicResponseField name="billing_units" type="number">
+              The number of units per billing increment (eg. $9 / 250 units).
+            </DynamicResponseField>
+
+            <DynamicResponseField name="billing_method" type="'prepaid' | 'usage_based'">
+              Whether usage is prepaid or billed pay-per-use.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="max_purchase" type="number | null">
+              Maximum quantity that can be purchased, or null for unlimited.
+            </DynamicResponseField>
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="expires_at" type="number | null">
+          Timestamp when this balance expires, or null for no expiration.
+        </DynamicResponseField>
+
+      </Expandable>
+    </DynamicResponseField>
+
+    <DynamicResponseField name="rollovers" type="object[]">
+      Rollover balances carried over from previous periods.
+      <Expandable title="properties">
+        <DynamicResponseField name="balance" type="number">
+          Amount of balance rolled over from a previous period.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="expires_at" type="number">
+          Timestamp when the rollover balance expires.
+        </DynamicResponseField>
+
+      </Expandable>
+    </DynamicResponseField>
+
+  </Expandable>
+</DynamicResponseField>
+
+<DynamicResponseField name="invoices" type="object[]">
+  Invoices for this entity (only included when expand=invoices)
+  <Expandable title="properties">
+    <DynamicResponseField name="plan_ids" type="string[]">
+      Array of plan IDs included in this invoice
+    </DynamicResponseField>
+
+    <DynamicResponseField name="stripe_id" type="string">
+      The Stripe invoice ID
+    </DynamicResponseField>
+
+    <DynamicResponseField name="status" type="string">
+      The status of the invoice
+    </DynamicResponseField>
+
+    <DynamicResponseField name="total" type="number">
+      The total amount of the invoice
+    </DynamicResponseField>
+
+    <DynamicResponseField name="currency" type="string">
+      The currency code for the invoice
+    </DynamicResponseField>
+
+    <DynamicResponseField name="created_at" type="number">
+      Timestamp when the invoice was created
+    </DynamicResponseField>
+
+    <DynamicResponseField name="hosted_invoice_url" type="string | null">
+      URL to the Stripe-hosted invoice page
+    </DynamicResponseField>
+
+  </Expandable>
+</DynamicResponseField>
+
+
+<ResponseExample>
+```json 200
+{
+  "id": "seat_42",
+  "name": "Seat 42",
+  "customer_id": "cus_123",
+  "feature_id": "seats",
+  "created_at": 1771409161016,
+  "env": "sandbox",
+  "subscriptions": [
+    {
+      "plan_id": "pro_plan",
+      "auto_enable": true,
+      "add_on": false,
+      "status": "active",
+      "past_due": false,
+      "canceled_at": null,
+      "expires_at": null,
+      "trial_ends_at": null,
+      "started_at": 1771431921437,
+      "current_period_start": 1771431921437,
+      "current_period_end": 1771999921437,
+      "quantity": 1
+    }
+  ],
+  "purchases": [],
+  "balances": {
+    "messages": {
+      "feature_id": "messages",
+      "granted": 100,
+      "remaining": 72,
+      "usage": 28,
+      "unlimited": false,
+      "overage_allowed": false,
+      "max_purchase": null,
+      "next_reset_at": 1773851121437,
+      "breakdown": [
+        {
+          "id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
+          "plan_id": "pro_plan",
+          "included_grant": 100,
+          "prepaid_grant": 0,
+          "remaining": 72,
+          "usage": 28,
+          "unlimited": false,
+          "reset": {
+            "interval": "month",
+            "resets_at": 1773851121437
+          },
+          "price": null,
+          "expires_at": null
+        }
+      ]
+    }
+  },
+  "invoices": []
+}
+```
+</ResponseExample>

apps/docs/mintlify/api-reference/entities/delete-entity.mdx

@@ -1,4 +0,0 @@
----
-title: "Delete an entity"
-openapi: "openapi-1.2.0 DELETE /customers/{customer_id}/entities/{entity_id}"
----

apps/docs/mintlify/api-reference/entities/deleteEntity.mdx

@@ -0,0 +1,32 @@
+---
+title: "Delete Entity"
+openapi: "openapi POST /v1/entities.delete"
+---
+
+import { DynamicParamField } from "/components/dynamic-param-field.jsx";
+import { DynamicResponseField } from "/components/dynamic-response-field.jsx";
+import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";
+
+### Body Parameters
+
+<DynamicParamField body="customer_id" type="string">
+  The ID of the customer.
+</DynamicParamField>
+
+<DynamicParamField body="entity_id" type="string" required>
+  The ID of the entity.
+</DynamicParamField>
+
+
+### Response
+
+<DynamicResponseField name="success" type="boolean" />
+
+
+<ResponseExample>
+```json 200
+{
+  "success": true
+}
+```
+</ResponseExample>

apps/docs/mintlify/api-reference/entities/get-entity.mdx

@@ -1,8 +0,0 @@
----
-title: "Get Entity"
-openapi: "openapi-1.2.0 GET /customers/{customer_id}/entities/{entity_id}"
----
-
-<Tip>
-  To get additional data in the entity object, you can use the `expand` parameter to fetch data like invoices.
-</Tip>

apps/docs/mintlify/api-reference/entities/getEntity.mdx

@@ -1,6 +1,6 @@
 ---
-title: "Billing Preview Attach"
-openapi: "openapi POST /v1/billing.preview_attach"
+title: "Get Entity"
+openapi: "openapi POST /v1/entities.get"
 ---
 
 import { DynamicParamField } from "/components/dynamic-param-field.jsx";
@@ -9,260 +9,47 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
 
 ### Body Parameters
 
-<DynamicParamField body="customer_id" type="string" required>
-  The ID of the customer to attach the plan to.
+<DynamicParamField body="customer_id" type="string">
+  The ID of the customer to create the entity for.
 </DynamicParamField>
 
-<DynamicParamField body="entity_id" type="string | null">
-  The ID of the entity to attach the plan to.
+<DynamicParamField body="entity_id" type="string" required>
+  The ID of the entity.
 </DynamicParamField>
 
-<DynamicParamField body="feature_quantities" type="object[] | null">
-  If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan.
-  <Expandable title="properties">
-    <DynamicParamField body="feature_id" type="string" required />
-
-    <DynamicParamField body="quantity" type="number" />
-
-    <DynamicParamField body="adjustable" type="boolean" />
-
-  </Expandable>
-</DynamicParamField>
-
-<DynamicParamField body="version" type="number">
-  The version of the plan to attach.
-</DynamicParamField>
-
-<DynamicParamField body="free_trial" type="object | null">
-  <Expandable title="properties">
-    <DynamicParamField body="duration_length" type="number" required />
-
-    <DynamicParamField body="duration_type" type="'day' | 'month' | 'year'" />
-
-    <DynamicParamField body="card_required" type="boolean" />
-
-  </Expandable>
-</DynamicParamField>
-
-<DynamicParamField body="customize" type="object">
-  Customize the plan to attach. Can either override the price of the plan, the items in the plan, or both.
-  <Expandable title="properties">
-    <DynamicParamField body="price" type="object | null">
-      <Expandable title="properties">
-        <DynamicParamField body="amount" type="number" required />
-
-        <DynamicParamField body="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" required />
-
-        <DynamicParamField body="interval_count" type="number" />
-
-      </Expandable>
-    </DynamicParamField>
-
-    <DynamicParamField body="items" type="object[]">
-      <Expandable title="properties">
-        <DynamicParamField body="feature_id" type="string" required />
-
-        <DynamicParamField body="included" type="number" />
-
-        <DynamicParamField body="unlimited" type="boolean" />
-
-        <DynamicParamField body="reset" type="object">
-          <Expandable title="properties">
-            <DynamicParamField body="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" required />
-
-            <DynamicParamField body="interval_count" type="number" />
-
-          </Expandable>
-        </DynamicParamField>
-
-        <DynamicParamField body="price" type="object">
-          <Expandable title="properties">
-            <DynamicParamField body="amount" type="number" />
-
-            <DynamicParamField body="tiers" type="object[]">
-              <Expandable title="properties">
-                <DynamicParamField body="to" type="number" required />
-
-                <DynamicParamField body="amount" type="number" required />
-
-              </Expandable>
-            </DynamicParamField>
-
-            <DynamicParamField body="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" required />
-
-            <DynamicParamField body="interval_count" type="number" />
-
-            <DynamicParamField body="billing_units" type="number" />
-
-            <DynamicParamField body="billing_method" type="'prepaid' | 'usage_based'" required />
-
-            <DynamicParamField body="max_purchase" type="number" />
-
-          </Expandable>
-        </DynamicParamField>
-
-        <DynamicParamField body="proration" type="object">
-          <Expandable title="properties">
-            <DynamicParamField body="on_increase" type="'bill_immediately' | 'prorate_immediately' | 'prorate_next_cycle' | 'bill_next_cycle'" required />
-
-            <DynamicParamField body="on_decrease" type="'prorate' | 'prorate_immediately' | 'prorate_next_cycle' | 'none' | 'no_prorations'" required />
-
-          </Expandable>
-        </DynamicParamField>
-
-        <DynamicParamField body="rollover" type="object">
-          <Expandable title="properties">
-            <DynamicParamField body="max" type="number" />
-
-            <DynamicParamField body="expiry_duration_type" type="'month' | 'forever'" required />
-
-            <DynamicParamField body="expiry_duration_length" type="number" />
-
-          </Expandable>
-        </DynamicParamField>
-
-      </Expandable>
-    </DynamicParamField>
-
-  </Expandable>
-</DynamicParamField>
-
-<DynamicParamField body="plan_id" type="string" required />
-
-<DynamicParamField body="invoice_mode" type="object">
-  <Expandable title="properties">
-    <DynamicParamField body="enabled" type="boolean" required />
-
-    <DynamicParamField body="enable_plan_immediately" type="boolean" />
-
-    <DynamicParamField body="finalize" type="boolean" />
-
-  </Expandable>
-</DynamicParamField>
-
-<DynamicParamField body="discounts" type="object[]" />
-
-<DynamicParamField body="redirect_mode" type="'always' | 'if_required' | 'never'" />
-
-<DynamicParamField body="success_url" type="string" />
-
-<DynamicParamField body="new_billing_subscription" type="boolean" />
-
-<DynamicParamField body="plan_schedule" type="'immediate' | 'end_of_cycle'" />
-
-<DynamicParamField body="billing_behavior" type="'prorate_immediately' | 'next_cycle_only'" />
-
 
 ### Response
 
-<DynamicResponseField name="customer_id" type="string" />
+<DynamicResponseField name="autumn_id" type="string" />
 
-<DynamicResponseField name="line_items" type="object[]">
-  <Expandable title="properties">
-    <DynamicResponseField name="title" type="string" />
-
-    <DynamicResponseField name="description" type="string" />
-
-    <DynamicResponseField name="amount" type="number" />
-
-    <DynamicResponseField name="discounts" type="object[]">
-      <Expandable title="properties">
-        <DynamicResponseField name="amountOff" type="number" />
-
-        <DynamicResponseField name="percentOff" type="number" />
-
-        <DynamicResponseField name="stripeCouponId" type="string" />
-
-        <DynamicResponseField name="couponName" type="string" />
-
-      </Expandable>
+<DynamicResponseField name="id" type="string | null">
+  The unique identifier of the entity
 </DynamicResponseField>
 
-    <DynamicResponseField name="plan_id" type="string" />
-
-    <DynamicResponseField name="total_quantity" type="number" />
-
-    <DynamicResponseField name="paid_quantity" type="number" />
-
-    <DynamicResponseField name="deferred_for_trial" type="boolean" />
-
-    <DynamicResponseField name="effective_period" type="object">
-      <Expandable title="properties">
-        <DynamicResponseField name="start" type="number" />
-
-        <DynamicResponseField name="end" type="number" />
-
-      </Expandable>
+<DynamicResponseField name="name" type="string | null">
+  The name of the entity
 </DynamicResponseField>
 
-    <DynamicResponseField name="is_base" type="boolean" />
-
-  </Expandable>
+<DynamicResponseField name="customer_id" type="string | null">
+  The customer ID this entity belongs to
 </DynamicResponseField>
 
-<DynamicResponseField name="total" type="number" />
-
-<DynamicResponseField name="currency" type="string" />
-
-<DynamicResponseField name="period_start" type="number" />
-
-<DynamicResponseField name="period_end" type="number" />
-
-<DynamicResponseField name="next_cycle" type="object">
-  <Expandable title="properties">
-    <DynamicResponseField name="starts_at" type="number" />
-
-    <DynamicResponseField name="total" type="number" />
-
-    <DynamicResponseField name="line_items" type="object[]">
-      <Expandable title="properties">
-        <DynamicResponseField name="title" type="string" />
-
-        <DynamicResponseField name="description" type="string" />
-
-        <DynamicResponseField name="amount" type="number" />
-
-        <DynamicResponseField name="discounts" type="object[]">
-          <Expandable title="properties">
-            <DynamicResponseField name="amountOff" type="number" />
-
-            <DynamicResponseField name="percentOff" type="number" />
-
-            <DynamicResponseField name="stripeCouponId" type="string" />
-
-            <DynamicResponseField name="couponName" type="string" />
-
-          </Expandable>
+<DynamicResponseField name="feature_id" type="string | null">
+  The feature ID this entity belongs to
 </DynamicResponseField>
 
-        <DynamicResponseField name="plan_id" type="string" />
-
-        <DynamicResponseField name="total_quantity" type="number" />
-
-        <DynamicResponseField name="paid_quantity" type="number" />
-
-        <DynamicResponseField name="deferred_for_trial" type="boolean" />
-
-        <DynamicResponseField name="effective_period" type="object">
-          <Expandable title="properties">
-            <DynamicResponseField name="start" type="number" />
-
-            <DynamicResponseField name="end" type="number" />
-
-          </Expandable>
+<DynamicResponseField name="created_at" type="number">
+  Unix timestamp when the entity was created
 </DynamicResponseField>
 
-        <DynamicResponseField name="is_base" type="boolean" />
-
-      </Expandable>
+<DynamicResponseField name="env" type="'sandbox' | 'live'">
+  The environment (sandbox/live)
 </DynamicResponseField>
 
-  </Expandable>
-</DynamicResponseField>
-
-<DynamicResponseField name="incoming" type="object[]">
+<DynamicResponseField name="subscriptions" type="object[]">
   <Expandable title="properties">
     <DynamicResponseField name="plan" type="object">
+      The full plan object if expanded.
       <Expandable title="properties">
         <DynamicResponseField name="id" type="string" />
 
@@ -453,27 +240,61 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
       </Expandable>
     </DynamicResponseField>
 
-    <DynamicResponseField name="feature_quantities" type="object[]">
-      <Expandable title="properties">
-        <DynamicResponseField name="feature_id" type="string" />
+    <DynamicResponseField name="plan_id" type="string">
+      The unique identifier of the subscribed plan.
+    </DynamicResponseField>
 
-        <DynamicResponseField name="quantity" type="number" />
+    <DynamicResponseField name="auto_enable" type="boolean">
+      Whether the plan was automatically enabled for the customer.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="add_on" type="boolean">
+      Whether this is an add-on plan rather than a base subscription.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="status" type="'active' | 'scheduled'">
+      Current status of the subscription.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="past_due" type="boolean">
+      Whether the subscription has overdue payments.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="canceled_at" type="number | null">
+      Timestamp when the subscription was canceled, or null if not canceled.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="expires_at" type="number | null">
+      Timestamp when the subscription will expire, or null if no expiry set.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="trial_ends_at" type="number | null">
+      Timestamp when the trial period ends, or null if not on trial.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="started_at" type="number">
+      Timestamp when the subscription started.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="current_period_start" type="number | null">
+      Start timestamp of the current billing period.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="current_period_end" type="number | null">
+      End timestamp of the current billing period.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="quantity" type="number">
+      Number of units of this subscription (for per-seat plans).
+    </DynamicResponseField>
 
   </Expandable>
 </DynamicResponseField>
 
-    <DynamicResponseField name="balances" type="object" />
-
-    <DynamicResponseField name="period_start" type="number" />
-
-    <DynamicResponseField name="period_end" type="number" />
-
-  </Expandable>
-</DynamicResponseField>
-
-<DynamicResponseField name="outgoing" type="object[]">
+<DynamicResponseField name="purchases" type="object[]">
   <Expandable title="properties">
     <DynamicResponseField name="plan" type="object">
+      The full plan object if expanded.
       <Expandable title="properties">
         <DynamicResponseField name="id" type="string" />
 
@@ -664,22 +485,291 @@ import { DynamicResponseExample } from "/components/dynamic-response-example.jsx
       </Expandable>
     </DynamicResponseField>
 
-    <DynamicResponseField name="feature_quantities" type="object[]">
+    <DynamicResponseField name="plan_id" type="string">
+      The unique identifier of the purchased plan.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="expires_at" type="number | null">
+      Timestamp when the purchase expires, or null for lifetime access.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="started_at" type="number">
+      Timestamp when the purchase was made.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="quantity" type="number">
+      Number of units purchased.
+    </DynamicResponseField>
+
+  </Expandable>
+</DynamicResponseField>
+
+<DynamicResponseField name="balances.{key}" type="object">
   <Expandable title="properties">
-        <DynamicResponseField name="feature_id" type="string" />
+    <DynamicResponseField name="feature_id" type="string">
+      The feature ID this balance is for.
+    </DynamicResponseField>
 
-        <DynamicResponseField name="quantity" type="number" />
+    <DynamicResponseField name="feature" type="object">
+      The full feature object if expanded.
+      <Expandable title="properties">
+        <DynamicResponseField name="id" type="string" />
+
+        <DynamicResponseField name="name" type="string" />
+
+        <DynamicResponseField name="type" type="'boolean' | 'metered' | 'credit_system'" />
+
+        <DynamicResponseField name="consumable" type="boolean" />
+
+        <DynamicResponseField name="event_names" type="string[]" />
+
+        <DynamicResponseField name="credit_schema" type="object[]">
+          <Expandable title="properties">
+            <DynamicResponseField name="metered_feature_id" type="string" />
+
+            <DynamicResponseField name="credit_cost" type="number" />
 
           </Expandable>
         </DynamicResponseField>
 
-    <DynamicResponseField name="balances" type="object" />
+        <DynamicResponseField name="display" type="object">
+          <Expandable title="properties">
+            <DynamicResponseField name="singular" type="string | null" />
 
-    <DynamicResponseField name="period_start" type="number" />
-
-    <DynamicResponseField name="period_end" type="number" />
+            <DynamicResponseField name="plural" type="string | null" />
 
           </Expandable>
         </DynamicResponseField>
 
-<DynamicResponseField name="redirect_type" type="'stripe_checkout' | 'autumn_checkout'" />
+        <DynamicResponseField name="archived" type="boolean" />
+
+      </Expandable>
+    </DynamicResponseField>
+
+    <DynamicResponseField name="granted" type="number">
+      Total balance granted (included + prepaid).
+    </DynamicResponseField>
+
+    <DynamicResponseField name="remaining" type="number">
+      Remaining balance available for use.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="usage" type="number">
+      Total usage consumed in the current period.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="unlimited" type="boolean">
+      Whether this feature has unlimited usage.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="overage_allowed" type="boolean">
+      Whether usage beyond the granted balance is allowed (with overage charges).
+    </DynamicResponseField>
+
+    <DynamicResponseField name="max_purchase" type="number | null">
+      Maximum quantity that can be purchased as a top-up, or null for unlimited.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="next_reset_at" type="number | null">
+      Timestamp when the balance will reset, or null for no reset.
+    </DynamicResponseField>
+
+    <DynamicResponseField name="breakdown" type="object[]">
+      Detailed breakdown of balance sources when stacking multiple plans or grants.
+      <Expandable title="properties">
+        <DynamicResponseField name="id" type="string">
+          The unique identifier for this balance breakdown.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="plan_id" type="string | null">
+          The plan ID this balance originates from, or null for standalone balances.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="included_grant" type="number">
+          Amount granted from the plan's included usage.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="prepaid_grant" type="number">
+          Amount granted from prepaid purchases or top-ups.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="remaining" type="number">
+          Remaining balance available for use.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="usage" type="number">
+          Amount consumed in the current period.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="unlimited" type="boolean">
+          Whether this balance has unlimited usage.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="reset" type="object | null">
+          Reset configuration for this balance, or null if no reset.
+          <Expandable title="properties">
+            <DynamicResponseField name="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
+              The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="interval_count" type="number">
+              Number of intervals between resets (eg. 2 for bi-monthly).
+            </DynamicResponseField>
+
+            <DynamicResponseField name="resets_at" type="number | null">
+              Timestamp when the balance will next reset.
+            </DynamicResponseField>
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="price" type="object | null">
+          Pricing configuration if this balance has usage-based pricing.
+          <Expandable title="properties">
+            <DynamicResponseField name="amount" type="number">
+              The per-unit price amount.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="tiers" type="object[]">
+              Tiered pricing configuration if applicable.
+              <Expandable title="properties">
+                <DynamicResponseField name="to" type="number" />
+
+                <DynamicResponseField name="amount" type="number" />
+
+              </Expandable>
+            </DynamicResponseField>
+
+            <DynamicResponseField name="billing_units" type="number">
+              The number of units per billing increment (eg. $9 / 250 units).
+            </DynamicResponseField>
+
+            <DynamicResponseField name="billing_method" type="'prepaid' | 'usage_based'">
+              Whether usage is prepaid or billed pay-per-use.
+            </DynamicResponseField>
+
+            <DynamicResponseField name="max_purchase" type="number | null">
+              Maximum quantity that can be purchased, or null for unlimited.
+            </DynamicResponseField>
+
+          </Expandable>
+        </DynamicResponseField>
+
+        <DynamicResponseField name="expires_at" type="number | null">
+          Timestamp when this balance expires, or null for no expiration.
+        </DynamicResponseField>
+
+      </Expandable>
+    </DynamicResponseField>
+
+    <DynamicResponseField name="rollovers" type="object[]">
+      Rollover balances carried over from previous periods.
+      <Expandable title="properties">
+        <DynamicResponseField name="balance" type="number">
+          Amount of balance rolled over from a previous period.
+        </DynamicResponseField>
+
+        <DynamicResponseField name="expires_at" type="number">
+          Timestamp when the rollover balance expires.
+        </DynamicResponseField>
+
+      </Expandable>
+    </DynamicResponseField>
+
+  </Expandable>
+</DynamicResponseField>
+
+<DynamicResponseField name="invoices" type="object[]">
+  Invoices for this entity (only included when expand=invoices)
+  <Expandable title="properties">
+    <DynamicResponseField name="plan_ids" type="string[]">
+      Array of plan IDs included in this invoice
+    </DynamicResponseField>
+
+    <DynamicResponseField name="stripe_id" type="string">
+      The Stripe invoice ID
+    </DynamicResponseField>
+
+    <DynamicResponseField name="status" type="string">
+      The status of the invoice
+    </DynamicResponseField>
+
+    <DynamicResponseField name="total" type="number">
+      The total amount of the invoice
+    </DynamicResponseField>
+
+    <DynamicResponseField name="currency" type="string">
+      The currency code for the invoice
+    </DynamicResponseField>
+
+    <DynamicResponseField name="created_at" type="number">
+      Timestamp when the invoice was created
+    </DynamicResponseField>
+
+    <DynamicResponseField name="hosted_invoice_url" type="string | null">
+      URL to the Stripe-hosted invoice page
+    </DynamicResponseField>
+
+  </Expandable>
+</DynamicResponseField>
+
+
+<ResponseExample>
+```json 200
+{
+  "id": "seat_42",
+  "name": "Seat 42",
+  "customer_id": "cus_123",
+  "feature_id": "seats",
+  "created_at": 1771409161016,
+  "env": "sandbox",
+  "subscriptions": [
+    {
+      "plan_id": "pro_plan",
+      "auto_enable": true,
+      "add_on": false,
+      "status": "active",
+      "past_due": false,
+      "canceled_at": null,
+      "expires_at": null,
+      "trial_ends_at": null,
+      "started_at": 1771431921437,
+      "current_period_start": 1771431921437,
+      "current_period_end": 1771999921437,
+      "quantity": 1
+    }
+  ],
+  "purchases": [],
+  "balances": {
+    "messages": {
+      "feature_id": "messages",
+      "granted": 100,
+      "remaining": 72,
+      "usage": 28,
+      "unlimited": false,
+      "overage_allowed": false,
+      "max_purchase": null,
+      "next_reset_at": 1773851121437,
+      "breakdown": [
+        {
+          "id": "cus_ent_39qmLooixXLAqMywgXywjAz96rV",
+          "plan_id": "pro_plan",
+          "included_grant": 100,
+          "prepaid_grant": 0,
+          "remaining": 72,
+          "usage": 28,
+          "unlimited": false,
+          "reset": {
+            "interval": "month",
+            "resets_at": 1773851121437
+          },
+          "price": null,
+          "expires_at": null
+        }
+      ]
+    }
+  },
+  "invoices": []
+}
+```
+</ResponseExample>

apps/docs/mintlify/api-reference/events/aggregate-events.mdx

@@ -1,4 +0,0 @@
----
-title: "Aggregate Events"
-openapi: "openapi-1.2.0 POST /events/aggregate"
----

apps/docs/mintlify/api-reference/events/aggregateEvents.mdx

@@ -0,0 +1,200 @@
+---
+title: "Aggregate Events"
+openapi: "openapi POST /v1/events.aggregate"
+---
+
+import { DynamicParamField } from "/components/dynamic-param-field.jsx";
+import { DynamicResponseField } from "/components/dynamic-response-field.jsx";
+import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";
+
+Aggregate usage events by time period. Returns usage totals grouped by feature and optionally by a custom property.
+
+## Working with Properties
+
+When tracking events, you can attach custom properties that can later be used for grouping aggregations:
+
+```typescript
+// Track an event with properties
+await autumn.track({
+  customerId: "cus_123",
+  featureId: "api_calls",
+  value: 1,
+  properties: {
+    model: "gpt-4",
+    source: "api",
+    region: "us-east"
+  }
+});
+```
+
+You can then aggregate events grouped by any property using the `group_by` parameter:
+
+```typescript
+const result = await autumn.events.aggregate({
+  customerId: "cus_123",
+  featureId: "api_calls",
+  range: "7d",
+  groupBy: "properties.model"  // Group by the "model" property
+});
+```
+
+## Response Format
+
+The response structure changes based on whether `group_by` is provided:
+
+### Without `group_by` (Flat Response)
+
+When no grouping is specified, `values` contains the aggregated sum for each feature:
+
+```json
+{
+  "list": [
+    {
+      "period": 1762905600000,
+      "values": {
+        "api_calls": 150,
+        "messages": 45
+      }
+    }
+  ],
+  "total": {
+    "api_calls": { "count": 10, "sum": 150 },
+    "messages": { "count": 5, "sum": 45 }
+  }
+}
+```
+
+### With `group_by` (Grouped Response)
+
+When grouping is specified, `values` contains the total sum while `grouped_values` breaks down values by group:
+
+```json
+{
+  "list": [
+    {
+      "period": 1762905600000,
+      "values": {
+        "api_calls": 150
+      },
+      "grouped_values": {
+        "api_calls": {
+          "gpt-4": 100,
+          "gpt-3.5": 50
+        }
+      }
+    }
+  ],
+  "total": {
+    "api_calls": { "count": 10, "sum": 150 }
+  }
+}
+```
+
+<Note>
+  The `grouped_values` field is only present when `group_by` is provided in the request.
+</Note>
+
+### Body Parameters
+
+<DynamicParamField body="customer_id" type="string" required>
+  Customer ID to aggregate events for
+</DynamicParamField>
+
+<DynamicParamField body="feature_id" type="string" required>
+  Feature ID(s) to aggregate events for
+</DynamicParamField>
+
+<DynamicParamField body="group_by" type="string">
+  Property to group events by. If provided, each key in the response will be an object with distinct groups as the keys
+</DynamicParamField>
+
+<DynamicParamField body="range" type="'24h' | '7d' | '30d' | '90d' | 'last_cycle' | '1bc' | '3bc'">
+  Time range to aggregate events for. Either range or custom_range must be provided
+</DynamicParamField>
+
+<DynamicParamField body="bin_size" type="'day' | 'hour' | 'month'">
+  Size of the time bins to aggregate events for. Defaults to hour if range is 24h, otherwise day
+</DynamicParamField>
+
+<DynamicParamField body="custom_range" type="object">
+  Custom time range to aggregate events for. If provided, range must not be provided
+  <Expandable title="properties">
+    <DynamicParamField body="start" type="number" required />
+
+    <DynamicParamField body="end" type="number" required />
+
+  </Expandable>
+</DynamicParamField>
+
+
+### Response
+
+<DynamicResponseField name="list" type="object[]">
+  Array of time periods with aggregated values
+  <Expandable title="properties">
+    <DynamicResponseField name="period" type="number">
+      Unix timestamp (epoch ms) for this time period
+    </DynamicResponseField>
+
+    <DynamicResponseField name="values.{key}" type="number">
+      Aggregated values per feature: \{ [featureId]: number \}
+    </DynamicResponseField>
+
+    <DynamicResponseField name="grouped_values" type="object">
+      Values broken down by group (only present when group_by is used): \{ [featureId]: \{ [groupValue]: number \} \}
+      <Expandable title="properties">
+        <DynamicResponseField name="{key}.{key}" type="number" />
+
+      </Expandable>
+    </DynamicResponseField>
+
+  </Expandable>
+</DynamicResponseField>
+
+<DynamicResponseField name="total.{key}" type="object">
+  Total aggregations per feature. Keys are feature IDs, values contain count and sum.
+  <Expandable title="properties">
+    <DynamicResponseField name="count" type="number">
+      Number of events for this feature
+    </DynamicResponseField>
+
+    <DynamicResponseField name="sum" type="number">
+      Sum of event values for this feature
+    </DynamicResponseField>
+
+  </Expandable>
+</DynamicResponseField>
+
+
+<ResponseExample>
+```json 200
+{
+  "list": [
+    {
+      "period": 1762905600000,
+      "values": {
+        "messages": 10,
+        "sessions": 3
+      }
+    },
+    {
+      "period": 1762992000000,
+      "values": {
+        "messages": 3,
+        "sessions": 12
+      }
+    }
+  ],
+  "total": {
+    "messages": {
+      "count": 2,
+      "sum": 13
+    },
+    "sessions": {
+      "count": 2,
+      "sum": 15
+    }
+  }
+}
+```
+</ResponseExample>

apps/docs/mintlify/api-reference/events/list-events.mdx

@@ -1,4 +0,0 @@
----
-title: "List Events"
-openapi: "openapi-1.2.0 POST /events/list"
----

apps/docs/mintlify/api-reference/events/listEvents.mdx

@@ -0,0 +1,119 @@
+---
+title: "List Events"
+openapi: "openapi POST /v1/events.list"
+---
+
+import { DynamicParamField } from "/components/dynamic-param-field.jsx";
+import { DynamicResponseField } from "/components/dynamic-response-field.jsx";
+import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";
+
+### Body Parameters
+
+<DynamicParamField body="offset" type="integer">
+  Number of items to skip
+</DynamicParamField>
+
+<DynamicParamField body="limit" type="integer">
+  Number of items to return. Default 100, max 1000.
+</DynamicParamField>
+
+<DynamicParamField body="customer_id" type="string">
+  Filter events by customer ID
+</DynamicParamField>
+
+<DynamicParamField body="feature_id" type="string">
+  Filter by specific feature ID(s)
+</DynamicParamField>
+
+<DynamicParamField body="custom_range" type="object">
+  Filter events by time range
+  <Expandable title="properties">
+    <DynamicParamField body="start" type="number">
+      Filter events after this timestamp (epoch milliseconds)
+    </DynamicParamField>
+
+    <DynamicParamField body="end" type="number">
+      Filter events before this timestamp (epoch milliseconds)
+    </DynamicParamField>
+
+  </Expandable>
+</DynamicParamField>
+
+
+### Response
+
+<DynamicResponseField name="list" type="object[]">
+  Array of items for current page
+  <Expandable title="properties">
+    <DynamicResponseField name="id" type="string">
+      Event ID (KSUID)
+    </DynamicResponseField>
+
+    <DynamicResponseField name="timestamp" type="number">
+      Event timestamp (epoch milliseconds)
+    </DynamicResponseField>
+
+    <DynamicResponseField name="feature_id" type="string">
+      ID of the feature that the event belongs to
+    </DynamicResponseField>
+
+    <DynamicResponseField name="customer_id" type="string">
+      Customer identifier
+    </DynamicResponseField>
+
+    <DynamicResponseField name="value" type="number">
+      Event value/count
+    </DynamicResponseField>
+
+    <DynamicResponseField name="properties" type="object">
+      Event properties (JSONB)
+    </DynamicResponseField>
+
+  </Expandable>
+</DynamicResponseField>
+
+<DynamicResponseField name="has_more" type="boolean">
+  Whether more results exist after this page
+</DynamicResponseField>
+
+<DynamicResponseField name="offset" type="number">
+  Current offset position
+</DynamicResponseField>
+
+<DynamicResponseField name="limit" type="number">
+  Limit passed in the request
+</DynamicResponseField>
+
+<DynamicResponseField name="total" type="number">
+  Total number of items returned in the current page
+</DynamicResponseField>
+
+
+<ResponseExample>
+```json 200
+{
+  "list": [
+    {
+      "id": "evt_36xpk2TmuQX5zVPPQ8tCtnR5Weg",
+      "timestamp": 1765958215459,
+      "feature_id": "credits",
+      "customer_id": "0pCIbS4AMAFDB1iBMNhARWZt2gDtVwQx",
+      "value": 30,
+      "properties": {}
+    },
+    {
+      "id": "evt_36xmHxxjAkqxufDf9yHAPNfRrLM",
+      "timestamp": 1765956512057,
+      "feature_id": "credits",
+      "customer_id": "0pCIbS4AMAFDB1iBMNhARWZt2gDtVwQx",
+      "value": 49,
+      "properties": {}
+    }
+  ],
+  "total": 2,
+  "has_more": false,
+  "offset": 0,
+  "limit": 100
+}
+```
+</ResponseExample>

apps/docs/mintlify/api-reference/referrals/createReferralCode.mdx

@@ -0,0 +1,44 @@
+---
+title: "Create Referral Code"
+openapi: "openapi POST /v1/referrals.create_code"
+---
+
+import { DynamicParamField } from "/components/dynamic-param-field.jsx";
+import { DynamicResponseField } from "/components/dynamic-response-field.jsx";
+import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";
+
+### Body Parameters
+
+<DynamicParamField body="customer_id" type="string" required>
+  The unique identifier of the customer
+</DynamicParamField>
+
+<DynamicParamField body="program_id" type="string" required>
+  ID of your referral program
+</DynamicParamField>
+
+
+### Response
+
+<DynamicResponseField name="code" type="string">
+  The referral code that can be shared with customers
+</DynamicResponseField>
+
+<DynamicResponseField name="customer_id" type="string">
+  Your unique identifier for the customer
+</DynamicResponseField>
+
+<DynamicResponseField name="created_at" type="number">
+  The timestamp of when the referral code was created
+</DynamicResponseField>
+
+
+<ResponseExample>
+```json 200
+{
+  "code": "<string>",
+  "customer_id": "<string>",
+  "created_at": 123
+}
+```
+</ResponseExample>

apps/docs/mintlify/api-reference/referrals/redeemReferralCode.mdx

@@ -0,0 +1,44 @@
+---
+title: "Redeem Referral Code"
+openapi: "openapi POST /v1/referrals.redeem_code"
+---
+
+import { DynamicParamField } from "/components/dynamic-param-field.jsx";
+import { DynamicResponseField } from "/components/dynamic-response-field.jsx";
+import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";
+
+### Body Parameters
+
+<DynamicParamField body="code" type="string" required>
+  The referral code to redeem
+</DynamicParamField>
+
+<DynamicParamField body="customer_id" type="string" required>
+  The unique identifier of the customer redeeming the code
+</DynamicParamField>
+
+
+### Response
+
+<DynamicResponseField name="id" type="string">
+  The ID of the redemption event
+</DynamicResponseField>
+
+<DynamicResponseField name="customer_id" type="string">
+  Your unique identifier for the customer
+</DynamicResponseField>
+
+<DynamicResponseField name="reward_id" type="string">
+  The ID of the reward that will be granted
+</DynamicResponseField>
+
+
+<ResponseExample>
+```json 200
+{
+  "id": "<string>",
+  "customer_id": "<string>",
+  "reward_id": "<string>"
+}
+```
+</ResponseExample>

apps/docs/mintlify/api-reference/referrals/referral-code.mdx

@@ -1,30 +0,0 @@
----
-title: "Create a referral code"
-openapi: "productsapi POST /referrals/code"
----
-
-This endpoint creates or retrieves a unique referral code for a customer within a specific referral program. 
-
-<Tip>
-  A referral code is unique per customer within each program. On the first call, a new code is created, but subsequent calls will return the same existing code for that customer and program combination.
-</Tip>
-
-<Note>
-  The `program_id` parameter refers to the referral program ID that you define when creating a referral program in the Autumn dashboard. Each program can have different rewards and rules.
-</Note>
-
-{/* ## How it works
-
-1. **First call**: Creates a new unique referral code for the customer
-2. **Subsequent calls**: Returns the existing code for that customer/program pair  
-3. **Code sharing**: Customers can share their referral code with others
-4. **Redemption**: Other customers can redeem the code using the [redeem endpoint](/api-reference/products/referral-redeem)
-
-## Use Cases
-
-This endpoint is useful for:
-
-- **Customer referral programs**: Allow customers to generate codes to share with friends
-- **Affiliate marketing**: Create tracking codes for affiliate partners  
-- **Loyalty programs**: Generate codes tied to specific promotional campaigns
-- **User dashboards**: Display referral codes in customer account pages */}

apps/docs/mintlify/api-reference/referrals/referral-redeem.mdx

@@ -1,4 +0,0 @@
----
-title: "Redeem a referral code"
-openapi: "productsapi POST /referrals/redeem"
----

apps/docs/mintlify/docs.json

@@ -129,16 +129,24 @@
 			{
 				"tab": "API Reference",
 				"icon": "rectangle-terminal",
-				"openapi": "api/openapi.yml",
 				"groups": [
 					{
-						"group": "Core",
+						"group": "Billing",
+						"pages": [
+							"api-reference/billing/billingAttach",
+							"api-reference/billing/billingUpdate",
+							"api-reference/billing/previewAttach",
+							"api-reference/billing/previewUpdate",
+							"api-reference/billing/openCustomerPortal"
+						]
+					},
+					{
+						"group": "Balances",
 						"pages": [
-							"api-reference/core/checkout",
-							"api-reference/core/attach",
 							"api-reference/core/check",
 							"api-reference/core/track",
-							"api-reference/core/cancel"
+							"api-reference/balances/createBalance",
+							"api-reference/balances/updateBalance"
 						]
 					},
 					{
@@ -147,25 +155,36 @@
 							"api-reference/customers/getOrCreateCustomer",
 							"api-reference/customers/listCustomers",
 							"api-reference/customers/updateCustomer",
-							"api-reference/customers/deleteCustomer",
-							"api-reference/customers/open-billing-portal"
+							"api-reference/customers/deleteCustomer"
 						]
 					},
 					{
 						"group": "Events",
 						"pages": [
-							"api-reference/events/list-events",
-							"api-reference/events/aggregate-events"
+							"api-reference/events/listEvents",
+							"api-reference/events/aggregateEvents"
 						]
 					},
 					{
 						"group": "Entities",
 						"pages": [
-							"api-reference/entities/get-entity",
-							"api-reference/entities/create-entity",
-							"api-reference/entities/delete-entity"
+							"api-reference/entities/getEntity",
+							"api-reference/entities/createEntity",
+							"api-reference/entities/deleteEntity"
 						]
 					},
+					{
+						"group": "Referrals",
+						"pages": [
+							"api-reference/referrals/createReferralCode",
+							"api-reference/referrals/redeemReferralCode"
+						]
+					},
+					{
+						"group": "TODO",
+						"pages": ["api-reference/billing/setupPayment"]
+					},
+
 					{
 						"group": "Features",
 						"pages": [
@@ -189,18 +208,7 @@
 							"api-reference/products/delete-product"
 						]
 					},
-					{
-						"group": "Referrals",
-						"pages": [
-							"api-reference/referrals/referral-code",
-							"api-reference/referrals/referral-redeem"
-						]
-					},
 
-					{
-						"group": "CLI",
-						"pages": ["api-reference/cli/config"]
-					},
 					{
 						"group": "Platform (Beta)",
 						"pages": [

apps/docs/package.json

@@ -3,7 +3,7 @@
 	"private": true,
 	"scripts": {
 		"pull": "bun scripts/pull.ts",
-		"dev": "cd mintlify && mint dev -p 3003",
+		"dev": "cd mintlify && mint dev --port 3003",
 		"build": "cd mintlify && mint build",
 		"start": "cd mintlify && mint dev"
 	},

apps/sdk-test/app/scenarios/core/use-autumn/page.tsx

@@ -1,6 +1,9 @@
 "use client";
 
-import type { ClientAttachParams } from "autumn-js/react";
+import type {
+  ClientAttachParams,
+  ClientOpenCustomerPortalParams,
+} from "autumn-js/react";
 import { useCustomer } from "autumn-js/react";
 import { useId, useState } from "react";
 import { DataViewer } from "@/components/debug/DataViewer";
@@ -10,7 +13,7 @@ import { Button } from "@/components/ui/button";
 import { Input } from "@/components/ui/input";
 import { Label } from "@/components/ui/label";
 
-type ActionTab = "attach" | "check";
+type ActionTab = "attach" | "check" | "openCustomerPortal";
 
 type LastActionState = {
   name: string;
@@ -43,14 +46,8 @@ const toErrorPayload = ({ error }: { error: unknown }) => {
 };
 
 export default function UseAutumnScenarioPage() {
-  const {
-    data: customer,
-    isLoading,
-    error,
-    refetch,
-    attach,
-    check,
-  } = useCustomer({
+  const { isLoading, error, refetch, attach, check, openCustomerPortal } =
+    useCustomer({
       errorOnNotFound: false,
     });
 
@@ -66,11 +63,13 @@ export default function UseAutumnScenarioPage() {
   const [featureId, setFeatureId] = useState("");
   const [requiredBalance, setRequiredBalance] = useState("");
   const [openInNewTab, setOpenInNewTab] = useState(false);
+  const [portalReturnUrl, setPortalReturnUrl] = useState("");
 
   // Form element IDs
   const planIdInputId = useId();
   const featureIdInputId = useId();
   const requiredBalanceInputId = useId();
+  const portalReturnUrlInputId = useId();
 
   const runAction = async ({
     name,
@@ -138,6 +137,18 @@ export default function UseAutumnScenarioPage() {
     });
   };
 
+  const handleOpenCustomerPortal = () => {
+    const params: ClientOpenCustomerPortalParams = {
+      returnUrl: portalReturnUrl || undefined,
+      openInNewTab,
+    };
+    runAction({
+      name: "openCustomerPortal",
+      params,
+      execute: () => openCustomerPortal(params),
+    });
+  };
+
   return (
     <div className="space-y-4">
       <DebugCard
@@ -180,6 +191,17 @@ export default function UseAutumnScenarioPage() {
           >
             Check
           </button>
+          <button
+            type="button"
+            onClick={() => setActiveTab("openCustomerPortal")}
+            className={`px-3 py-1.5 text-sm font-medium border-b-2 -mb-px transition-colors ${
+              activeTab === "openCustomerPortal"
+                ? "border-zinc-900 text-zinc-900"
+                : "border-transparent text-zinc-500 hover:text-zinc-700"
+            }`}
+          >
+            Portal
+          </button>
         </div>
 
         {/* Tab content */}
@@ -258,6 +280,45 @@ export default function UseAutumnScenarioPage() {
             </Button>
           </div>
         )}
+
+        {activeTab === "openCustomerPortal" && (
+          <div className="space-y-3">
+            <div className="space-y-1.5">
+              <Label
+                htmlFor={portalReturnUrlInputId}
+                className="text-xs text-zinc-500"
+              >
+                Return URL (optional)
+              </Label>
+              <Input
+                id={portalReturnUrlInputId}
+                placeholder="https://app.example.com/settings/billing"
+                value={portalReturnUrl}
+                onChange={(e) => setPortalReturnUrl(e.target.value)}
+                className="h-8 text-sm"
+              />
+              <p className="text-[11px] text-zinc-500 leading-tight">
+                Defaults to the current page URL when left empty.
+              </p>
+            </div>
+            <label className="flex items-center gap-2 text-sm text-zinc-600">
+              <input
+                type="checkbox"
+                checked={openInNewTab}
+                onChange={(e) => setOpenInNewTab(e.target.checked)}
+                className="rounded border-zinc-300"
+              />
+              Open in new tab
+            </label>
+            <Button
+              size="sm"
+              disabled={isRunning}
+              onClick={handleOpenCustomerPortal}
+            >
+              {isRunning ? "Running..." : "Open portal"}
+            </Button>
+          </div>
+        )}
       </DebugCard>
 
       <div className="grid gap-4 lg:grid-cols-2">

apps/sdk-test/app/scenarios/core/use-referrals/page.tsx

@@ -0,0 +1,251 @@
+"use client";
+
+import type {
+  ClientCreateReferralCodeParams,
+  ClientRedeemReferralCodeParams,
+} from "autumn-js/react";
+import { useCustomer } from "autumn-js/react";
+import { useId, useState } from "react";
+import { DataViewer } from "@/components/debug/DataViewer";
+import { DebugCard } from "@/components/debug/DebugCard";
+import { HookStatePanel } from "@/components/debug/HookStatePanel";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+
+type ActionTab = "createReferralCode" | "redeemReferralCode";
+
+type LastActionState = {
+  name: string;
+  params: unknown;
+  result: unknown;
+  error: unknown;
+  executedAt: string;
+} | null;
+
+const toErrorPayload = ({ error }: { error: unknown }) => {
+  if (error instanceof Error) {
+    const typed = error as Error & {
+      code?: string;
+      statusCode?: number;
+      details?: unknown;
+    };
+
+    return {
+      message: typed.message,
+      code: typed.code ?? null,
+      statusCode: typed.statusCode ?? null,
+      details: typed.details ?? null,
+      name: typed.name,
+    };
+  }
+
+  return {
+    message: "Unknown error",
+    raw: error,
+  };
+};
+
+export default function UseReferralsScenarioPage() {
+  const { isLoading, error, refetch, createReferralCode, redeemReferralCode } =
+    useCustomer({
+      errorOnNotFound: false,
+    });
+
+  const [lastUpdatedAt, setLastUpdatedAt] = useState<string | null>(null);
+  const [isRunning, setIsRunning] = useState(false);
+  const [lastAction, setLastAction] = useState<LastActionState>(null);
+  const [activeTab, setActiveTab] = useState<ActionTab>("createReferralCode");
+
+  const [programId, setProgramId] = useState("");
+  const [referralCode, setReferralCode] = useState("");
+
+  const programIdInputId = useId();
+  const referralCodeInputId = useId();
+
+  const runAction = async ({
+    name,
+    params,
+    execute,
+  }: {
+    name: string;
+    params: unknown;
+    execute: () => Promise<unknown>;
+  }) => {
+    setIsRunning(true);
+    try {
+      const result = await execute();
+      setLastAction({
+        name,
+        params,
+        result,
+        error: null,
+        executedAt: new Date().toISOString(),
+      });
+    } catch (err) {
+      setLastAction({
+        name,
+        params,
+        result: null,
+        error: toErrorPayload({ error: err }),
+        executedAt: new Date().toISOString(),
+      });
+    } finally {
+      setIsRunning(false);
+    }
+  };
+
+  const onRefetch = async () => {
+    await refetch();
+    setLastUpdatedAt(new Date().toISOString());
+  };
+
+  const handleCreateReferralCode = () => {
+    if (!programId) return;
+
+    const params: ClientCreateReferralCodeParams = {
+      programId,
+    };
+
+    runAction({
+      name: "createReferralCode",
+      params,
+      execute: () => createReferralCode(params),
+    });
+  };
+
+  const handleRedeemReferralCode = () => {
+    if (!referralCode) return;
+
+    const params: ClientRedeemReferralCodeParams = {
+      code: referralCode,
+    };
+
+    runAction({
+      name: "redeemReferralCode",
+      params,
+      execute: () => redeemReferralCode(params),
+    });
+  };
+
+  return (
+    <div className="space-y-4">
+      <DebugCard
+        title="Hook State"
+        actions={
+          <Button variant="outline" size="sm" onClick={onRefetch}>
+            Refetch
+          </Button>
+        }
+      >
+        <HookStatePanel
+          isLoading={isLoading}
+          error={error}
+          lastUpdatedAt={lastUpdatedAt}
+        />
+      </DebugCard>
+
+      <DebugCard title="Referral Actions">
+        <div className="mb-4 flex gap-1 border-b border-zinc-200">
+          <button
+            type="button"
+            onClick={() => setActiveTab("createReferralCode")}
+            className={`-mb-px border-b-2 px-3 py-1.5 text-sm font-medium transition-colors ${
+              activeTab === "createReferralCode"
+                ? "border-zinc-900 text-zinc-900"
+                : "border-transparent text-zinc-500 hover:text-zinc-700"
+            }`}
+          >
+            Create Code
+          </button>
+          <button
+            type="button"
+            onClick={() => setActiveTab("redeemReferralCode")}
+            className={`-mb-px border-b-2 px-3 py-1.5 text-sm font-medium transition-colors ${
+              activeTab === "redeemReferralCode"
+                ? "border-zinc-900 text-zinc-900"
+                : "border-transparent text-zinc-500 hover:text-zinc-700"
+            }`}
+          >
+            Redeem Code
+          </button>
+        </div>
+
+        {activeTab === "createReferralCode" && (
+          <div className="space-y-3">
+            <div className="space-y-1.5">
+              <Label
+                htmlFor={programIdInputId}
+                className="text-xs text-zinc-500"
+              >
+                Program ID
+              </Label>
+              <Input
+                id={programIdInputId}
+                placeholder="prog_123"
+                value={programId}
+                onChange={(e) => setProgramId(e.target.value)}
+                className="h-8 text-sm"
+              />
+            </div>
+            <Button
+              size="sm"
+              disabled={isRunning || !programId}
+              onClick={handleCreateReferralCode}
+            >
+              {isRunning ? "Running..." : "Create code"}
+            </Button>
+          </div>
+        )}
+
+        {activeTab === "redeemReferralCode" && (
+          <div className="space-y-3">
+            <div className="space-y-1.5">
+              <Label
+                htmlFor={referralCodeInputId}
+                className="text-xs text-zinc-500"
+              >
+                Referral Code
+              </Label>
+              <Input
+                id={referralCodeInputId}
+                placeholder="REF123ABC"
+                value={referralCode}
+                onChange={(e) => setReferralCode(e.target.value)}
+                className="h-8 text-sm"
+              />
+            </div>
+            <Button
+              size="sm"
+              disabled={isRunning || !referralCode}
+              onClick={handleRedeemReferralCode}
+            >
+              {isRunning ? "Running..." : "Redeem code"}
+            </Button>
+          </div>
+        )}
+      </DebugCard>
+
+      <div className="grid gap-4 md:grid-cols-2">
+        <DataViewer
+          title="lastAction"
+          value={lastAction}
+          defaultExpandedDepth={3}
+        />
+        <DataViewer
+          title="error"
+          value={
+            error
+              ? {
+                  message: error.message,
+                  code: error.code,
+                  statusCode: error.statusCode,
+                }
+              : null
+          }
+          defaultExpandedDepth={2}
+        />
+      </div>
+    </div>
+  );
+}

apps/sdk-test/lib/scenarios.ts

@@ -40,6 +40,13 @@ export const scenarioSections: Array<ScenarioSection> = [
         description: "Test attach/check action helpers and inspect payloads.",
         status: "ready",
       },
+      {
+        id: "use-referrals",
+        title: "useReferrals",
+        href: "/scenarios/core/use-referrals",
+        description: "Test create/redeem referral code action helpers.",
+        status: "ready",
+      },
       {
         id: "use-entity",
         title: "useEntity",

apps/sdk-test/sdk.ts

@@ -9,15 +9,9 @@ const autumn = new Autumn({
   secretKey: process.env.AUTUMN_SECRET_KEY,
 });
 
-const customer = await autumn.customers.getOrCreate({
-  customerId: "123",
+const res = await autumn.events.aggregate({
+  customerId: "john",
+  featureId: "messages",
 });
 
-console.log("Customer:", customer);
-
-const attachResult = await autumn.billing.attach({
-  customerId: customer.id ?? "",
-  planId: "pro_plan",
-});
-
-console.log("Attach result:", attachResult);
+console.log(JSON.stringify(res, null, 2));

apps/sdk-test/tsconfig.check.json

@@ -2,8 +2,7 @@
   "extends": "./tsconfig.json",
   "compilerOptions": {
     "paths": {
-      "@/*": ["./*"],
-      "@api/*": ["../../shared/api/*"]
+      "@/*": ["./*"]
     }
   },
   "include": [

apps/sdk-test/tsconfig.json

@@ -1,6 +1,5 @@
 {
   "compilerOptions": {
-    "baseUrl": ".",
     "target": "ES2017",
     "lib": ["dom", "dom.iterable", "esnext"],
     "allowJs": true,
@@ -20,6 +19,7 @@
       }
     ],
     "paths": {
+      "*": ["./*"],
       "@/*": ["./*", "../../packages/autumn-js/src/libraries/react/*"],
       "@/components/*": [
         "./components/*",
@@ -35,7 +35,6 @@
       ],
       "@sdk": ["../../packages/autumn-js/src/sdk/index.ts"],
       "@sdk/*": ["../../packages/autumn-js/src/sdk/*"],
-      "@api/*": ["../../shared/api/*"],
       "@utils/*": ["../../packages/autumn-js/src/utils/*"],
       "autumn-js": ["../../packages/autumn-js/src/sdk/index.ts"],
       "autumn-js/react": ["../../packages/autumn-js/src/react/index.ts"],

bun.lock

@@ -168,7 +168,7 @@
     },
     "packages/sdk": {
       "name": "@useautumn/sdk",
-      "version": "0.8.27",
+      "version": "0.10.4",
       "dependencies": {
         "zod": "^3.25.65 || ^4.0.0",
       },

others/python-sdk/.speakeasy/code-samples.overlay.yaml

@@ -17,7 +17,7 @@ actions:
                 secret_key="<YOUR_BEARER_TOKEN_HERE>",
             ) as autumn:
 
-                res = autumn.balances.check(customer_id="<id>", feature_id="<id>")
+                res = autumn.check(customer_id="cus_123", feature_id="messages")
 
                 # Handle response
                 print(res)
@@ -35,7 +35,9 @@ actions:
                 secret_key="<YOUR_BEARER_TOKEN_HERE>",
             ) as autumn:
 
-                res = autumn.balances.create(feature_id="<id>", customer_id="<id>")
+                res = autumn.balances.create(customer_id="cus_123", feature_id="api_calls", included=1000, reset={
+                    "interval": "month",
+                })
 
                 # Handle response
                 print(res)
@@ -53,7 +55,7 @@ actions:
                 secret_key="<YOUR_BEARER_TOKEN_HERE>",
             ) as autumn:
 
-                res = autumn.balances.track(customer_id="<id>")
+                res = autumn.track(customer_id="cus_123", feature_id="messages", value=1)
 
                 # Handle response
                 print(res)
@@ -71,7 +73,7 @@ actions:
                 secret_key="<YOUR_BEARER_TOKEN_HERE>",
             ) as autumn:
 
-                res = autumn.balances.update(customer_id="<id>", feature_id="<id>")
+                res = autumn.balances.update(customer_id="cus_123", feature_id="api_calls", remaining=5)
 
                 # Handle response
                 print(res)
@@ -89,7 +91,25 @@ actions:
                 secret_key="<YOUR_BEARER_TOKEN_HERE>",
             ) as autumn:
 
-                res = autumn.billing.attach(customer_id="<id>", plan_id="<id>", redirect_mode="always")
+                res = autumn.billing.attach(customer_id="cus_123", plan_id="pro_plan")
+
+                # Handle response
+                print(res)
+  - target: $["paths"]["/v1/billing.open_customer_portal"]["post"]
+    update:
+      x-codeSamples:
+        - lang: python
+          label: Python (SDK)
+          source: |-
+            from autumn_sdk import Autumn
+
+
+            with Autumn(
+                x_api_version="2.1",
+                secret_key="<YOUR_BEARER_TOKEN_HERE>",
+            ) as autumn:
+
+                res = autumn.billing.open_customer_portal(customer_id="cus_123", return_url="https://useautumn.com")
 
                 # Handle response
                 print(res)
@@ -107,7 +127,7 @@ actions:
                 secret_key="<YOUR_BEARER_TOKEN_HERE>",
             ) as autumn:
 
-                res = autumn.billing.preview_attach(customer_id="<id>", plan_id="<id>", redirect_mode="always")
+                res = autumn.billing.preview_attach(customer_id="cus_123", plan_id="pro_plan")
 
                 # Handle response
                 print(res)
@@ -125,25 +145,12 @@ actions:
                 secret_key="<YOUR_BEARER_TOKEN_HERE>",
             ) as autumn:
 
-                res = autumn.billing.preview_update(customer_id="<id>")
-
-                # Handle response
-                print(res)
-  - target: $["paths"]["/v1/billing.setup_payment"]["post"]
-    update:
-      x-codeSamples:
-        - lang: python
-          label: Python (SDK)
-          source: |-
-            from autumn_sdk import Autumn
-
-
-            with Autumn(
-                x_api_version="2.1",
-                secret_key="<YOUR_BEARER_TOKEN_HERE>",
-            ) as autumn:
-
-                res = autumn.billing.setup_payment(customer_id="<id>")
+                res = autumn.billing.preview_update(customer_id="cus_123", plan_id="pro_plan", feature_quantities=[
+                    {
+                        "feature_id": "seats",
+                        "quantity": 15,
+                    },
+                ])
 
                 # Handle response
                 print(res)
@@ -161,7 +168,12 @@ actions:
                 secret_key="<YOUR_BEARER_TOKEN_HERE>",
             ) as autumn:
 
-                res = autumn.billing.update(customer_id="<id>")
+                res = autumn.billing.update(customer_id="cus_123", plan_id="pro_plan", feature_quantities=[
+                    {
+                        "feature_id": "seats",
+                        "quantity": 10,
+                    },
+                ])
 
                 # Handle response
                 print(res)
@@ -235,6 +247,96 @@ actions:
 
                 res = autumn.customers.update(customer_id="cus_123", name="Jane Doe", email="jane@example.com")
 
+                # Handle response
+                print(res)
+  - target: $["paths"]["/v1/entities.create"]["post"]
+    update:
+      x-codeSamples:
+        - lang: python
+          label: Python (SDK)
+          source: |-
+            from autumn_sdk import Autumn
+
+
+            with Autumn(
+                x_api_version="2.1",
+                secret_key="<YOUR_BEARER_TOKEN_HERE>",
+            ) as autumn:
+
+                res = autumn.entities.create(feature_id="seats", customer_id="cus_123", entity_id="seat_42", name="Seat 42")
+
+                # Handle response
+                print(res)
+  - target: $["paths"]["/v1/entities.delete"]["post"]
+    update:
+      x-codeSamples:
+        - lang: python
+          label: Python (SDK)
+          source: |-
+            from autumn_sdk import Autumn
+
+
+            with Autumn(
+                x_api_version="2.1",
+                secret_key="<YOUR_BEARER_TOKEN_HERE>",
+            ) as autumn:
+
+                res = autumn.entities.delete(entity_id="seat_42", customer_id="cus_123")
+
+                # Handle response
+                print(res)
+  - target: $["paths"]["/v1/entities.get"]["post"]
+    update:
+      x-codeSamples:
+        - lang: python
+          label: Python (SDK)
+          source: |-
+            from autumn_sdk import Autumn
+
+
+            with Autumn(
+                x_api_version="2.1",
+                secret_key="<YOUR_BEARER_TOKEN_HERE>",
+            ) as autumn:
+
+                res = autumn.entities.get(entity_id="seat_42")
+
+                # Handle response
+                print(res)
+  - target: $["paths"]["/v1/events.aggregate"]["post"]
+    update:
+      x-codeSamples:
+        - lang: python
+          label: Python (SDK)
+          source: |-
+            from autumn_sdk import Autumn
+
+
+            with Autumn(
+                x_api_version="2.1",
+                secret_key="<YOUR_BEARER_TOKEN_HERE>",
+            ) as autumn:
+
+                res = autumn.events.aggregate(customer_id="cus_123", feature_id="api_calls", range="30d", bin_size="day")
+
+                # Handle response
+                print(res)
+  - target: $["paths"]["/v1/events.list"]["post"]
+    update:
+      x-codeSamples:
+        - lang: python
+          label: Python (SDK)
+          source: |-
+            from autumn_sdk import Autumn
+
+
+            with Autumn(
+                x_api_version="2.1",
+                secret_key="<YOUR_BEARER_TOKEN_HERE>",
+            ) as autumn:
+
+                res = autumn.events.list(offset=0, limit=50, customer_id="cus_123")
+
                 # Handle response
                 print(res)
   - target: $["paths"]["/v1/plans.list"]["post"]
@@ -253,5 +355,41 @@ actions:
 
                 res = autumn.plans.list()
 
+                # Handle response
+                print(res)
+  - target: $["paths"]["/v1/referrals.create_code"]["post"]
+    update:
+      x-codeSamples:
+        - lang: python
+          label: Python (SDK)
+          source: |-
+            from autumn_sdk import Autumn
+
+
+            with Autumn(
+                x_api_version="2.1",
+                secret_key="<YOUR_BEARER_TOKEN_HERE>",
+            ) as autumn:
+
+                res = autumn.referrals.create_code(customer_id="cus_123", program_id="prog_123")
+
+                # Handle response
+                print(res)
+  - target: $["paths"]["/v1/referrals.redeem_code"]["post"]
+    update:
+      x-codeSamples:
+        - lang: python
+          label: Python (SDK)
+          source: |-
+            from autumn_sdk import Autumn
+
+
+            with Autumn(
+                x_api_version="2.1",
+                secret_key="<YOUR_BEARER_TOKEN_HERE>",
+            ) as autumn:
+
+                res = autumn.referrals.redeem_code(code="REF123", customer_id="cus_456")
+
                 # Handle response
                 print(res)

others/python-sdk/.speakeasy/gen.yaml

@@ -30,7 +30,7 @@ generation:
     generateNewTests: true
     skipResponseBodyAssertions: false
 python:
-  version: 0.2.23
+  version: 0.4.4
   additionalDependencies:
     dev: {}
     main: {}
@@ -38,6 +38,7 @@ python:
     - id
     - object
     - input
+    - range
   asyncMode: both
   author: Autumn
   authors:

others/python-sdk/README.md

@@ -132,7 +132,7 @@ with Autumn(
     secret_key="<YOUR_BEARER_TOKEN_HERE>",
 ) as autumn:
 
-    res = autumn.customers.get_or_create(customer_id="cus_123", name="John Doe", email="john@example.com")
+    res = autumn.check(customer_id="cus_123", feature_id="messages")
 
     # Handle response
     print(res)
@@ -154,7 +154,7 @@ async def main():
         secret_key="<YOUR_BEARER_TOKEN_HERE>",
     ) as autumn:
 
-        res = await autumn.customers.get_or_create_async(customer_id="cus_123", name="John Doe", email="john@example.com")
+        res = await autumn.check_async(customer_id="cus_123", feature_id="messages")
 
         # Handle response
         print(res)
@@ -184,7 +184,7 @@ with Autumn(
     x_api_version="2.1",
 ) as autumn:
 
-    res = autumn.customers.get_or_create(customer_id="cus_123", name="John Doe", email="john@example.com")
+    res = autumn.check(customer_id="cus_123", feature_id="messages")
 
     # Handle response
     print(res)
@@ -198,20 +198,35 @@ with Autumn(
 <details open>
 <summary>Available methods</summary>
 
+### [Autumn SDK](docs/sdks/autumn/README.md)
+
+* [check](docs/sdks/autumn/README.md#check) - Checks whether a customer currently has enough balance to use a feature.
+
+Use this to gate access before a feature action. Enable sendEvent when you want to check and consume balance atomically in one request.
+* [track](docs/sdks/autumn/README.md#track) - Records usage for a customer feature and returns updated balances.
+
+Use this after an action happens to decrement usage, or send a negative value to credit balance back.
+
 ### [Balances](docs/sdks/balancessdk/README.md)
 
 * [create](docs/sdks/balancessdk/README.md#create) - Create a balance for a customer feature.
 * [update](docs/sdks/balancessdk/README.md#update) - Update a customer balance.
-* [check](docs/sdks/balancessdk/README.md#check) - Check whether usage is allowed for a customer feature.
-* [track](docs/sdks/balancessdk/README.md#track) - Track usage for a customer feature.
 
 ### [Billing](docs/sdks/billing/README.md)
 
 * [attach](docs/sdks/billing/README.md#attach) - Attaches a plan to a customer. Handles new subscriptions, upgrades and downgrades.
-* [preview_attach](docs/sdks/billing/README.md#preview_attach) - Preview billing changes before attaching a plan.
-* [update](docs/sdks/billing/README.md#update) - Update an existing subscription.
-* [preview_update](docs/sdks/billing/README.md#preview_update) - Preview billing changes before updating a subscription.
-* [setup_payment](docs/sdks/billing/README.md#setup_payment) - Create a setup payment session for a customer.
+
+Use this endpoint to subscribe a customer to a plan, upgrade/downgrade between plans, or add an add-on product.
+* [preview_attach](docs/sdks/billing/README.md#preview_attach) - Previews the billing changes that would occur when attaching a plan, without actually making any changes.
+
+Use this endpoint to show customers what they will be charged before confirming a subscription change.
+* [update](docs/sdks/billing/README.md#update) - Updates an existing subscription. Use to modify feature quantities, cancel, or change plan configuration.
+
+Use this endpoint to update prepaid quantities, cancel a subscription (immediately or at end of cycle), or modify subscription settings.
+* [preview_update](docs/sdks/billing/README.md#preview_update) - Previews the billing changes that would occur when updating a subscription, without actually making any changes.
+
+Use this endpoint to show customers prorated charges or refunds before confirming subscription modifications.
+* [open_customer_portal](docs/sdks/billing/README.md#open_customer_portal) - Create a billing portal session for a customer to manage their subscription.
 
 ### [Customers](docs/sdks/customers/README.md)
 
@@ -222,10 +237,32 @@ Use this as the primary entrypoint before billing operations so the customer rec
 * [update](docs/sdks/customers/README.md#update) - Updates an existing customer by ID.
 * [delete](docs/sdks/customers/README.md#delete) - Deletes a customer by ID.
 
+### [Entities](docs/sdks/entities/README.md)
+
+* [create](docs/sdks/entities/README.md#create) - Creates an entity for a customer and feature, then returns the entity with balances and subscriptions.
+
+Use entities when usage and access must be scoped to sub-resources (for example seats, projects, or workspaces) instead of only the customer.
+* [get](docs/sdks/entities/README.md#get) - Fetches a single entity by entity ID.
+
+Use this to read one entity's current state. Pass customerId when you want to scope the lookup to a specific customer.
+* [delete](docs/sdks/entities/README.md#delete) - Deletes an entity by entity ID.
+
+Use this when the underlying resource is removed and you no longer want entity-scoped balances or subscriptions tracked for it.
+
+### [Events](docs/sdks/events/README.md)
+
+* [list](docs/sdks/events/README.md#list) - List usage events for your organization. Filter by customer, feature, or time range.
+* [aggregate](docs/sdks/events/README.md#aggregate) - Aggregate usage events by time period. Returns usage totals grouped by feature and optionally by a custom property.
+
 ### [Plans](docs/sdks/plans/README.md)
 
 * [list](docs/sdks/plans/README.md#list) - List all plans
 
+### [Referrals](docs/sdks/referrals/README.md)
+
+* [create_code](docs/sdks/referrals/README.md#create_code) - Create or fetch a referral code for a customer in a referral program.
+* [redeem_code](docs/sdks/referrals/README.md#redeem_code) - Redeem a referral code for a customer.
+
 </details>
 <!-- End Available Resources and Operations [operations] -->
 
@@ -245,7 +282,7 @@ with Autumn(
     secret_key="<YOUR_BEARER_TOKEN_HERE>",
 ) as autumn:
 
-    res = autumn.customers.get_or_create(customer_id="cus_123", name="John Doe", email="john@example.com",
+    res = autumn.check(customer_id="cus_123", feature_id="messages",
         RetryConfig("backoff", BackoffStrategy(1, 50, 1.1, 100), False))
 
     # Handle response
@@ -265,7 +302,7 @@ with Autumn(
     secret_key="<YOUR_BEARER_TOKEN_HERE>",
 ) as autumn:
 
-    res = autumn.customers.get_or_create(customer_id="cus_123", name="John Doe", email="john@example.com")
+    res = autumn.check(customer_id="cus_123", feature_id="messages")
 
     # Handle response
     print(res)
@@ -298,7 +335,7 @@ with Autumn(
     res = None
     try:
 
-        res = autumn.customers.get_or_create(customer_id="cus_123", name="John Doe", email="john@example.com")
+        res = autumn.check(customer_id="cus_123", feature_id="messages")
 
         # Handle response
         print(res)
@@ -350,7 +387,7 @@ with Autumn(
     secret_key="<YOUR_BEARER_TOKEN_HERE>",
 ) as autumn:
 
-    res = autumn.customers.get_or_create(customer_id="cus_123", name="John Doe", email="john@example.com")
+    res = autumn.check(customer_id="cus_123", feature_id="messages")
 
     # Handle response
     print(res)

others/python-sdk/USAGE.md

@@ -9,7 +9,7 @@ with Autumn(
     secret_key="<YOUR_BEARER_TOKEN_HERE>",
 ) as autumn:
 
-    res = autumn.customers.get_or_create(customer_id="cus_123", name="John Doe", email="john@example.com")
+    res = autumn.check(customer_id="cus_123", feature_id="messages")
 
     # Handle response
     print(res)
@@ -31,7 +31,7 @@ async def main():
         secret_key="<YOUR_BEARER_TOKEN_HERE>",
     ) as autumn:
 
-        res = await autumn.customers.get_or_create_async(customer_id="cus_123", name="John Doe", email="john@example.com")
+        res = await autumn.check_async(customer_id="cus_123", feature_id="messages")
 
         # Handle response
         print(res)

others/python-sdk/docs/models/aggregateeventscustomrange.md

@@ -1,4 +1,6 @@
-# BillingPreviewAttachNextCycleEffectivePeriod
+# AggregateEventsCustomRange
+
+Custom time range to aggregate events for. If provided, range must not be provided
 
 
 ## Fields

others/python-sdk/docs/models/aggregateeventsfeatureid.md

@@ -0,0 +1,19 @@
+# AggregateEventsFeatureID
+
+Feature ID(s) to aggregate events for
+
+
+## Supported Types
+
+### `str`
+
+```python
+value: str = /* values here */
+```
+
+### `List[str]`
+
+```python
+value: List[str] = /* values here */
+```
+

others/python-sdk/docs/models/aggregateeventsglobals.md

@@ -0,0 +1,8 @@
+# AggregateEventsGlobals
+
+
+## Fields
+
+| Field              | Type               | Required           | Description        |
+| ------------------ | ------------------ | ------------------ | ------------------ |
+| `x_api_version`    | *Optional[str]*    | :heavy_minus_sign: | N/A                |

others/python-sdk/docs/models/aggregateeventslist.md

@@ -0,0 +1,10 @@
+# AggregateEventsList
+
+
+## Fields
+
+| Field                                                                                                       | Type                                                                                                        | Required                                                                                                    | Description                                                                                                 |
+| ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `period`                                                                                                    | *float*                                                                                                     | :heavy_check_mark:                                                                                          | Unix timestamp (epoch ms) for this time period                                                              |
+| `values`                                                                                                    | Dict[str, *float*]                                                                                          | :heavy_check_mark:                                                                                          | Aggregated values per feature: { [featureId]: number }                                                      |
+| `grouped_values`                                                                                            | Dict[str, Dict[str, *float*]]                                                                               | :heavy_minus_sign:                                                                                          | Values broken down by group (only present when group_by is used): { [featureId]: { [groupValue]: number } } |

others/python-sdk/docs/models/aggregateeventsresponse.md

@@ -0,0 +1,11 @@
+# AggregateEventsResponse
+
+OK
+
+
+## Fields
+
+| Field                                                                               | Type                                                                                | Required                                                                            | Description                                                                         |
+| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `list`                                                                              | List[[models.AggregateEventsList](../models/aggregateeventslist.md)]                | :heavy_check_mark:                                                                  | Array of time periods with aggregated values                                        |
+| `total`                                                                             | Dict[str, [models.Total](../models/total.md)]                                       | :heavy_check_mark:                                                                  | Total aggregations per feature. Keys are feature IDs, values contain count and sum. |

others/python-sdk/docs/models/attachparams.md

@@ -1,21 +1,20 @@
-# BillingPreviewAttachRequest
+# AttachParams
 
 
 ## Fields
 
 | Field                                                                                                                                                                                                                    | Type                                                                                                                                                                                                                     | Required                                                                                                                                                                                                                 | Description                                                                                                                                                                                                              |
-| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `customer_id`                                                                                                                                                                                                            | *str*                                                                                                                                                                                                                    | :heavy_check_mark:                                                                                                                                                                                                       | The ID of the customer to attach the plan to.                                                                                                                                                                            |
-| `entity_id`                                                                                                                                                                                            | *OptionalNullable[str]*                                                                                                                                                                                | :heavy_minus_sign:                                                                                                                                                                                     | The ID of the entity to attach the plan to.                                                                                                                                                            |
-| `feature_quantities`                                                                                                                                                                                   | List[[models.BillingPreviewAttachFeatureQuantities](../models/billingpreviewattachfeaturequantities.md)]                                                                                               | :heavy_minus_sign:                                                                                                                                                                                     | If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan. |
+| `entity_id`                                                                                                                                                                                                              | *Optional[str]*                                                                                                                                                                                                          | :heavy_minus_sign:                                                                                                                                                                                                       | The ID of the entity to attach the plan to.                                                                                                                                                                              |
+| `plan_id`                                                                                                                                                                                                                | *str*                                                                                                                                                                                                                    | :heavy_check_mark:                                                                                                                                                                                                       | The ID of the plan.                                                                                                                                                                                                      |
+| `feature_quantities`                                                                                                                                                                                                     | List[[models.BillingAttachFeatureQuantity](../models/billingattachfeaturequantity.md)]                                                                                                                                   | :heavy_minus_sign:                                                                                                                                                                                                       | If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan.                   |
 | `version`                                                                                                                                                                                                                | *Optional[float]*                                                                                                                                                                                                        | :heavy_minus_sign:                                                                                                                                                                                                       | The version of the plan to attach.                                                                                                                                                                                       |
-| `free_trial`                                                                                                                                                                                           | [OptionalNullable[models.BillingPreviewAttachFreeTrial]](../models/billingpreviewattachfreetrial.md)                                                                                                   | :heavy_minus_sign:                                                                                                                                                                                     | N/A                                                                                                                                                                                                    |
-| `customize`                                                                                                                                                                                            | [Optional[models.BillingPreviewAttachCustomize]](../models/billingpreviewattachcustomize.md)                                                                                                           | :heavy_minus_sign:                                                                                                                                                                                     | Customize the plan to attach. Can either override the price of the plan, the items in the plan, or both.                                                                                               |
-| `plan_id`                                                                                                                                                                                              | *str*                                                                                                                                                                                                  | :heavy_check_mark:                                                                                                                                                                                     | N/A                                                                                                                                                                                                    |
-| `invoice_mode`                                                                                                                                                                                         | [Optional[models.BillingPreviewAttachInvoiceMode]](../models/billingpreviewattachinvoicemode.md)                                                                                                       | :heavy_minus_sign:                                                                                                                                                                                     | N/A                                                                                                                                                                                                    |
-| `discounts`                                                                                                                                                                                            | List[[models.BillingPreviewAttachDiscountUnion](../models/billingpreviewattachdiscountunion.md)]                                                                                                       | :heavy_minus_sign:                                                                                                                                                                                     | N/A                                                                                                                                                                                                    |
-| `redirect_mode`                                                                                                                                                                                        | [Optional[models.BillingPreviewAttachRedirectMode]](../models/billingpreviewattachredirectmode.md)                                                                                                     | :heavy_minus_sign:                                                                                                                                                                                     | N/A                                                                                                                                                                                                    |
-| `success_url`                                                                                                                                                                                          | *Optional[str]*                                                                                                                                                                                        | :heavy_minus_sign:                                                                                                                                                                                     | N/A                                                                                                                                                                                                    |
-| `new_billing_subscription`                                                                                                                                                                             | *Optional[bool]*                                                                                                                                                                                       | :heavy_minus_sign:                                                                                                                                                                                     | N/A                                                                                                                                                                                                    |
-| `plan_schedule`                                                                                                                                                                                        | [Optional[models.BillingPreviewAttachPlanSchedule]](../models/billingpreviewattachplanschedule.md)                                                                                                     | :heavy_minus_sign:                                                                                                                                                                                     | N/A                                                                                                                                                                                                    |
-| `billing_behavior`                                                                                                                                                                                     | [Optional[models.BillingPreviewAttachBillingBehavior]](../models/billingpreviewattachbillingbehavior.md)                                                                                               | :heavy_minus_sign:                                                                                                                                                                                     | N/A                                                                                                                                                                                                    |
+| `free_trial`                                                                                                                                                                                                             | [OptionalNullable[models.BillingAttachFreeTrial]](../models/billingattachfreetrial.md)                                                                                                                                   | :heavy_minus_sign:                                                                                                                                                                                                       | Override the plan's default free trial. Pass an object to set a custom trial, or null to remove the trial entirely.                                                                                                      |
+| `customize`                                                                                                                                                                                                              | [Optional[models.BillingAttachCustomize]](../models/billingattachcustomize.md)                                                                                                                                           | :heavy_minus_sign:                                                                                                                                                                                                       | Customize the plan to attach. Can either override the price of the plan, the items in the plan, or both.                                                                                                                 |
+| `invoice_mode`                                                                                                                                                                                                           | [Optional[models.BillingAttachInvoiceMode]](../models/billingattachinvoicemode.md)                                                                                                                                       | :heavy_minus_sign:                                                                                                                                                                                                       | Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. This uses Stripe's send_invoice collection method.                                                |
+| `billing_behavior`                                                                                                                                                                                                       | [Optional[models.BillingAttachBillingBehavior]](../models/billingattachbillingbehavior.md)                                                                                                                               | :heavy_minus_sign:                                                                                                                                                                                                       | How to handle billing when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'next_cycle_only' skips creating any charges and applies the change at the next billing cycle. |
+| `discounts`                                                                                                                                                                                                              | List[[models.BillingAttachDiscountUnion](../models/billingattachdiscountunion.md)]                                                                                                                                       | :heavy_minus_sign:                                                                                                                                                                                                       | List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code.                                                                                                        |
+| `success_url`                                                                                                                                                                                                            | *Optional[str]*                                                                                                                                                                                                          | :heavy_minus_sign:                                                                                                                                                                                                       | URL to redirect to after successful checkout.                                                                                                                                                                            |
+| `new_billing_subscription`                                                                                                                                                                                               | *Optional[bool]*                                                                                                                                                                                                         | :heavy_minus_sign:                                                                                                                                                                                                       | Only applicable when the customer has an existing Stripe subscription. If true, creates a new separate subscription instead of merging into the existing one.                                                            |
+| `plan_schedule`                                                                                                                                                                                                          | [Optional[models.BillingAttachPlanSchedule]](../models/billingattachplanschedule.md)                                                                                                                                     | :heavy_minus_sign:                                                                                                                                                                                                       | 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.                    |

others/python-sdk/docs/models/balances.md

@@ -4,15 +4,15 @@
 ## Fields
 
 | Field                                                                         | Type                                                                          | Required                                                                      | Description                                                                   |
-| ---------------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------- |
-| `feature_id`                                                     | *str*                                                            | :heavy_check_mark:                                               | N/A                                                              |
-| `feature`                                                        | [Optional[models.CustomerFeature]](../models/customerfeature.md) | :heavy_minus_sign:                                               | N/A                                                              |
-| `granted`                                                        | *float*                                                          | :heavy_check_mark:                                               | N/A                                                              |
-| `remaining`                                                      | *float*                                                          | :heavy_check_mark:                                               | N/A                                                              |
-| `usage`                                                          | *float*                                                          | :heavy_check_mark:                                               | N/A                                                              |
-| `unlimited`                                                      | *bool*                                                           | :heavy_check_mark:                                               | N/A                                                              |
-| `overage_allowed`                                                | *bool*                                                           | :heavy_check_mark:                                               | N/A                                                              |
-| `max_purchase`                                                   | *Nullable[float]*                                                | :heavy_check_mark:                                               | N/A                                                              |
-| `next_reset_at`                                                  | *Nullable[float]*                                                | :heavy_check_mark:                                               | N/A                                                              |
-| `breakdown`                                                      | List[[models.Breakdown](../models/breakdown.md)]                 | :heavy_minus_sign:                                               | N/A                                                              |
-| `rollovers`                                                      | List[[models.CustomerRollover](../models/customerrollover.md)]   | :heavy_minus_sign:                                               | N/A                                                              |
+| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `feature_id`                                                                  | *str*                                                                         | :heavy_check_mark:                                                            | The feature ID this balance is for.                                           |
+| `feature`                                                                     | [Optional[models.CustomerFeature]](../models/customerfeature.md)              | :heavy_minus_sign:                                                            | The full feature object if expanded.                                          |
+| `granted`                                                                     | *float*                                                                       | :heavy_check_mark:                                                            | Total balance granted (included + prepaid).                                   |
+| `remaining`                                                                   | *float*                                                                       | :heavy_check_mark:                                                            | Remaining balance available for use.                                          |
+| `usage`                                                                       | *float*                                                                       | :heavy_check_mark:                                                            | Total usage consumed in the current period.                                   |
+| `unlimited`                                                                   | *bool*                                                                        | :heavy_check_mark:                                                            | Whether this feature has unlimited usage.                                     |
+| `overage_allowed`                                                             | *bool*                                                                        | :heavy_check_mark:                                                            | Whether usage beyond the granted balance is allowed (with overage charges).   |
+| `max_purchase`                                                                | *Nullable[float]*                                                             | :heavy_check_mark:                                                            | Maximum quantity that can be purchased as a top-up, or null for unlimited.    |
+| `next_reset_at`                                                               | *Nullable[float]*                                                             | :heavy_check_mark:                                                            | Timestamp when the balance will reset, or null for no reset.                  |
+| `breakdown`                                                                   | List[[models.Breakdown](../models/breakdown.md)]                              | :heavy_minus_sign:                                                            | Detailed breakdown of balance sources when stacking multiple plans or grants. |
+| `rollovers`                                                                   | List[[models.CustomerRollover](../models/customerrollover.md)]                | :heavy_minus_sign:                                                            | Rollover balances carried over from previous periods.                         |

others/python-sdk/docs/models/balancescheckbalance.md

@@ -1,18 +0,0 @@
-# BalancesCheckBalance
-
-
-## Fields
-
-| Field                                                                                  | Type                                                                                   | Required                                                                               | Description                                                                            |
-| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
-| `feature_id`                                                                           | *str*                                                                                  | :heavy_check_mark:                                                                     | N/A                                                                                    |
-| `feature`                                                                              | [Optional[models.BalancesCheckFeature]](../models/balancescheckfeature.md)             | :heavy_minus_sign:                                                                     | N/A                                                                                    |
-| `granted`                                                                              | *float*                                                                                | :heavy_check_mark:                                                                     | N/A                                                                                    |
-| `remaining`                                                                            | *float*                                                                                | :heavy_check_mark:                                                                     | N/A                                                                                    |
-| `usage`                                                                                | *float*                                                                                | :heavy_check_mark:                                                                     | N/A                                                                                    |
-| `unlimited`                                                                            | *bool*                                                                                 | :heavy_check_mark:                                                                     | N/A                                                                                    |
-| `overage_allowed`                                                                      | *bool*                                                                                 | :heavy_check_mark:                                                                     | N/A                                                                                    |
-| `max_purchase`                                                                         | *Nullable[float]*                                                                      | :heavy_check_mark:                                                                     | N/A                                                                                    |
-| `next_reset_at`                                                                        | *Nullable[float]*                                                                      | :heavy_check_mark:                                                                     | N/A                                                                                    |
-| `breakdown`                                                                            | List[[models.BalancesCheckBreakdown](../models/balancescheckbreakdown.md)]             | :heavy_minus_sign:                                                                     | N/A                                                                                    |
-| `rollovers`                                                                            | List[[models.BalancesCheckBalanceRollover](../models/balancescheckbalancerollover.md)] | :heavy_minus_sign:                                                                     | N/A                                                                                    |

others/python-sdk/docs/models/balancescheckbalancerollover.md

@@ -1,9 +0,0 @@
-# BalancesCheckBalanceRollover
-
-
-## Fields
-
-| Field              | Type               | Required           | Description        |
-| ------------------ | ------------------ | ------------------ | ------------------ |
-| `balance`          | *float*            | :heavy_check_mark: | N/A                |
-| `expires_at`       | *float*            | :heavy_check_mark: | N/A                |

others/python-sdk/docs/models/balancescheckbreakdown.md

@@ -1,17 +0,0 @@
-# BalancesCheckBreakdown
-
-
-## Fields
-
-| Field                                                                  | Type                                                                   | Required                                                               | Description                                                            |
-| ---------------------------------------------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| `id`                                                                   | *Optional[str]*                                                        | :heavy_minus_sign:                                                     | N/A                                                                    |
-| `plan_id`                                                              | *Nullable[str]*                                                        | :heavy_check_mark:                                                     | N/A                                                                    |
-| `included_grant`                                                       | *float*                                                                | :heavy_check_mark:                                                     | N/A                                                                    |
-| `prepaid_grant`                                                        | *float*                                                                | :heavy_check_mark:                                                     | N/A                                                                    |
-| `remaining`                                                            | *float*                                                                | :heavy_check_mark:                                                     | N/A                                                                    |
-| `usage`                                                                | *float*                                                                | :heavy_check_mark:                                                     | N/A                                                                    |
-| `unlimited`                                                            | *bool*                                                                 | :heavy_check_mark:                                                     | N/A                                                                    |
-| `reset`                                                                | [Nullable[models.BalancesCheckReset]](../models/balancescheckreset.md) | :heavy_check_mark:                                                     | N/A                                                                    |
-| `price`                                                                | [Nullable[models.BalancesCheckPrice]](../models/balancescheckprice.md) | :heavy_check_mark:                                                     | N/A                                                                    |
-| `expires_at`                                                           | *Nullable[float]*                                                      | :heavy_check_mark:                                                     | N/A                                                                    |

others/python-sdk/docs/models/balancescheckintervalunion.md

@@ -1,17 +0,0 @@
-# BalancesCheckIntervalUnion
-
-
-## Supported Types
-
-### `models.BalancesCheckBalanceIntervalEnum`
-
-```python
-value: models.BalancesCheckBalanceIntervalEnum = /* values here */
-```
-
-### `str`
-
-```python
-value: str = /* values here */
-```
-

others/python-sdk/docs/models/balancescheckprice.md

@@ -1,12 +0,0 @@
-# BalancesCheckPrice
-
-
-## Fields
-
-| Field                                                                        | Type                                                                         | Required                                                                     | Description                                                                  |
-| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
-| `amount`                                                                     | *Optional[float]*                                                            | :heavy_minus_sign:                                                           | N/A                                                                          |
-| `tiers`                                                                      | List[[models.BalancesCheckTier](../models/balanceschecktier.md)]             | :heavy_minus_sign:                                                           | N/A                                                                          |
-| `billing_units`                                                              | *float*                                                                      | :heavy_check_mark:                                                           | N/A                                                                          |
-| `billing_method`                                                             | [models.BalancesCheckBillingMethod](../models/balancescheckbillingmethod.md) | :heavy_check_mark:                                                           | N/A                                                                          |
-| `max_purchase`                                                               | *Nullable[float]*                                                            | :heavy_check_mark:                                                           | N/A                                                                          |

others/python-sdk/docs/models/balancescheckrequest.md

@@ -1,14 +0,0 @@
-# BalancesCheckRequest
-
-
-## Fields
-
-| Field                                                                                                                                       | Type                                                                                                                                        | Required                                                                                                                                    | Description                                                                                                                                 |
-| ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| `customer_id`                                                                                                                               | *str*                                                                                                                                       | :heavy_check_mark:                                                                                                                          | ID which you provided when creating the customer                                                                                            |
-| `feature_id`                                                                                                                                | *str*                                                                                                                                       | :heavy_check_mark:                                                                                                                          | ID of the feature to check access to.                                                                                                       |
-| `entity_id`                                                                                                                                 | *Optional[str]*                                                                                                                             | :heavy_minus_sign:                                                                                                                          | If using entity balances (eg, seats), the entity ID to check access for.                                                                    |
-| `required_balance`                                                                                                                          | *Optional[float]*                                                                                                                           | :heavy_minus_sign:                                                                                                                          | If you know the amount of the feature the end user is consuming in advance. If their balance is below this quantity, allowed will be false. |
-| `properties`                                                                                                                                | Dict[str, *Any*]                                                                                                                            | :heavy_minus_sign:                                                                                                                          | N/A                                                                                                                                         |
-| `send_event`                                                                                                                                | *Optional[bool]*                                                                                                                            | :heavy_minus_sign:                                                                                                                          | If true, a usage event will be recorded together with checking access. The required_balance field will be used as the usage value.          |
-| `with_preview`                                                                                                                              | *Optional[bool]*                                                                                                                            | :heavy_minus_sign:                                                                                                                          | If true, the response will include a preview object, which can be used to display information such as a paywall or upgrade confirmation.    |

others/python-sdk/docs/models/balancescheckresponse.md

@@ -1,15 +0,0 @@
-# BalancesCheckResponse
-
-OK
-
-
-## Fields
-
-| Field                                                                      | Type                                                                       | Required                                                                   | Description                                                                |
-| -------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| `allowed`                                                                  | *bool*                                                                     | :heavy_check_mark:                                                         | N/A                                                                        |
-| `customer_id`                                                              | *str*                                                                      | :heavy_check_mark:                                                         | N/A                                                                        |
-| `entity_id`                                                                | *OptionalNullable[str]*                                                    | :heavy_minus_sign:                                                         | N/A                                                                        |
-| `required_balance`                                                         | *Optional[float]*                                                          | :heavy_minus_sign:                                                         | N/A                                                                        |
-| `balance`                                                                  | [Nullable[models.BalancesCheckBalance]](../models/balancescheckbalance.md) | :heavy_check_mark:                                                         | N/A                                                                        |
-| `preview`                                                                  | [Optional[models.Preview]](../models/preview.md)                           | :heavy_minus_sign:                                                         | N/A                                                                        |

others/python-sdk/docs/models/balancescheckscenario.md

@@ -1,9 +0,0 @@
-# BalancesCheckScenario
-
-
-## Values
-
-| Name           | Value          |
-| -------------- | -------------- |
-| `USAGE_LIMIT`  | usage_limit    |
-| `FEATURE_FLAG` | feature_flag   |

others/python-sdk/docs/models/balanceschecktier.md

@@ -1,9 +0,0 @@
-# BalancesCheckTier
-
-
-## Fields
-
-| Field                                                                | Type                                                                 | Required                                                             | Description                                                          |
-| -------------------------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| `to`                                                                 | [models.BalancesCheckBalanceTo](../models/balancescheckbalanceto.md) | :heavy_check_mark:                                                   | N/A                                                                  |
-| `amount`                                                             | *float*                                                              | :heavy_check_mark:                                                   | N/A                                                                  |

others/python-sdk/docs/models/balancescreaterequest.md

@@ -1,15 +0,0 @@
-# BalancesCreateRequest
-
-
-## Fields
-
-| Field                                                                    | Type                                                                     | Required                                                                 | Description                                                              |
-| ------------------------------------------------------------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
-| `feature_id`                                                             | *str*                                                                    | :heavy_check_mark:                                                       | The feature ID to create the balance for                                 |
-| `customer_id`                                                            | *str*                                                                    | :heavy_check_mark:                                                       | The customer ID to assign the balance to                                 |
-| `entity_id`                                                              | *Optional[str]*                                                          | :heavy_minus_sign:                                                       | Entity ID for entity-scoped balances                                     |
-| `included`                                                               | *Optional[float]*                                                        | :heavy_minus_sign:                                                       | The initial balance amount to grant                                      |
-| `unlimited`                                                              | *Optional[bool]*                                                         | :heavy_minus_sign:                                                       | Whether the balance is unlimited                                         |
-| `reset`                                                                  | [Optional[models.BalancesCreateReset]](../models/balancescreatereset.md) | :heavy_minus_sign:                                                       | Reset configuration for the balance                                      |
-| `expires_at`                                                             | *Optional[float]*                                                        | :heavy_minus_sign:                                                       | Unix timestamp (milliseconds) when the balance expires                   |
-| `granted_balance`                                                        | *Optional[float]*                                                        | :heavy_minus_sign:                                                       | N/A                                                                      |

others/python-sdk/docs/models/balancescreatereset.md

@@ -1,11 +0,0 @@
-# BalancesCreateReset
-
-Reset configuration for the balance
-
-
-## Fields
-
-| Field                                                                | Type                                                                 | Required                                                             | Description                                                          |
-| -------------------------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| `interval`                                                           | [models.BalancesCreateInterval](../models/balancescreateinterval.md) | :heavy_check_mark:                                                   | N/A                                                                  |
-| `interval_count`                                                     | *Optional[float]*                                                    | :heavy_minus_sign:                                                   | N/A                                                                  |

others/python-sdk/docs/models/balancestrackbalance.md

@@ -1,18 +0,0 @@
-# BalancesTrackBalance
-
-
-## Fields
-
-| Field                                                                                    | Type                                                                                     | Required                                                                                 | Description                                                                              |
-| ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
-| `feature_id`                                                                             | *str*                                                                                    | :heavy_check_mark:                                                                       | N/A                                                                                      |
-| `feature`                                                                                | [Optional[models.BalancesTrackBalanceFeature]](../models/balancestrackbalancefeature.md) | :heavy_minus_sign:                                                                       | N/A                                                                                      |
-| `granted`                                                                                | *float*                                                                                  | :heavy_check_mark:                                                                       | N/A                                                                                      |
-| `remaining`                                                                              | *float*                                                                                  | :heavy_check_mark:                                                                       | N/A                                                                                      |
-| `usage`                                                                                  | *float*                                                                                  | :heavy_check_mark:                                                                       | N/A                                                                                      |
-| `unlimited`                                                                              | *bool*                                                                                   | :heavy_check_mark:                                                                       | N/A                                                                                      |
-| `overage_allowed`                                                                        | *bool*                                                                                   | :heavy_check_mark:                                                                       | N/A                                                                                      |
-| `max_purchase`                                                                           | *Nullable[float]*                                                                        | :heavy_check_mark:                                                                       | N/A                                                                                      |
-| `next_reset_at`                                                                          | *Nullable[float]*                                                                        | :heavy_check_mark:                                                                       | N/A                                                                                      |
-| `breakdown`                                                                              | List[[models.BalancesTrackBalanceBreakdown](../models/balancestrackbalancebreakdown.md)] | :heavy_minus_sign:                                                                       | N/A                                                                                      |
-| `rollovers`                                                                              | List[[models.BalancesTrackBalanceRollover](../models/balancestrackbalancerollover.md)]   | :heavy_minus_sign:                                                                       | N/A                                                                                      |

others/python-sdk/docs/models/balancestrackbalancebreakdown.md

@@ -1,17 +0,0 @@
-# BalancesTrackBalanceBreakdown
-
-
-## Fields
-
-| Field                                                                                | Type                                                                                 | Required                                                                             | Description                                                                          |
-| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
-| `id`                                                                                 | *Optional[str]*                                                                      | :heavy_minus_sign:                                                                   | N/A                                                                                  |
-| `plan_id`                                                                            | *Nullable[str]*                                                                      | :heavy_check_mark:                                                                   | N/A                                                                                  |
-| `included_grant`                                                                     | *float*                                                                              | :heavy_check_mark:                                                                   | N/A                                                                                  |
-| `prepaid_grant`                                                                      | *float*                                                                              | :heavy_check_mark:                                                                   | N/A                                                                                  |
-| `remaining`                                                                          | *float*                                                                              | :heavy_check_mark:                                                                   | N/A                                                                                  |
-| `usage`                                                                              | *float*                                                                              | :heavy_check_mark:                                                                   | N/A                                                                                  |
-| `unlimited`                                                                          | *bool*                                                                               | :heavy_check_mark:                                                                   | N/A                                                                                  |
-| `reset`                                                                              | [Nullable[models.BalancesTrackBalanceReset]](../models/balancestrackbalancereset.md) | :heavy_check_mark:                                                                   | N/A                                                                                  |
-| `price`                                                                              | [Nullable[models.BalancesTrackBalancePrice]](../models/balancestrackbalanceprice.md) | :heavy_check_mark:                                                                   | N/A                                                                                  |
-| `expires_at`                                                                         | *Nullable[float]*                                                                    | :heavy_check_mark:                                                                   | N/A                                                                                  |

others/python-sdk/docs/models/balancestrackbalancecreditschema.md

@@ -1,9 +0,0 @@
-# BalancesTrackBalanceCreditSchema
-
-
-## Fields
-
-| Field                | Type                 | Required             | Description          |
-| -------------------- | -------------------- | -------------------- | -------------------- |
-| `metered_feature_id` | *str*                | :heavy_check_mark:   | N/A                  |
-| `credit_cost`        | *float*              | :heavy_check_mark:   | N/A                  |

others/python-sdk/docs/models/balancestrackbalancedisplay.md

@@ -1,9 +0,0 @@
-# BalancesTrackBalanceDisplay
-
-
-## Fields
-
-| Field                   | Type                    | Required                | Description             |
-| ----------------------- | ----------------------- | ----------------------- | ----------------------- |
-| `singular`              | *OptionalNullable[str]* | :heavy_minus_sign:      | N/A                     |
-| `plural`                | *OptionalNullable[str]* | :heavy_minus_sign:      | N/A                     |

others/python-sdk/docs/models/balancestrackbalancefeature.md

@@ -1,15 +0,0 @@
-# BalancesTrackBalanceFeature
-
-
-## Fields
-
-| Field                                                                                          | Type                                                                                           | Required                                                                                       | Description                                                                                    |
-| ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| `id`                                                                                           | *str*                                                                                          | :heavy_check_mark:                                                                             | N/A                                                                                            |
-| `name`                                                                                         | *str*                                                                                          | :heavy_check_mark:                                                                             | N/A                                                                                            |
-| `type`                                                                                         | [models.BalancesTrackBalanceType](../models/balancestrackbalancetype.md)                       | :heavy_check_mark:                                                                             | N/A                                                                                            |
-| `consumable`                                                                                   | *bool*                                                                                         | :heavy_check_mark:                                                                             | N/A                                                                                            |
-| `event_names`                                                                                  | List[*str*]                                                                                    | :heavy_minus_sign:                                                                             | N/A                                                                                            |
-| `credit_schema`                                                                                | List[[models.BalancesTrackBalanceCreditSchema](../models/balancestrackbalancecreditschema.md)] | :heavy_minus_sign:                                                                             | N/A                                                                                            |
-| `display`                                                                                      | [Optional[models.BalancesTrackBalanceDisplay]](../models/balancestrackbalancedisplay.md)       | :heavy_minus_sign:                                                                             | N/A                                                                                            |
-| `archived`                                                                                     | *bool*                                                                                         | :heavy_check_mark:                                                                             | N/A                                                                                            |

others/python-sdk/docs/models/balancestrackbalanceintervalenum.md

@@ -1,16 +0,0 @@
-# BalancesTrackBalanceIntervalEnum
-
-
-## Values
-
-| Name          | Value         |
-| ------------- | ------------- |
-| `ONE_OFF`     | one_off       |
-| `MINUTE`      | minute        |
-| `HOUR`        | hour          |
-| `DAY`         | day           |
-| `WEEK`        | week          |
-| `MONTH`       | month         |
-| `QUARTER`     | quarter       |
-| `SEMI_ANNUAL` | semi_annual   |
-| `YEAR`        | year          |

others/python-sdk/docs/models/balancestrackbalanceintervalunion.md

@@ -1,17 +0,0 @@
-# BalancesTrackBalanceIntervalUnion
-
-
-## Supported Types
-
-### `models.BalancesTrackBalanceIntervalEnum`
-
-```python
-value: models.BalancesTrackBalanceIntervalEnum = /* values here */
-```
-
-### `str`
-
-```python
-value: str = /* values here */
-```
-

others/python-sdk/docs/models/balancestrackbalanceprice.md

@@ -1,12 +0,0 @@
-# BalancesTrackBalancePrice
-
-
-## Fields
-
-| Field                                                                                      | Type                                                                                       | Required                                                                                   | Description                                                                                |
-| ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
-| `amount`                                                                                   | *Optional[float]*                                                                          | :heavy_minus_sign:                                                                         | N/A                                                                                        |
-| `tiers`                                                                                    | List[[models.BalancesTrackBalanceTier](../models/balancestrackbalancetier.md)]             | :heavy_minus_sign:                                                                         | N/A                                                                                        |
-| `billing_units`                                                                            | *float*                                                                                    | :heavy_check_mark:                                                                         | N/A                                                                                        |
-| `billing_method`                                                                           | [models.BalancesTrackBalanceBillingMethod](../models/balancestrackbalancebillingmethod.md) | :heavy_check_mark:                                                                         | N/A                                                                                        |
-| `max_purchase`                                                                             | *Nullable[float]*                                                                          | :heavy_check_mark:                                                                         | N/A                                                                                        |

others/python-sdk/docs/models/balancestrackbalancerollover.md

@@ -1,9 +0,0 @@
-# BalancesTrackBalanceRollover
-
-
-## Fields
-
-| Field              | Type               | Required           | Description        |
-| ------------------ | ------------------ | ------------------ | ------------------ |
-| `balance`          | *float*            | :heavy_check_mark: | N/A                |
-| `expires_at`       | *float*            | :heavy_check_mark: | N/A                |

others/python-sdk/docs/models/balancestrackbalances.md

@@ -1,18 +0,0 @@
-# BalancesTrackBalances
-
-
-## Fields
-
-| Field                                                                      | Type                                                                       | Required                                                                   | Description                                                                |
-| -------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| `feature_id`                                                               | *str*                                                                      | :heavy_check_mark:                                                         | N/A                                                                        |
-| `feature`                                                                  | [Optional[models.BalancesTrackFeature]](../models/balancestrackfeature.md) | :heavy_minus_sign:                                                         | N/A                                                                        |
-| `granted`                                                                  | *float*                                                                    | :heavy_check_mark:                                                         | N/A                                                                        |
-| `remaining`                                                                | *float*                                                                    | :heavy_check_mark:                                                         | N/A                                                                        |
-| `usage`                                                                    | *float*                                                                    | :heavy_check_mark:                                                         | N/A                                                                        |
-| `unlimited`                                                                | *bool*                                                                     | :heavy_check_mark:                                                         | N/A                                                                        |
-| `overage_allowed`                                                          | *bool*                                                                     | :heavy_check_mark:                                                         | N/A                                                                        |
-| `max_purchase`                                                             | *Nullable[float]*                                                          | :heavy_check_mark:                                                         | N/A                                                                        |
-| `next_reset_at`                                                            | *Nullable[float]*                                                          | :heavy_check_mark:                                                         | N/A                                                                        |
-| `breakdown`                                                                | List[[models.BalancesTrackBreakdown](../models/balancestrackbreakdown.md)] | :heavy_minus_sign:                                                         | N/A                                                                        |
-| `rollovers`                                                                | List[[models.BalancesTrackRollover](../models/balancestrackrollover.md)]   | :heavy_minus_sign:                                                         | N/A                                                                        |

others/python-sdk/docs/models/balancestrackbalancetier.md

@@ -1,9 +0,0 @@
-# BalancesTrackBalanceTier
-
-
-## Fields
-
-| Field                                                                | Type                                                                 | Required                                                             | Description                                                          |
-| -------------------------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| `to`                                                                 | [models.BalancesTrackBalanceTo](../models/balancestrackbalanceto.md) | :heavy_check_mark:                                                   | N/A                                                                  |
-| `amount`                                                             | *float*                                                              | :heavy_check_mark:                                                   | N/A                                                                  |

others/python-sdk/docs/models/balancestrackbalancetype.md

@@ -1,10 +0,0 @@
-# BalancesTrackBalanceType
-
-
-## Values
-
-| Name            | Value           |
-| --------------- | --------------- |
-| `BOOLEAN`       | boolean         |
-| `METERED`       | metered         |
-| `CREDIT_SYSTEM` | credit_system   |

others/python-sdk/docs/models/balancestrackbreakdown.md

@@ -1,17 +0,0 @@
-# BalancesTrackBreakdown
-
-
-## Fields
-
-| Field                                                                  | Type                                                                   | Required                                                               | Description                                                            |
-| ---------------------------------------------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| `id`                                                                   | *Optional[str]*                                                        | :heavy_minus_sign:                                                     | N/A                                                                    |
-| `plan_id`                                                              | *Nullable[str]*                                                        | :heavy_check_mark:                                                     | N/A                                                                    |
-| `included_grant`                                                       | *float*                                                                | :heavy_check_mark:                                                     | N/A                                                                    |
-| `prepaid_grant`                                                        | *float*                                                                | :heavy_check_mark:                                                     | N/A                                                                    |
-| `remaining`                                                            | *float*                                                                | :heavy_check_mark:                                                     | N/A                                                                    |
-| `usage`                                                                | *float*                                                                | :heavy_check_mark:                                                     | N/A                                                                    |
-| `unlimited`                                                            | *bool*                                                                 | :heavy_check_mark:                                                     | N/A                                                                    |
-| `reset`                                                                | [Nullable[models.BalancesTrackReset]](../models/balancestrackreset.md) | :heavy_check_mark:                                                     | N/A                                                                    |
-| `price`                                                                | [Nullable[models.BalancesTrackPrice]](../models/balancestrackprice.md) | :heavy_check_mark:                                                     | N/A                                                                    |
-| `expires_at`                                                           | *Nullable[float]*                                                      | :heavy_check_mark:                                                     | N/A                                                                    |

others/python-sdk/docs/models/balancestrackintervalunion.md

@@ -1,17 +0,0 @@
-# BalancesTrackIntervalUnion
-
-
-## Supported Types
-
-### `models.BalancesTrackIntervalEnum`
-
-```python
-value: models.BalancesTrackIntervalEnum = /* values here */
-```
-
-### `str`
-
-```python
-value: str = /* values here */
-```
-

others/python-sdk/docs/models/balancestrackrequest.md

@@ -1,14 +0,0 @@
-# BalancesTrackRequest
-
-
-## Fields
-
-| Field                                                                                                                                                                | Type                                                                                                                                                                 | Required                                                                                                                                                             | Description                                                                                                                                                          |
-| -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `customer_id`                                                                                                                                                        | *str*                                                                                                                                                                | :heavy_check_mark:                                                                                                                                                   | ID which you provided when creating the customer                                                                                                                     |
-| `feature_id`                                                                                                                                                         | *Optional[str]*                                                                                                                                                      | :heavy_minus_sign:                                                                                                                                                   | ID of the feature to track usage for. Required if event_name is not provided. Use this for direct feature tracking.                                                  |
-| `event_name`                                                                                                                                                         | *Optional[str]*                                                                                                                                                      | :heavy_minus_sign:                                                                                                                                                   | An [event name](/features/tracking-usage#using-event-names) can be used in place of feature_id. This can be used if multiple features are tracked in the same event. |
-| `value`                                                                                                                                                              | *Optional[float]*                                                                                                                                                    | :heavy_minus_sign:                                                                                                                                                   | The amount of usage to record. Defaults to 1. Can be negative to increase the balance (e.g., when removing a seat).                                                  |
-| `properties`                                                                                                                                                         | Dict[str, *Any*]                                                                                                                                                     | :heavy_minus_sign:                                                                                                                                                   | Additional properties to attach to this usage event.                                                                                                                 |
-| `idempotency_key`                                                                                                                                                    | *Optional[str]*                                                                                                                                                      | :heavy_minus_sign:                                                                                                                                                   | Unique key to prevent duplicate event recording. Use this to safely retry requests without creating duplicate usage records.                                         |
-| `entity_id`                                                                                                                                                          | *Optional[str]*                                                                                                                                                      | :heavy_minus_sign:                                                                                                                                                   | If using [entity balances](/features/feature-entities) (eg, seats), the entity ID to track usage for.                                                                |

others/python-sdk/docs/models/balancestrackresponse.md

@@ -1,15 +0,0 @@
-# BalancesTrackResponse
-
-OK
-
-
-## Fields
-
-| Field                                                                         | Type                                                                          | Required                                                                      | Description                                                                   |
-| ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| `customer_id`                                                                 | *str*                                                                         | :heavy_check_mark:                                                            | The ID of the customer                                                        |
-| `entity_id`                                                                   | *Optional[str]*                                                               | :heavy_minus_sign:                                                            | The ID of the entity (if provided)                                            |
-| `event_name`                                                                  | *Optional[str]*                                                               | :heavy_minus_sign:                                                            | The name of the event                                                         |
-| `value`                                                                       | *float*                                                                       | :heavy_check_mark:                                                            | N/A                                                                           |
-| `balance`                                                                     | [Nullable[models.BalancesTrackBalance]](../models/balancestrackbalance.md)    | :heavy_check_mark:                                                            | N/A                                                                           |
-| `balances`                                                                    | Dict[str, [models.BalancesTrackBalances](../models/balancestrackbalances.md)] | :heavy_minus_sign:                                                            | N/A                                                                           |

others/python-sdk/docs/models/balancestrackrollover.md

@@ -1,9 +0,0 @@
-# BalancesTrackRollover
-
-
-## Fields
-
-| Field              | Type               | Required           | Description        |
-| ------------------ | ------------------ | ------------------ | ------------------ |
-| `balance`          | *float*            | :heavy_check_mark: | N/A                |
-| `expires_at`       | *float*            | :heavy_check_mark: | N/A                |

others/python-sdk/docs/models/balancesupdaterequest.md

@@ -1,17 +0,0 @@
-# BalancesUpdateRequest
-
-
-## Fields
-
-| Field                                                                          | Type                                                                           | Required                                                                       | Description                                                                    |
-| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
-| `customer_id`                                                                  | *str*                                                                          | :heavy_check_mark:                                                             | The ID of the customer.                                                        |
-| `entity_id`                                                                    | *Optional[str]*                                                                | :heavy_minus_sign:                                                             | The ID of the entity to update balance for (if using entity balances).         |
-| `feature_id`                                                                   | *str*                                                                          | :heavy_check_mark:                                                             | The ID of the feature to update balance for.                                   |
-| `current_balance`                                                              | *Optional[float]*                                                              | :heavy_minus_sign:                                                             | The new balance value to set.                                                  |
-| `interval`                                                                     | [Optional[models.BalancesUpdateInterval]](../models/balancesupdateinterval.md) | :heavy_minus_sign:                                                             | The interval to update balance for.                                            |
-| `granted_balance`                                                              | *Optional[float]*                                                              | :heavy_minus_sign:                                                             | N/A                                                                            |
-| `usage`                                                                        | *Optional[float]*                                                              | :heavy_minus_sign:                                                             | N/A                                                                            |
-| `customer_entitlement_id`                                                      | *Optional[str]*                                                                | :heavy_minus_sign:                                                             | N/A                                                                            |
-| `next_reset_at`                                                                | *Optional[float]*                                                              | :heavy_minus_sign:                                                             | N/A                                                                            |
-| `add_to_balance`                                                               | *Optional[float]*                                                              | :heavy_minus_sign:                                                             | N/A                                                                            |

others/python-sdk/docs/models/billingattachbillingbehavior.md

@@ -1,5 +1,7 @@
 # BillingAttachBillingBehavior
 
+How to handle billing when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'next_cycle_only' skips creating any charges and applies the change at the next billing cycle.
+
 
 ## Values
 

others/python-sdk/docs/models/billingattachcode.md

@@ -1,5 +1,7 @@
 # BillingAttachCode
 
+The type of action required to complete the payment.
+
 
 ## Values
 

others/python-sdk/docs/models/billingattachdiscount1.md

@@ -4,5 +4,5 @@
 ## Fields
 
 | Field                                        | Type                                         | Required                                     | Description                                  |
-| ------------------ | ------------------ | ------------------ | ------------------ |
-| `reward_id`        | *str*              | :heavy_check_mark: | N/A                |
+| -------------------------------------------- | -------------------------------------------- | -------------------------------------------- | -------------------------------------------- |
+| `reward_id`                                  | *str*                                        | :heavy_check_mark:                           | The ID of the reward to apply as a discount. |

others/python-sdk/docs/models/billingattachdiscount2.md

@@ -4,5 +4,5 @@
 ## Fields
 
 | Field                                      | Type                                       | Required                                   | Description                                |
-| ------------------ | ------------------ | ------------------ | ------------------ |
-| `promotion_code`   | *str*              | :heavy_check_mark: | N/A                |
+| ------------------------------------------ | ------------------------------------------ | ------------------------------------------ | ------------------------------------------ |
+| `promotion_code`                           | *str*                                      | :heavy_check_mark:                         | The promotion code to apply as a discount. |

others/python-sdk/docs/models/billingattachdiscountunion.md

@@ -1,5 +1,7 @@
 # BillingAttachDiscountUnion
 
+A discount to apply. Can be either a reward ID or a promotion code.
+
 
 ## Supported Types
 

others/python-sdk/docs/models/billingattachfeaturequantity.md

@@ -1,4 +1,4 @@
-# BillingUpdateFeatureQuantities
+# BillingAttachFeatureQuantity
 
 
 ## Fields