Autumn

https://docs.useautumn.com
Admin
Autumn is an open-source platform that manages your application's pricing plans and billing. It...
Tokens:272,791
Snippets:1,761
Trust Score:7.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Setup Payment Response Example

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

Example of a successful 200 OK response containing the customer ID and redirect URL.

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

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

### Attach Customer to Pay-as-you-go Product

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

Use these examples to initiate the payment setup process for a customer.

```javascript
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"
  }'
```

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

### Setup Payment via SDK

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

Use these examples to generate a payment setup URL for a specific customer using the Autumn SDK.

```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",
)
```

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

### Get or Create Customer SDK Examples

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

Use the TypeScript or Python SDK to interact with the customer creation endpoint. Ensure your client is initialized with the appropriate credentials.

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

const autumn = new Autumn()

const result = await autumn.customers.getOrCreate({
  customerId: "cus_123",
  name: "John Doe",
  email: "john@example.com",
});
```

```python
from autumn_sdk import Autumn

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

res = autumn.customers.get_or_create(
    customer_id="cus_123",
    name="John Doe",
    email="john@example.com",
)
```

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

### Create Plan Default Example

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

A basic example payload for creating a free plan.

```json
plan_id: free_plan
name: Free
auto_enable: true
items:
  - feature_id: messages
    included: 100
    reset:
      interval: month
```

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

### Retrieve a plan

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

Use these examples to fetch plan details. Specify a version to retrieve a historical configuration, or omit it to get the latest version.

```typescript
const plan = await autumn.plans.get({
  planId: "pro_plan"
});
```

```typescript
const plan = await autumn.plans.get({
  planId: "pro_plan",
  version: 2
});
```

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

### Get Plan Response Example

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

A successful 200 OK response containing the full plan object, including pricing, feature items, and metadata.

```json
{
    "id": "pro",
    "name": "Pro Plan",
    "description": null,
    "group": null,
    "version": 1,
    "version_slug": "v1",
    "active": true,
    "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,
    "config": {
      "ignore_past_due": false
    },
    "billing_controls": {},
    "metadata": {}
  }
```

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

### Get Referral Program Response Example

Source: https://docs.useautumn.com/api-reference/referrals/getReferralProgram

A successful 200 OK response containing the referral program configuration details.

```json
{
  "id": "refer_a_friend",
  "reward_id": "beta_credits_grant",
  "redeem_on": "customer_creation",
  "received_by": "referrer",
  "max_redemptions": 10,
  "plan_ids": null,
  "exclude_trial": false,
  "created_at": 1718000000000
}
```

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

### Create Billing Schedule SDK Examples

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

Examples for initializing the Autumn SDK and creating a billing schedule with multiple phases.

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

const autumn = new Autumn()

const result = await autumn.billing.createSchedule({
  customerId: "cus_123",
  phases: [
    {
      startsAt: 1735689600000,
      plans: [
        {
          planId: "trial_plan",
        },
      ],
    },
    {
      startsAt: 1736899200000,
      plans: [
        {
          planId: "pro_plan",
        },
      ],
    },
  ],
});
```

```python
from autumn_sdk import Autumn

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

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

### MultiUpdatePreviewResponse Example

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

Example JSON response for a multi-update preview, showing subscription line items and plan IDs.

```json
{
  "customer_id": "cus_123",
  "currency": "usd",
  "total": -40,
  "subscriptions": [
    {
      "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",
      "plan_ids": [
        "pro_plan"
      ]
    },
    {
      "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",
      "plan_ids": [
        "addon_seats"
      ]
    }
  ]
}
```

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

### Install Autumn SDK

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

Install the Autumn SDK using your preferred package manager.

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

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

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

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

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

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

### AttachParams Example

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

Minimal example of the parameters required to attach a plan to a customer.

```json
customer_id: cus_123
plan_id: pro_plan
```

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

### Get Referral Program SDK Examples

Source: https://docs.useautumn.com/api-reference/referrals/getReferralProgram

Retrieve a referral program using the Autumn SDK in TypeScript or Python.

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

const autumn = new Autumn()

const result = await autumn.referrals.getProgram({
  referralProgramId: "<id>",
});
```

```python
from autumn_sdk import Autumn

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

res = autumn.referrals.get_program(
    referral_program_id="<id>",
)
```

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

### Create Reward Request Example

Source: https://docs.useautumn.com/api-reference/rewards/createReward

