### Configure Environment Variables and Install SDK

Source: https://docs.useautumn.com/documentation/getting-started/setup

Setting up the required secret key in the .env file and installing the Autumn SDK package.

```bash
AUTUMN_SECRET_KEY=am_sk_test_42424242...
```

```bash
bun add autumn-js
```

```bash
npm install autumn-js
```

--------------------------------

### Install Autumn SDKs

Source: https://docs.useautumn.com/documentation/getting-started/setup

Install the necessary Autumn SDKs for your project using different package managers. This step ensures you have the required libraries to interact with Autumn's services.

```bash
npm install autumn-js
```

```bash
pnpm add autumn-js
```

```bash
yarn add autumn-js
```

```bash
pip install autumn-sdk
```

--------------------------------

### Install Autumn SDK

Source: https://docs.useautumn.com/documentation/getting-started/setup

Install the Autumn SDK package using your preferred package manager. This library should be installed in both frontend and backend environments if they are separate.

```bun
bun add autumn-js
```

```npm
npm install autumn-js
```

```pnpm
pnpm add autumn-js
```

```yarn
yarn add autumn-js
```

--------------------------------

### POST /plan/setup

Source: https://docs.useautumn.com/api-reference/billing/setupPayment

Configures plan carry-over settings for balances and usages and returns a payment setup URL.

```APIDOC
## POST /plan/setup

### Description
Configures how balances and usages are carried over from a previous plan and returns a URL to complete the payment setup.

### Method
POST

### Endpoint
/plan/setup

### Parameters
#### Request Body
- **carry_over_balances** (object) - Optional - Settings for carrying over balances.
  - **enabled** (boolean) - Required - Whether to carry over balances.
  - **feature_ids** (string[]) - Optional - Specific feature IDs to carry over.
- **carry_over_usages** (object) - Optional - Settings for carrying over usages.
  - **enabled** (boolean) - Required - Whether to carry over usages.
  - **feature_ids** (string[]) - Optional - Specific feature IDs to carry over.

### Request Example
{
  "carry_over_balances": {
    "enabled": true,
    "feature_ids": ["feat_1"]
  },
  "carry_over_usages": {
    "enabled": true
  }
}

### Response
#### Success Response (200)
- **customer_id** (string) - The ID of the customer.
- **entity_id** (string) - The ID of the entity the plan will be attached to.
- **url** (string) - URL to redirect the customer to setup their payment.

#### Response Example
{
  "customer_id": "cus_123",
  "url": "https://checkout.stripe.com/..."
}
```

--------------------------------

### PreviewUpdateParams Configuration Example

Source: https://docs.useautumn.com/api-reference/billing/previewUpdate

A YAML-based configuration example demonstrating how to structure the PreviewUpdateParams object, including customer identification, plan selection, and feature quantity adjustments.

```yaml
customer_id: cus_123
plan_id: pro_plan
feature_quantities:
  - feature_id: seats
    quantity: 15
```

--------------------------------

### autumnHandler Setup

Source: https://docs.useautumn.com/react/hooks/autumn-handler

This example demonstrates how to set up the autumnHandler in a Next.js application for handling API requests and customer authentication.

```APIDOC
## POST /api/autumn/[...all]

### Description
Handles incoming API requests and customer authentication for Autumn.

### Method
POST

### Endpoint
/api/autumn/[...all]

### Parameters
#### Request Body
- **identify** (request: Request) => AuthResult - Required - Function that receives the incoming request and returns customer identification data.
  - **customerId** (string) - Required - The unique identifier for the customer.
  - **customerData** (CustomerData) - Optional - Additional metadata about the customer (e.g., `name`, `email`).
- **secretKey** (string) - Optional - Autumn API secret key. Defaults to `AUTUMN_SECRET_KEY` environment variable.
- **autumnURL** (string) - Optional - Override the Autumn API URL. Use when self-hosting.
- **pathPrefix** (string) - Optional - Path prefix for routes. Defaults to `/api/autumn`.
- **suppressLogs** (boolean) - Optional - If true, suppresses console warnings and logs.

### Request Example
```ts
// app/api/autumn/[...all]/route.ts
import { autumnHandler } from "autumn-js/next";
import { auth } from "@clerk/nextjs/server";

export const { GET, POST } = autumnHandler({
  identify: async () => {
    const { userId } = await auth();
    return { customerId: userId };
  },
});
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### POST /setup_payment

Source: https://docs.useautumn.com/api-reference/billing/setupPayment

Initiates the payment setup process for a customer. This endpoint allows for applying discounts, specifying success URLs, and configuring subscription parameters.

```APIDOC
## POST /setup_payment

### Description
Initiates the payment setup process for a customer. This endpoint allows for applying discounts, specifying success URLs, and configuring subscription parameters.

### Method
POST

### Endpoint
/setup_payment

### Parameters
#### Request Body
- **customer_id** (string) - Required - The ID of the customer.
- **discounts** (array) - Optional - List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code.
  - **reward_id** (string) - Optional - The ID of the reward to apply as a discount.
  - **promotion_code** (string) - Optional - The promotion code to apply as a discount.
- **success_url** (string) - Optional - URL to redirect to after successful checkout.
- **checkout_session_params** (object) - Optional - Additional parameters to pass into the creation of the Stripe checkout session.
- **custom_line_items** (array) - Optional - Custom line items that override the auto-generated proration invoice. Only valid for immediate plan changes (eg. upgrades or one off plans).
  - **amount** (number) - Required - Amount in dollars for this line item (e.g. 10.50). Can be negative for credits.
  - **description** (string) - Required - Description for the line item.
- **processor_subscription_id** (string) - Optional - The processor subscription ID to link. Use this to attach an existing Stripe subscription instead of creating a new one.
- **carry_over_balances** (object) - Optional - Whether to carry over balances from the previous plan.
  - **enabled** (boolean) - Required - Whether to carry over balances from the previous plan.
  - **feature_ids** (array) - Optional - The IDs of the features to carry over balances from. If left undefined, all features will be carried over.
- **carry_over_usages** (object) - Optional - Whether to carry over usages from the previous plan.
  - **enabled** (boolean) - Required - Whether to carry over usages from the previous plan.
  - **feature_ids** (array) - Optional - The IDs of the features to carry over usages for. If left undefined, all consumable features will be carried over.

### Request Example
```json
{
  "customer_id": "cus_123",
  "success_url": "https://example.com/account/billing",
  "discounts": [
    {
      "reward_id": "rew_abc"
    },
    {
      "promotion_code": "SUMMER20"
    }
  ],
  "custom_line_items": [
    {
      "amount": 10.50,
      "description": "Premium Plan Upgrade"
    }
  ],
  "carry_over_balances": {
    "enabled": true,
    "feature_ids": ["feat_1", "feat_2"]
  }
}
```

### Response
#### Success Response (200)
- **customer_id** (string) - The ID of the customer.
- **entity_id** (string) - The ID of the entity the plan (if specified) will be attached to after setup.
- **url** (string) - URL to redirect the customer to setup their payment.

#### Response Example
```json
{
  "customer_id": "cus_123",
  "entity_id": "ent_xyz",
  "url": "https://checkout.stripe.com/pay/cs_test_..."
}
```
```

--------------------------------

### Handle Customer Setup Response

Source: https://docs.useautumn.com/api-reference/billing/setupPayment

Represents the successful response from the customer setup endpoint. It returns the unique customer identifier and a redirect URL for payment processing.

```json
{
  "customer_id": "cus_123",
  "url": "https://checkout.stripe.com/..."
}
```

--------------------------------

### POST /v1/billing.setup_payment

Source: https://docs.useautumn.com/api-reference/billing/setupPayment

Creates a payment setup session for a customer to add or update their payment method. This is used for initiating payment setup for a customer.

```APIDOC
## POST /v1/billing.setup_payment

### Description
Create a payment setup session for a customer to add or update their payment method.

### Method
POST

### Endpoint
https://api.useautumn.com/v1/billing.setup_payment

### Parameters
#### Header Parameters
- **x-api-version** (string) - Required - Specifies the API version, defaults to '2.1'.

#### Request Body
- **customer_id** (string) - Required - The ID of the customer to attach the plan to.
- **entity_id** (string) - Required - The ID of the entity to attach the plan to.
- **plan_id** (string) - Optional - If specified, the plan will be attached to the customer after setup.
- **feature_quantities** (array) - Optional - Quantity configuration for prepaid features.
  - **feature_id** (string) - Required - The ID of the feature to set quantity for.
  - **quantity** (number) - Required - The quantity of the feature. Minimum 0.
  - **adjustable** (boolean) - Optional - Whether the customer can adjust the quantity.
- **version** (number) - Optional - The version of the plan to attach.
- **customize** (object) - Optional - Override the base price of the plan.
  - **price** (object) - Optional - Base price configuration for a plan.
    - **amount** (number) - Required - Base price amount for the plan.
    - **interval** (enum) - Required - Billing interval (e.g. 'one_off', 'week', 'month', 'quarter', 'semi_annual', 'year').
    - **interval_count** (number) - Optional - Number of intervals per billing cycle. Defaults to 1.
  - **items** (array) - Optional - Configuration for prepaid features.
    - **feature_id** (string) - Required - The ID of the feature to configure.
    - **included** (number) - Optional - Number of free units included.
    - **unlimited** (boolean) - Optional - If true, customer has unlimited access to this feature.
    - **reset** (object) - Optional - Reset configuration for the feature.
      - **interval** (enum) - Required - The interval at which the feature resets (e.g., 'week', 'month').

### Request Example
```json
{
  "customer_id": "cus_12345",
  "entity_id": "ent_abcde",
  "plan_id": "plan_xyz",
  "feature_quantities": [
    {
      "feature_id": "feat_1",
      "quantity": 10,
      "adjustable": true
    }
  ],
  "version": 1,
  "customize": {
    "price": {
      "amount": 1000,
      "interval": "month"
    },
    "items": [
      {
        "feature_id": "feat_2",
        "included": 5,
        "unlimited": false,
        "reset": {
          "interval": "month"
        }
      }
    ]
  }
}
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the payment setup session.
- **url** (string) - The URL to redirect the customer to complete the payment setup.