Example payload for creating a reward with a percentage discount coupon.

```json
coupon:
  id: summer_sale
  name: Summer Sale
  type: percentage_discount
  value: 20
  duration:
    type: months
    length: 3
  plan_ids: null
  promo_codes:
    - code: SUMMER20
```

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

### Create Plan Request Examples

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

Example JSON payloads for creating different types of plans, including free, usage-based, and prepaid configurations.

```json
plan_id: free_plan
name: Free
auto_enable: true
items:
  - feature_id: messages
    included: 100
    reset:
      interval: month
```

```json
plan_id: pro_plan
name: Pro Plan
price:
  amount: 10
  interval: month
items:
  - feature_id: messages
    included: 1000
    reset:
      interval: month
    price:
      amount: 0.01
      interval: month
      billing_units: 1
      billing_method: usage_based
```

```json
plan_id: team_plan
name: Team Plan
price:
  amount: 49
  interval: month
items:
  - feature_id: seats
    included: 5
    price:
      amount: 10
      interval: month
      billing_units: 1
      billing_method: prepaid
```

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

### List Plans API Examples

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

Examples for retrieving plans, including filtering by customer eligibility or including archived plans.

```typescript
const plans = await autumn.plans.list();
```

```typescript
const plans = await autumn.plans.list({
  customerId: "cus_123"
});

// Each plan will include customerEligibility:
// - trialAvailable: whether customer can use the trial
// - scenario: 'new', 'upgrade', 'downgrade', etc.
```

```typescript
const plans = await autumn.plans.list({
  includeArchived: true
});
```

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

### Setup Payment

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

Configures payment settings and generates a URL for the customer to complete the setup process.

```APIDOC
## Setup Payment

### Description
Initiates the payment setup flow, allowing for plan attachment, metadata configuration, and immediate plan activation.

### Parameters
#### Request Body
- **quantity** (integer) - Required - Total seats for the license.
- **metadata.{key}** (string) - Optional - Key-value metadata to attach to Stripe objects.
- **no_billing_changes** (boolean) - Optional - If true, skips billing changes.
- **enable_plan_immediately** (boolean) - Optional - If true, activates the plan immediately.
- **tax_rate_id** (string) - Optional - Stripe tax rate ID.
- **currency** (string) - Optional - Currency for the billing.
- **remove_plan_ids** (string[]) - Optional - Plan IDs to expire on the customer.

### 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/..."
}
```

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

### Install OpenRouter Gateway

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

Install the gateway package using your preferred package manager.

```bash
npm install @useautumn/gateway
```

```bash
pnpm add @useautumn/gateway
```

```bash
yarn add @useautumn/gateway
```

```bash
bun add @useautumn/gateway
```

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

### Check Response Example

Source: https://docs.useautumn.com/examples/entity-balances

Example JSON response returned when checking customer-level balances.

```json
{
  "allowed": true,
  "customer_id": "org_123",
  "feature_id": "meeting_summaries",
  "balance": 141,
  "usage": 9,
  "included_usage": 150,
  "unlimited": false
}
```

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

### PreviewUpdateParams Example

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

Example payload for previewing a subscription update for a specific customer and plan.

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

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

### List License Assignments Response Example

Source: https://docs.useautumn.com/api-reference/licenses/listLicenseAssignments

Example of a successful 200 OK response containing a list of license assignment objects.

```json
{
    "list": [
      {
        "id": "lic_asn_123",
        "entity_id": "user_123",
        "license_plan_id": "seat_plan",
        "started_at": 1759247877000,
        "ended_at": null
      }
    ]
  }
```

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

### Preview Attach SDK Examples

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

Use these examples to preview billing attachments for a customer using the TypeScript or Python SDKs.

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

const autumn = new Autumn()

const result = await autumn.billing.previewAttach({
  customerId: "cus_123",
  planId: "pro_plan",
});
```

```python
from autumn_sdk import Autumn

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

res = autumn.billing.preview_attach(
    customer_id="cus_123",
    plan_id="pro_plan",
    redirect_mode="if_required",
)
```

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

### CreateScheduleParams Example

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

Example payload for defining customer billing phases and associated plans.

```yaml
customer_id: cus_123
phases:
  - starts_at: 1735689600000
    plans:
      - plan_id: trial_plan
  - starts_at: 1736899200000
    plans:
      - plan_id: pro_plan