#### Response Example
```json
{
  "id": "set_session_123",
  "url": "https://checkout.useautumn.com/setup/set_session_123"
}
```
```

--------------------------------

### Response Example (JSON)

Source: https://docs.useautumn.com/api-reference/customers/updateCustomer

A sample JSON response illustrating user data, including personal information, billing controls, subscriptions, and feature balances. This example shows a user with an active subscription and message balance.

```json
{
  "id": "2ee25a41-0d81-4ad2-8451-ec1aadaefe58",
  "name": "Patrick",
  "email": "patrick@useautumn.com",
  "createdAt": 1771409161016,
  "fingerprint": null,
  "stripeId": "cus_U0BKxpq1mFhuJO",
  "env": "sandbox",
  "metadata": {},
  "sendEmailReceipts": false,
  "billingControls": {
    "autoTopups": []
  },
  "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
    }
  }
}
```

--------------------------------

### Define Pricing Plans in TypeScript

Source: https://docs.useautumn.com/documentation/getting-started/setup

Configuration for defining features and pricing tiers using the Autumn SDK. This example sets up a metered 'messages' feature with a Free plan (5 messages/month) and a Pro plan ($20/month, 100 messages/month).

```typescript
import { feature, item, plan } from "atmn";

// Features
export const messages = feature({
  id: "messages",
  name: "Messages",
  type: "metered",
  consumable: true,
});

// Plans
export const free = plan({
  id: "free",
  name: "Free",
  autoEnable: true,
  items: [
    // 5 messages per month
    item({
      featureId: messages.id,
      included: 5,
      reset: { interval: "month" },
    }),
  ],
});

export const pro = plan({
  id: "pro",
  name: "Pro",
  price: {
    amount: 20,
    interval: "month",
  },
  items: [
    // 100 messages per month
    item({
      featureId: messages.id,
      included: 100,
      reset: { interval: "month" },
    }),
  ],
});
```

--------------------------------

### Prepaid Pricing Example (TypeScript)

Source: https://docs.useautumn.com/cli/config

Sets up a plan item using prepaid pricing. This example charges a fixed amount of 5 for 100 units of 'credits.id', purchased upfront.

```typescript
item({
  featureId: credits.id,
  price: {
    amount: 5,
    billingUnits: 100,
    billingMethod: 'prepaid',
  },
})
```

--------------------------------

### Setup Payment Session with Autumn SDK

Source: https://docs.useautumn.com/api-reference/billing/setupPayment

Initializes a payment setup session for a specific customer. This function requires a customer ID and a success URL to redirect the user after the payment process is completed.

```typescript
import { Autumn } from 'autumn-js'

const autumn = new Autumn()

const result = await autumn.billing.setupPayment({
  customerId: "cus_123",
  successUrl: "https://example.com/account/billing",
});
```

```python
from autumn_sdk import Autumn

autumn = Autumn(secret_key="am_sk_test...")