```

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

### Multi-Update Billing SDK Examples

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

Examples for updating multiple billing plans simultaneously using the Autumn SDK.

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

const autumn = new Autumn()

const result = await autumn.billing.multiUpdate({
  customerId: "cus_123",
  updates: [
    {
      planId: "pro_plan",
      cancelAction: "cancel_end_of_cycle",
    },
    {
      planId: "addon_seats",
      cancelAction: "cancel_end_of_cycle",
    },
  ],
});
```

```python
from autumn_sdk import Autumn
```

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

### Refresh Key SDK Examples

Source: https://docs.useautumn.com/api-reference/keys/refreshKey

Examples for refreshing keys using the Autumn SDK in TypeScript and Python.

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

const autumn = new Autumn()

const result = await autumn.keys.refresh({});
```

```python
from autumn_sdk import Autumn

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

res = autumn.keys.refresh(
    request={},
)
```

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

### Customer Data Example

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

Example JSON structure representing a customer record with associated subscriptions, balances, and processor configurations.

```json
id: 2ee25a41-0d81-4ad2-8451-ec1aadaefe58
name: Patrick
email: patrick@useautumn.com
createdAt: 1771409161016
fingerprint: null
stripeId: cus_U0BKxpq1mFhuJO
processors:
  stripe:
    id: 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: []
licenses: []
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
flags:
  advanced_workflows:
    id: cus_ent_abc123
    plan_id: pro_plan
    expires_at: null
    feature_id: advanced_workflows
config:
  disable_pooled_balance: false
  disable_overage_billing: false
```

```json
id: 2ee25a41-0d81-4ad2-8451-ec1aadaefe58
name: Patrick
email: patrick@useautumn.com
createdAt: 1771409161016
fingerprint: null
stripeId: cus_U0BKxpq1mFhuJO
processors:
  stripe:
    id: 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: []
licenses: []
balances:
  messages:
    featureId: messages
    granted: 100
    remaining: 0
    usage: 100
    unlimited: false
    overageAllowed: false
    maxPurchase: null
    nextResetAt: 1773851121437
    breakdown:
```

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

### Feature Balance Example

Source: https://docs.useautumn.com/api-reference/balances/trackTokens

Example JSON object representing a feature's current usage, grant, and reset configuration.

```yaml
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
```

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

### Coupon Example Object

Source: https://docs.useautumn.com/api-reference/rewards/getReward

An example of a coupon object structure including discount details, duration, and promo codes.

```json
{
  "id": "summer_sale",
  "name": "Summer Sale",
  "type": "percentage_discount",
  "value": 20,
  "duration": {
    "type": "months",
    "length": 3
  },
  "plan_ids": [
    "pro",
    "starter"
  ],
  "promo_codes": [
    {
      "code": "SUMMER20",
      "global_max_redemption": 100,
      "first_time_transaction": false
    }
  ],
  "created_at": 1718000000000
}
```

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

### DfuFlashParams Example

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

Example payload for the billing import operation, demonstrating the structure for customer, processor, and billable plan information.

```json
customer_id: cus_123
processors:
  - type: stripe
    id: cus_stripe_123
billables:
  - processor: stripe
    link:
      subscription_id: sub_123
    plan:
      plan_id: pro
      status: active
      balances:
        - feature_id: messages
          usage: 10
```

```json
example:
  customer_id: cus_123
  processors:
    - type: stripe
      id: cus_stripe_123
  billables:
    - processor: stripe
      link:
        subscription_id: sub_123
      plan:
        plan_id: pro
        status: active
        balances:
          - feature_id: messages
            usage: 10
```

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

### DfuFlashResult OpenAPI Example

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

Example data structure for the DfuFlashResult object, including customer details, subscription status, and balance information.

```yaml
customer_id: cus_123
flashed:
  - plan_id: pro
    processor: stripe
    customer_product_id: cus_prod_123
    status: active
    skipped: false
customer:
  id: cus_123
  name: Jane Doe
  email: jane@example.com
  createdAt: 1771409161016
  fingerprint: null
  stripeId: cus_stripe_123
  processors:
    stripe:
      id: cus_stripe_123
  env: sandbox
  metadata: {}
  sendEmailReceipts: false
  billingControls:
    autoTopups: []
  subscriptions:
    - planId: pro
      autoEnable: false
      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: 90
      usage: 10
      unlimited: false
      overageAllowed: false
      maxPurchase: null
      nextResetAt: 1773851121437
      breakdown:
        - id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
          planId: pro
          includedGrant: 100
          prepaidGrant: 0
          remaining: 90
          usage: 10
          unlimited: false
          reset:
            interval: month
            resetsAt: 1773851121437
          price: null
          expiresAt: null
  flags: {}
  config:
    disable_pooled_balance: false
    disable_overage_billing: false
```

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

### Get Entity API Response

Source: https://docs.useautumn.com/api-reference/entities/getEntity

Example of a successful 200 OK response when retrieving an entity.

```json
{
    "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": []
  }
```

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

### Create a Referral Program

Source: https://docs.useautumn.com/api-reference/referrals/createReferralProgram

Use these examples to initialize the SDK and create a new referral program with specific reward and redemption settings.

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

const autumn = new Autumn()

const result = await autumn.referrals.createProgram({
  id: "refer_a_friend",
  rewardId: "beta_credits_grant",
  redeemOn: "customer_creation",
  receivedBy: "referrer",
  maxRedemptions: 10,
  planIds: null,
  excludeTrial: false,
});
```

```python
from autumn_sdk import Autumn

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

res = autumn.referrals.create_program(
    id="refer_a_friend",
    reward_id="beta_credits_grant",
    redeem_on="customer_creation",
    received_by="referrer",
    max_redemptions=10,
    plan_ids=None,
    exclude_trial=False,
)
```

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

### Update Plan Examples

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

Common operations for updating plans, including price adjustments, feature configuration, archiving, and renaming.

```typescript
await autumn.plans.update({
  planId: "pro_plan",
  price: { amount: 15, interval: "month" }
});
```

```typescript
await autumn.plans.update({
  planId: "pro_plan",
  price: null // Removes the base price
});
```

```typescript
await autumn.plans.update({
  planId: "pro_plan",
  items: [
    {
      featureId: "messages",
      included: 2000, // Increased from 1000
      reset: { interval: "month" }
    }
  ]
});
```

```typescript
await autumn.plans.update({
  planId: "old_plan",
  archived: true
});
```

```typescript
await autumn.plans.update({
  planId: "pro_plan",
  name: "Pro Plan (Updated)",
  newPlanId: "pro_plan_v2" // Optional: change the plan ID
});
```

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

### Update a Plan using the Autumn SDK

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

Use these examples to modify plan attributes like name and price. Ensure the plan ID corresponds to an existing plan in your environment.

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

const autumn = new Autumn()

const result = await autumn.plans.update({
  planId: "pro_plan",
  name: "Pro Plan (Updated)",
  price: {
    amount: 15,
    interval: "month",
  },
});
```

```python
from autumn_sdk import Autumn

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

res = autumn.plans.update(
    plan_id="pro_plan",
    name="Pro Plan (Updated)",
    price={
        "amount": 15,
        "interval": "month",
    },
    create_in_stripe=True,
    archived=False,
)
```

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

### Update Plan API Success Response

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

Example of a successful 200 OK response returned when updating a plan.

```json
{
  "id": "pro",
  "name": "Pro Plan",
  "description": null,
  "group": null,
  "version": 1,
  "version_slug": "v1",
  "active": true,
  "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,
  "config": {
    "ignore_past_due": false
  },
  "billing_controls": {},
  "metadata": {}
}
```

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

### Get Customer API Success Response

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

Example of a successful 200 response containing customer profile, subscription, and balance information.

```json
{
    "id": "2ee25a41-0d81-4ad2-8451-ec1aadaefe58",
    "name": "Patrick",
    "email": "patrick@useautumn.com",
    "createdAt": 1771409161016,
    "fingerprint": null,
    "stripeId": "cus_U0BKxpq1mFhuJO",
    "processors": {
      "stripe": {
        "id": "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": [],
    "licenses": [],
    "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
          }
        ]
      }
    },
    "flags": {
      "advanced_workflows": {
        "id": "cus_ent_abc123",
        "plan_id": "pro_plan",
        "expires_at": null,
        "feature_id": "advanced_workflows"
      }
    },
    "config": {
      "disable_pooled_balance": false,
      "disable_overage_billing": false
    }
  }