res = autumn.billing.setup_payment(
    customer_id="cus_123",
    success_url="https://example.com/account/billing",
)
```

--------------------------------

### Open Customer Portal Response Example

Source: https://docs.useautumn.com/api-reference/billing/openCustomerPortal

This JSON example shows a successful response from the open_customer_portal endpoint. It contains the customer ID for the billing session and the URL to access the billing portal.

```json
{
  "customer_id": "cus_123",
  "url": "https://billing.stripe.com/session/..."
}
```

--------------------------------

### Open Customer Portal Request Body Example

Source: https://docs.useautumn.com/api-reference/billing/openCustomerPortal

This JSON example illustrates the structure of the request body required to open a customer portal session. It includes the customer's ID and an optional configuration ID and return URL.

```json
{
  "customer_id": "cus_123",
  "return_url": "https://useautumn.com"
}
```

--------------------------------

### Dynamic JSON Response Example

Source: https://docs.useautumn.com/api-reference/billing/billingUpdate

Renders a JSON response example, dynamically converting keys to camelCase if the user prefers TypeScript output. It listens for 'mintlify-localstorage' events and polls localStorage to detect language preference changes.

```javascript
export const DynamicResponseExample = ({json, statusCode = "200"}) => {
  const toCamelCase = str => {
    return str.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
  };
  const convertKeysToCamelCase = obj => {
    if (Array.isArray(obj)) {
      return obj.map(item => convertKeysToCamelCase(item));
    }
    if (obj !== null && typeof obj === "object") {
      return Object.keys(obj).reduce((acc, key) => {
        const camelKey = toCamelCase(key);
        acc[camelKey] = convertKeysToCamelCase(obj[key]);
        return acc;
      }, {});
    }
    return obj;
  };
  const [isTypeScript, setIsTypeScript] = useState(() => {
    if (typeof window !== "undefined") {
      try {
        const lang = localStorage.getItem("code");
        return JSON.parse(lang) === "typescript";
      } catch {
        return true;
      }
    }
    return true;
  });
  useEffect(() => {
    const onMintlifyStorage = event => {
      if (event.detail?.key === "code") {
        try {
          const value = JSON.parse(event.detail.value);
          setIsTypeScript(value === "typescript");
        } catch {}
      }
    };
    const pollInterval = setInterval(() => {
      try {
        const lang = localStorage.getItem("code");
        const value = JSON.parse(lang);
        setIsTypeScript(value === "typescript");
      } catch {}
    }, 300);
    document.addEventListener("mintlify-localstorage", onMintlifyStorage);
    return () => {
      document.removeEventListener("mintlify-localstorage", onMintlifyStorage);
      clearInterval(pollInterval);
    };
  }, []);
  const camelCaseJson = useMemo(() => convertKeysToCamelCase(json), [json]);
  const snakeCaseString = JSON.stringify(json, null, 2);
  const camelCaseString = JSON.stringify(camelCaseJson, null, 2);
  return <ResponseExample>
			{isTypeScript ? <CodeBlock language="json" filename={statusCode}>
					{camelCaseString}
				</CodeBlock> : <CodeBlock language="json" filename={statusCode}>
					{snakeCaseString}
				</CodeBlock>}
		</ResponseExample>;
};
```

--------------------------------

### List Platform Users Example (curl)

Source: https://docs.useautumn.com/api-reference/platform/list-users

Example command using curl to list platform users. It demonstrates how to set query parameters for limit, offset, and expansion, and includes the necessary Authorization header.

```curl
curl -X GET \
  'https://api.useautumn.com/v1/platform/users?limit=20&offset=0&expand=organizations' \
  -H 'Authorization: Bearer am_sk_test_...'
```

--------------------------------

### Response Example: Customer Line Items

Source: https://docs.useautumn.com/api-reference/billing/previewUpdate

Provides a JSON example of a successful API response for a customer's line items. It includes details like customer ID, line item descriptions, subtotals, totals, and currency.

```json
{
  "customerId": "charles",
  "lineItems": [
    {
      "display_name": "Pro seed",
      "description": "Pro seed - Base Price (from 18 Feb 2026 to 18 Mar 2026)",
      "subtotal": 20,
      "total": 20,
      "discounts": []
    }
  ],
  "subtotal": 20,
  "total": 20,
  "currency": "usd"
}
```

--------------------------------

### POST /subscriptions

Source: https://docs.useautumn.com/api-reference/billing/setupPayment

Create or update a subscription configuration with specific billing, trial, and discount parameters.

```APIDOC
## POST /subscriptions

### Description
Configures a new subscription or updates an existing one, including billing methods, proration settings, and trial periods.

### Method
POST

### Endpoint
/subscriptions

### Parameters
#### Request Body
- **billing_method** (string) - Required - 'prepaid' or 'usage_based'.
- **max_purchase** (number) - Optional - Max units purchasable beyond included.
- **proration** (object) - Optional - Settings for mid-cycle quantity changes.
- **rollover** (object) - Optional - Config for unused units.
- **free_trial** (object) - Optional - Trial configuration.
- **proration_behavior** (string) - Optional - 'prorate_immediately' or 'none'.
- **subscription_id** (string) - Optional - Unique identifier for the subscription.
- **discounts** (array) - Optional - List of reward IDs or promotion codes.
- **success_url** (string) - Optional - Redirect URL after checkout.
- **custom_line_items** (array) - Optional - Custom line items for immediate plan changes.

### Request Example
{
  "billing_method": "prepaid",
  "proration": {
    "on_increase": "bill_immediately",
    "on_decrease": "prorate"
  },
  "free_trial": {
    "duration_length": 14,
    "duration_type": "day",
    "card_required": true
  }
}

### Response
#### Success Response (200)
- **status** (string) - Operation status.

#### Response Example
{
  "status": "success"
}
```

--------------------------------

### Enable Pay-as-you-go Plan

Source: https://docs.useautumn.com/examples/pay-as-you-go-overages

This snippet demonstrates how to prompt users to switch to a Pay-as-you-go plan when they approach or exceed their limits. It uses the `attach` method with `setup_payment: true` to collect payment information without immediate charging. The user's notification balance can be retrieved using `check` or `customer` methods to conditionally trigger this prompt.

```jsx
import { useCustomer } from "autumn-js/react";

export default function EnableOveragesButton() {
  const { attach } = useCustomer();

  return (
    <button
      onClick={async () => {
        const { data } = await attach({
          productId: "pay_as_you_go",
          setupPayment: true,
        });

        if (data?.url) {
          window.location.href = data.url;
        }
      }}>
      Enable Pay-as-you-go
    </button>
  );
}
```

```typescript
import { Autumn } from "autumn-js";

const autumn = new Autumn({
  secretKey: 'am_sk_42424242',
});

const { data } = await autumn.attach({
  customer_id: "user_123",
  product_id: "pay_as_you_go",
  setup_payment: true,
  success_url: "https://your-app.com/settings",
});

if (data.url) {
  // Redirect user to Stripe setup page
}
```

```python
import asyncio
from autumn import Autumn

autumn = Autumn("am_sk_42424242")

async def main():
    response = await autumn.attach(
        customer_id="user_123",
        product_id="pay_as_you_go",
        setup_payment=True,
        success_url="https://your-app.com/settings",
    )
    
    if response.url:
        # Redirect user to Stripe setup page
        pass

asyncio.run(main())
```

```bash
curl -X POST "https://api.useautumn.com/v1/attach" \
  -H "Authorization: Bearer am_sk_42424242" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "user_123",
    "product_id": "pay_as_you_go",
    "setup_payment": true,
    "success_url": "https://your-app.com/settings"
  }'
```

--------------------------------

### Retrieve Entity Response JSON Example

Source: https://docs.useautumn.com/api-reference/customers/getOrCreateCustomer

A representative JSON response object returned by the Autumn API, demonstrating the structure of customer entities, including metadata, billing controls, and active subscription details.

```json
{
  "id": "2ee25a41-0d81-4ad2-8451-ec1aadaefe58",
  "name": "Patrick",
  "email": "patrick@useautumn.com",
  "createdAt": 1771409161016,
  "fingerprint": null,
  "stripeId": "cus_U0BKxpq1mFhuJO",
  "env": "sandbox",
  "metadata": {},
  "sendEmailReceipts": false,
  "billingControls": {
    "autoTopups": []
  },
  "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
    }
  }
}
```

--------------------------------

### Pricing Configuration Example (YAML)

Source: https://docs.useautumn.com/api-reference/customers/listCustomers

This YAML snippet illustrates the configuration for pricing, including billing units, billing method (prepaid or usage-based), and maximum purchase quantity. It's part of a larger structure detailing balance sources.

```yaml
price:
  billing_units: 250
  billing_method: usage_based
  max_purchase: null
```

--------------------------------

### Use PricingTable Component

Source: https://docs.useautumn.com/documentation/external-providers/convex

Integrate the `PricingTable` component from `autumn-js/react` into your React application to display pricing information. This component provides a quick way to get started with Autumn's UI elements. It can be downloaded as a shadcn component for customization.

```typescript
import { PricingTable } from "autumn-js/react";

export default function Home() {
  return (
    <PricingTable/>
  );
}

```

--------------------------------

### Push Configuration to Autumn Sandbox

Source: https://docs.useautumn.com/documentation/getting-started/setup

Commands to deploy local pricing configurations to the Autumn sandbox environment using the CLI.

```bash
bunx atmn push
```

```bash
npx atmn push
```

```bash
pnpm dlx atmn push
```

--------------------------------

### GET /features/{feature_id}

Source: https://docs.useautumn.com/api-reference/features/getFeature

Retrieves the detailed configuration for a specific feature by its ID.

```APIDOC
## GET /features/{feature_id}

### Description
Retrieves the full configuration object for a specific feature, including its type, display settings, and credit schemas.

### Method
GET

### Endpoint
/features/{feature_id}

### Parameters
#### Path Parameters
- **feature_id** (string) - Required - The unique identifier of the feature.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for this feature.
- **name** (string) - Human-readable name displayed in the dashboard.
- **type** ('boolean' | 'metered' | 'credit_system') - The classification of the feature.
- **consumable** (boolean) - Whether usage resets periodically.
- **event_names** (string[]) - Events that trigger this feature's balance.
- **credit_schema** (object[]) - Mapping of metered features to credit costs.
- **display** (object) - UI display labels.
- **archived** (boolean) - Whether the feature is hidden from the dashboard.

#### Response Example
{
  "id": "api-calls",
  "name": "API Calls",
  "type": "metered",
  "consumable": true,
  "archived": false,
  "display": {
    "singular": "API call",
    "plural": "API calls"
  }
}
```

--------------------------------

### Get Customer

Source: https://docs.useautumn.com/api-reference/customers/getOrCreateCustomer

Retrieves details for a specific customer using their unique ID.

```APIDOC
## GET /customers/{customer_id}

### Description
Retrieves details for a specific customer using their unique ID.

### Method
GET

### Endpoint
/customers/{customer_id}

### Parameters
#### Path Parameters
- **customer_id** (string) - Required - Your unique identifier for the customer