```

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

### Initialize a Project

Source: https://docs.useautumn.com/cli/getting-started

Create an autumn.config.ts file in your project root.

```bash
bunx atmn init
```

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

### Get Reward API Response Example

Source: https://docs.useautumn.com/api-reference/rewards/getReward

A successful 200 OK response containing coupon details, duration, and promo code configuration.

```json
{
    "coupon": {
      "id": "summer_sale",
      "name": "Summer Sale",
      "type": "percentage_discount",
      "value": 20,
      "duration": {
        "type": "months",
        "length": 3
      },
      "plan_ids": [
        "pro",
        "starter"
      ],
      "promo_codes": [
        {
          "code": "SUMMER20",
          "global_max_redemption": 100,
          "first_time_transaction": false
        }
      ],
      "created_at": 1718000000000
    }
  }
```

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

### Push configuration to production

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

Use the CLI to deploy your configuration to the production environment.

```bash
bunx atmn push -p
```

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

### autumn.billing.setupPayment

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

Initiates the payment setup process for a customer, returning a redirect URL.

```APIDOC
## SDK Method: setupPayment

### Description
Generates a redirect URL for the customer to complete their payment setup.

### Parameters
- **customer_id** (string) - Required - The unique identifier for the customer.
- **success_url** (string) - Required - The URL to redirect the customer to after successful setup.

### TypeScript Example
```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 Example
```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",
)
```

### Response
- **customer_id** (string) - The customer identifier.
- **url** (string) - The URL to redirect the customer to setup their payment.
```

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

### List Plans Response Example

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

A successful 200 OK response containing a list of plan objects with their respective pricing, items, and configuration metadata.

```json
{
  "list": [
    {
      "id": "pro",
      "name": "Pro Plan",
      "description": null,
      "group": null,
      "version": 1,
      "version_slug": "v1",
      "active": true,
      "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,
      "config": {
        "ignore_past_due": false
      },
      "billing_controls": {},
      "metadata": {}
    }
  ]
}
```

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

### Billing Feature Example

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

Example of a billing feature object identifier.

```json
id: cus_ent_39qmLooixXLAqMywgXywjAz96rV
```

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

### Feature Example Object

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

Example of a metered feature object structure.

```json
id: api-calls
name: API Calls
type: metered
consumable: true
archived: false
display:
  singular: API call
  plural: API calls
```

```json
id: api-calls
name: API Calls
type: metered
```

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

### Insert Invoices Request Example

Source: https://docs.useautumn.com/api-reference/invoices/insertInvoices

Example JSON payload for the insertInvoices operation.

```json
invoices:
  - customer_id: cus_123
    plan_ids:
      - pro
    stripe_id: in_legacy_123
    processor_type: stripe
    status: paid
    total: 29.99
    amount_paid: 29.99
    refunded_amount: 0
    currency: usd
    created_at: 1451606400000
    hosted_invoice_url: https://billing.example.com/invoices/legacy-123
```

```json
{
  "invoices": [
    {
      "customer_id": "cus_123",
      "plan_ids": [
        "pro"
      ],
      "stripe_id": "in_legacy_123",
      "processor_type": "stripe",
      "status": "paid",
      "total": 29.99,
      "amount_paid": 29.99,
      "refunded_amount": 0,
      "currency": "usd",
      "created_at": 1451606400000,
      "hosted_invoice_url": "https://billing.example.com/invoices/legacy-123"
    }
  ]
}
```

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

### POST /v1/billing.setup_payment

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

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

```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
/v1/billing.setup_payment

### Parameters
#### Header Parameters
- **x-api-version** (string) - Required - The API version to use.

#### Request Body
- **customer_id** (string) - Optional - The ID of the customer to attach the plan to.
- **entity_id** (string) - Optional - 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 - If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature.
- **version** (number) - Optional - The version of the plan to attach.
- **free_trial** (object) - Optional - Free trial for this plan.
- **customize** (object) - Optional - Customization options for the plan.
```

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

### Create a Plan using Autumn SDK

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

Use these examples to initialize the Autumn client and create a new plan with specific feature configurations.

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

const autumn = new Autumn()

const result = await autumn.plans.create({
  planId: "free_plan",
  name: "Free",
  autoEnable: true,
  items: [
    {
      featureId: "messages",
      included: 100,
      reset: {
        interval: "month",
      },
    },
  ],
});
```

```python
from autumn_sdk import Autumn

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