### Response
#### Success Response (200)
- **id** (string) - Your unique identifier for the customer.
- **name** (string) - The name of the customer.
- **email** (string) - The email address of the customer.
- **created_at** (number) - Timestamp of customer creation in milliseconds since epoch.
- **fingerprint** (string) - A unique identifier (eg. serial number) to de-duplicate customers across devices or browsers. For example: apple device ID.
- **stripe_id** (string) - Stripe customer ID.
- **env** (string) - The environment this customer was created in. Enum: ["sandbox", "live"]
- **metadata** (object) - The metadata for the customer.
- **send_email_receipts** (boolean) - Whether to send email receipts to the customer.
- **billing_controls** (object) - Billing controls for the customer (auto top-ups, etc.).
  - **auto_topups** (array) - List of auto top-up configurations per feature.
    - **feature_id** (string) - The ID of the feature (credit balance) to auto top-up.
    - **enabled** (boolean) - Whether auto top-up is enabled.
    - **threshold** (number) - When the balance drops below this threshold, an auto top-up will be purchased.
    - **quantity** (number) - Amount of credits to add per auto top-up.
    - **purchase_limit** (object) - Optional rate limit to cap how often auto top-ups occur.
      - **interval** (string) - The time interval for the purchase limit window. Enum: ["hour", "day", "week", "month"]
      - **interval_count** (number) - Number of intervals in the purchase limit window.
      - **limit** (number) - Maximum number of auto top-ups allowed within the interval.
  - **spend_limits** (array) - List of overage spend limits per feature.
    - **feature_id** (string) - Optional feature ID this spend limit applies to.
    - **enabled** (boolean) - Whether this spend limit is enabled.
    - **overage_limit** (number) - Maximum allowed overage spend for the target feature.
- **subscriptions** (array) - List of subscriptions associated with the customer.
  - **id** (string) - The unique identifier of this subscription.

#### Response Example
{
  "id": "cus_123",
  "name": "John Doe",
  "email": "john@example.com",
  "created_at": 1678886400000,
  "fingerprint": "abc123xyz",
  "stripe_id": "stripe_cus_abc",
  "env": "sandbox",
  "metadata": {
    "key": "value"
  },
  "send_email_receipts": true,
  "billing_controls": {
    "auto_topups": [
      {
        "feature_id": "credits",
        "enabled": true,
        "threshold": 100,
        "quantity": 1000,
        "purchase_limit": {
          "interval": "day",
          "interval_count": 1,
          "limit": 5
        }
      }
    ],
    "spend_limits": [
      {
        "feature_id": "credits",
        "enabled": true,
        "overage_limit": 5000
      }
    ]
  },
  "subscriptions": [
    {
      "id": "sub_abc"
    }
  ]
}
```

--------------------------------

### Plan Response Example

Source: https://docs.useautumn.com/api-reference/plans/listPlans

A sample JSON response illustrating a 'Pro Plan' object. It includes pricing details, feature breakdowns with included amounts and usage-based pricing, creation timestamp, environment, and archiving status.

```json
{
  "list": [
    {
      "id": "pro",
      "name": "Pro Plan",
      "description": null,
      "group": null,
      "version": 1,
      "addOn": false,
      "autoEnable": false,
      "price": {
        "amount": 10,
        "interval": "month",
        "display": {
          "primaryText": "$10",
          "secondaryText": "per month"
        }
      },
      "items": [
        {
          "featureId": "messages",
          "included": 100,
          "unlimited": false,
          "reset": {
            "interval": "month"
          },
          "price": {
            "amount": 0.5,
            "interval": "month",
            "billingUnits": 100,
            "billingMethod": "usage_based",
            "maxPurchase": null
          },
          "display": {
            "primaryText": "100 messages",
            "secondaryText": "then $0.5 per 100 messages"
          }
        },
        {
          "featureId": "users",
          "included": 0,
          "unlimited": false,
          "reset": null,
          "price": {
            "amount": 10,
            "interval": "month",
            "billingUnits": 1,
            "billingMethod": "prepaid",
            "maxPurchase": null
          },
          "display": {
            "primaryText": "$10 per Users"
          }
        }
      ],
      "createdAt": 1771513979217,
      "env": "sandbox",
      "archived": false,
      "baseVariantId": null
    }
  ]
}
```

--------------------------------

### Upgrade to Pro Tier with cURL

Source: https://docs.useautumn.com/examples/per-seat

Shows how to initiate a customer upgrade to the 'Pro' product using a cURL request. The example demonstrates how to specify the quantity of additional paid seats required.

```bash
curl -X POST "https://api.useautumn.com/v1/checkout" \
  -H "Authorization: Bearer am_sk_42424242" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "org_123",
    "product_id": "pro",
    "options": [{
      "feature_id": "seats",
      "quantity": 3
    }]
  }'
```

--------------------------------

### GET /subscriptions

Source: https://docs.useautumn.com/api-reference/customers/getOrCreateCustomer

Retrieves the subscription details and associated plan information for a customer.

```APIDOC
## GET /subscriptions

### Description
Retrieves detailed information about a customer's subscription, including trial status, billing periods, and plan metadata.

### Method
GET

### Endpoint
/subscriptions

### Response
#### Success Response (200)
- **plan_id** (string) - The unique identifier of the subscribed plan.
- **status** (string) - Current status of the subscription ('active' | 'scheduled').
- **trial_ends_at** (number | null) - Timestamp when the trial period ends.
- **current_period_start** (number | null) - Start timestamp of the current billing period.
- **current_period_end** (number | null) - End timestamp of the current billing period.
- **quantity** (number) - Number of units of this subscription.

#### Response Example
{
  "plan_id": "plan_123",
  "status": "active",
  "trial_ends_at": 1735689600000,
  "quantity": 1
}
```

--------------------------------

### Upgrade to Pro Tier with Node.js

Source: https://docs.useautumn.com/examples/per-seat

Provides a Node.js example for initiating a checkout process to upgrade a customer to the 'Pro' product. It shows how to include options for additional paid seats.

```typescript
import { Autumn } from "autumn-js";

const autumn = new Autumn({
  secretKey: 'am_sk_42424242',
});

// Customer wants 8 total seats (5 included + 3 paid)
const { data } = await autumn.checkout({
  customer_id: "org_123",
  product_id: "pro",
  options: [{
    feature_id: "seats",
    quantity: 3, // 3 paid seats beyond the 5 included
  }],
});

if (data.url) {
  // Redirect to Stripe checkout
}
```

--------------------------------

### GET /features

Source: https://docs.useautumn.com/api-reference/customers/getOrCreateCustomer

Retrieve the configuration details for features, including their type, credit schemas, and reset intervals.

```APIDOC
## GET /features

### Description
Retrieves a list of feature configurations, including their type (static, boolean, credit_system, etc.) and reset logic for consumable features.

### Method
GET

### Endpoint
/features

### Parameters
#### Query Parameters
- **expand** (string) - Optional - Expand the feature object to include full details.

### Response
#### Success Response (200)
- **feature_id** (string) - The unique identifier for the feature.
- **feature** (object) - The full feature definition object.
- **included** (number) - Number of free units included.
- **unlimited** (boolean) - Whether the customer has unlimited access.
- **reset** (object) - Configuration for usage reset intervals.

#### Response Example
{
  "feature_id": "feat_123",
  "included": 100,
  "unlimited": false,
  "reset": {
    "interval": "month",
    "interval_count": 1
  }
}
```

--------------------------------

### Create Plan with Free Trial (TypeScript)

Source: https://docs.useautumn.com/api-reference/plans/createPlan

Creates a premium plan with a monthly price and a 14-day free trial. A credit card is required to start the trial.

```typescript
await autumn.plans.create({
    planId: "premium_plan",
    name: "Premium",
    price: { amount: 99, interval: "month" },
    freeTrial: {
      durationLength: 14,
      durationType: "day",
      cardRequired: true
    }
  });
```

--------------------------------

### GET /api/usage

Source: https://docs.useautumn.com/api-reference/customers/getOrCreateCustomer

Retrieves the current usage statistics, balance breakdown, and billing configurations for the authenticated account.

```APIDOC
## GET /api/usage

### Description
Returns the current usage metrics, including granted balance, remaining balance, and detailed breakdowns of usage sources.

### Method
GET

### Endpoint
/api/usage

### Parameters
#### Query Parameters
- **None**

### Response
#### Success Response (200)
- **granted** (number) - Total balance granted (included + prepaid).
- **remaining** (number) - Remaining balance available for use.
- **usage** (number) - Total usage consumed in the current period.
- **unlimited** (boolean) - Whether this feature has unlimited usage.
- **overage_allowed** (boolean) - Whether usage beyond the granted balance is allowed.
- **breakdown** (object[]) - Detailed list of balance sources.

#### Response Example
{
  "granted": 1000,
  "remaining": 450,
  "usage": 550,
  "unlimited": false,
  "overage_allowed": true,
  "breakdown": [
    {
      "id": "bal_123",
      "included_grant": 500,
      "prepaid_grant": 500,
      "remaining": 450,
      "usage": 550
    }
  ]
}
```

--------------------------------

### GET /plans

Source: https://docs.useautumn.com/api-reference/customers/getOrCreateCustomer

Retrieves details about available plans, including versioning, trial configurations, and eligibility rules.

```APIDOC
## GET /plans

### Description
Retrieves configuration details for plans, including trial settings, environment scope, and customer eligibility criteria.

### Method
GET

### Endpoint
/plans

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the plan.
- **name** (string) - Display name of the plan.
- **version** (number) - Version number of the plan.
- **env** (string) - Environment ('sandbox' | 'live').
- **archived** (boolean) - Whether the plan is archived.
- **customer_eligibility** (object) - Rules for customer access to trials and scenarios.