res = autumn.plans.create(
    plan_id="free_plan",
    name="Free",
    group="",
    add_on=False,
    auto_enable=True,
    items=[
        {
            "feature_id": "messages",
            "included": 100,
            "reset": {
                "interval": "month",
            },
        },
    ],
    create_in_stripe=True,
)
```

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

### List Licenses Response Example

Source: https://docs.useautumn.com/api-reference/licenses/listLicenses

A successful 200 OK response containing a list of license objects.

```json
{
    "list": [
      {
        "license_plan_id": "seat_plan",
        "parent_plan_id": "pro_plan",
        "license_plan_name": "Seat",
        "granted": 10,
        "usage": 3,
        "remaining": 7,
        "paid_quantity": 5
      }
    ]
  }
```

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

### Initialize Autumn configuration

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

Creates an autumn.config.ts file from a starter template and initiates authentication if required.

```bash
atmn init
```

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

### Update Customer Response Example

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

Example response object returned after a successful update.

```yaml
customer_id: cus_123
name: Jane Doe
email: jane@example.com
```

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

### Preview Multi-Update Response Example

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

A successful 200 OK response showing the structure of subscription updates, including customer details, line items, and plan IDs.

```json
{
    "customer_id": "cus_123",
    "currency": "usd",
    "total": -40,
    "subscriptions": [
      {
        "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",
        "plan_ids": [
          "pro_plan"
        ]
      },
      {
        "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",
        "plan_ids": [
          "addon_seats"
        ]
      }
    ]
  }
```

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

### Preview Multi-Update Billing SDK Examples

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

Use these SDK methods to simulate subscription changes and retrieve the resulting billing preview.

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

const autumn = new Autumn()

const result = await autumn.billing.previewMultiUpdate({
  customerId: "cus_123",
  updates: [
    {
      planId: "pro_plan",
      cancelAction: "cancel_immediately",
    },
    {
      planId: "addon_seats",
      cancelAction: "cancel_immediately",
    },
  ],
});
```

```python
from autumn_sdk import Autumn

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

res = autumn.billing.preview_multi_update(
    customer_id="cus_123",
    updates=[
        {
            "plan_id": "pro_plan",
            "cancel_action": "cancel_immediately",
        },
        {
            "plan_id": "addon_seats",
            "cancel_action": "cancel_immediately",
        },
    ],
)
```

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

### Update Customer Request Example

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

Example payload for updating a customer's details.

```yaml
- customer_id: cus_123
  name: Jane Doe
  email: jane@example.com
```

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

### UpdateRewardResponse Example

Source: https://docs.useautumn.com/api-reference/rewards/updateReward

Example response structure for an updated reward containing a feature grant.

```json
feature_grant:
  id: beta_credits_grant
```

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

### Preview Multi-Attach with SDKs

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

Use these examples to preview billing outcomes when attaching multiple plans to a customer. Ensure the SDK is initialized with appropriate credentials before calling the method.

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

const autumn = new Autumn()

const result = await autumn.billing.previewMultiAttach({
  customerId: "cus_123",
  plans: [
    {
      planId: "pro_plan",
    },
    {
      planId: "addon_seats",
      featureQuantities: [
        {
          featureId: "seats",
          quantity: 5,
        },
      ],
    },
  ],
});
```

```python
from autumn_sdk import Autumn

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

res = autumn.billing.preview_multi_attach(
    customer_id="cus_123",
    plans=[
        {
            "plan_id": "pro_plan",
        },
        {
            "plan_id": "addon_seats",
            "feature_quantities": [
                {
                    "feature_id": "seats",
                    "quantity": 5,
                },
            ],
        },
    ],
    redirect_mode="if_required",
)
```

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

### Preview Billing Update with SDK

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

Use these examples to preview plan updates for a specific customer. Ensure the SDK is initialized with appropriate credentials before calling the preview method.

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

const autumn = new Autumn()

const result = await autumn.billing.previewUpdate({
  customerId: "cus_123",
  planId: "pro_plan",
  featureQuantities: [
    {
      featureId: "seats",
      quantity: 15,
    },
  ],
});
```

```python
from autumn_sdk import Autumn

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

res = autumn.billing.preview_update(
    customer_id="cus_123",
    plan_id="pro_plan",
    feature_quantities=[
        {
            "feature_id": "seats",
            "quantity": 15,
        },
    ],
    redirect_mode="if_required",
)
```

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

### Push Configuration to Sandbox

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

Sync your local configuration changes to the Autumn sandbox environment.

```bash
bunx atmn push
```

```bash
npx atmn push
```

```bash
pnpm dlx atmn push
```
Tokens:
Raw