#### Response Example
{
  "id": "plan_abc",
  "name": "Pro Plan",
  "version": 1,
  "env": "live",
  "archived": false
}
```

--------------------------------

### Implement Purchase Flow and Paywalls

Source: https://docs.useautumn.com/documentation/external-providers/revenuecat

Demonstrates how to trigger a specific product purchase using the RevenueCat SDK or display a pre-built paywall component.

```typescript
<Button
    variant="default"
    size="lg"
    onPress={async () => {
        try {
            const offerings = await Purchases.getOfferings();
            const pkg = offerings.all.default.availablePackages.find(
                (x) => x.identifier === "$rc_monthly",
            );
            if (!pkg) {
                throw new Error("Package not found");
            }
            const { customerInfo } = await Purchases.purchasePackage(pkg);
            if (
                typeof customerInfo.entitlements.active["monthly"] !==
                "undefined"
            ) {
                alert("Successfully purchased product PRO");
            }
        } catch (e: unknown) {
            if (JSON.stringify(e).includes("Purchase was cancelled")) return;
            alert("Error purchasing product PRO");
        }
    }}
    className="w-full mt-6"
>
    <Text>Upgrade to PRO</Text>
</Button>
```

```typescript
import { useRouter } from "expo-router";
import { View } from "react-native";
import RevenueCatUI from "react-native-purchases-ui";

export default function RCPaywall() {
    const router = useRouter();

    return (
        <View className="flex-1">
            <RevenueCatUI.Paywall
                onDismiss={() => {
                    router.back();
                }}
            />
        </View>
    );
}
```

--------------------------------

### Upgrade to Pro Tier with Python

Source: https://docs.useautumn.com/examples/per-seat

Demonstrates how to upgrade a customer to the 'Pro' product using the Autumn Python SDK. The example includes specifying the desired quantity of additional paid seats.

```python
import asyncio
from autumn import Autumn

autumn = Autumn("am_sk_42424242")

async def main():
    # Customer wants 8 total seats (5 included + 3 paid)
    response = await autumn.checkout(
        customer_id="org_123",
        product_id="pro",
        options=[{
            "feature_id": "seats",
            "quantity": 3,  # 3 paid seats beyond the 5 included
        }],
    )
    
    if response.url:
        # Redirect to Stripe checkout
        pass

asyncio.run(main())
```

--------------------------------

### GET /plans

Source: https://docs.useautumn.com/api-reference/customers/getOrCreateCustomer

Retrieve pricing plan details including base recurring costs and associated feature configurations.

```APIDOC
## GET /plans

### Description
Retrieves pricing plan information, including the base recurring price and the display text for pricing pages.

### Method
GET

### Endpoint
/plans

### Response
#### Success Response (200)
- **amount** (number) - Base recurring price for the plan.
- **interval** (string) - Billing interval (e.g., month, year).
- **display_text** (object) - Pricing page display configuration.

#### Response Example
{
  "amount": 29.99,
  "interval": "month",
  "display_text": {
    "primary_text": "$29.99",
    "secondary_text": "per month"
  }
}
```

--------------------------------

### Free Trial Configuration Schema

Source: https://docs.useautumn.com/api-reference/plans/createPlan

Defines the schema for free trial settings. It specifies the duration, unit of time, and whether a payment method is required to start the trial.

```yaml
free_trial:
  type: object
  properties:
    duration_length:
      type: number
      description: Number of duration_type periods the trial lasts.
    duration_type:
      enum:
        - day
        - month
        - year
      default: month
      description: Unit of time for the trial ('day', 'month', 'year').
    card_required:
      type: boolean
      default: true
      description: >-
        If true, payment method required to start trial.
        Customer is charged after trial ends.
  required:
    - duration_length
  description: >-
    Free trial configuration. Customers can try this plan before
    being charged.
```

--------------------------------

### GET /plans/configuration

Source: https://docs.useautumn.com/api-reference/customers/getOrCreateCustomer

Retrieves the configuration schema for plan features, including pricing models, rollover rules, and trial settings.

```APIDOC
## GET /plans/configuration

### Description
Returns the detailed configuration schema for features, pricing, and trial settings used in plan management.

### Method
GET

### Endpoint
/plans/configuration

### Response
#### Success Response (200)
- **price** (object) - Pricing configuration for usage beyond included units.
- **display** (object) - Display text for pricing pages.
- **rollover** (object) - Configuration for unused unit rollover.
- **free_trial** (object) - Free trial duration and requirement settings.

#### Response Example
{
  "price": {
    "amount": 10,
    "billing_method": "usage_based",
    "interval": "month"
  },
  "display": {
    "primary_text": "$10",
    "secondary_text": "per month"
  },
  "rollover": {
    "max": 100,
    "expiry_duration_type": "month"
  },
  "free_trial": {
    "duration_length": 14,
    "duration_type": "day",
    "card_required": false
  }
}
```