Updating Subscriptions

Use billing.update to modify an existing subscription. This is different from billing.attach which is for attaching new plans or changing between plans. When to use billing.update:

Update feature quantities — if your plan contains prepaid features (like seats)
Cancel or uncancel — cancel a subscription immediately or at end of cycle
Customize the plan — modify pricing or feature configuration (advanced)

Updating prepaid feature quantities

Prepaid features are features where customers pay upfront for a quantity (e.g., seats, team members). Here’s an example plan with a prepaid seats feature:

Show Example plan with prepaid feature

autumn.config.ts

import { atmn, feature, plan } from "atmn";

export const seats = feature({
  featureId: "seats",
  name: "Seats",
  type: "metered",
  consumable: false, // Non-consumable = doesn't reset
});

export const team = plan({
  planId: "team",
  versionSlug: "v1",
  active: true,
  name: "Team Plan",
  price: {
    amount: 49,
    interval: "month",
  },
  items: [
    {
      featureId: seats.featureId,
      included: 5, // 5 seats included
      price: {
        amount: 10, // $10 per additional seat
        interval: "month",
        billingMethod: "prepaid",
      },
    },
  ],
});

export default atmn({ features: [seats], plans: [team] });

To update the quantity of seats for a customer:

const response = await autumn.billing.update({
  customerId: "user_123",
  planId: "team",
  featureQuantities: [
    { featureId: "seats", quantity: 10 }
  ],
});

response = await autumn.billing.update(
    customer_id="user_123",
    plan_id="team",
    feature_quantities=[
        { "feature_id": "seats", "quantity": 10 }
    ],
)

curl -X POST 'https://api.useautumn.com/v1/billing/update' \
  -H 'Authorization: Bearer am_sk_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer_id": "user_123",
    "plan_id": "team",
    "feature_quantities": [
      { "feature_id": "seats", "quantity": 10 }
    ]
  }'

Canceling a subscription

Use cancelAction to cancel or uncancel a subscription:

Action	Description
`cancel_end_of_cycle`	Cancel at the end of the current billing period. Customer retains access until then.
`cancel_immediately`	Cancel immediately with a prorated refund.
`uncancel`	Reverse a pending cancellation (only works if not yet expired).

// Cancel at end of billing cycle
await autumn.billing.update({
  customerId: "user_123",
  planId: "pro",
  cancelAction: "cancel_end_of_cycle",
});

// Uncancel a pending cancellation
await autumn.billing.update({
  customerId: "user_123",
  planId: "pro",
  cancelAction: "uncancel",
});

# Cancel at end of billing cycle
await autumn.billing.update(
    customer_id="user_123",
    plan_id="pro",
    cancel_action="cancel_end_of_cycle",
)

curl -X POST 'https://api.useautumn.com/v1/billing/update' \
  -H 'Authorization: Bearer am_sk_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer_id": "user_123",
    "plan_id": "pro",
    "cancel_action": "cancel_end_of_cycle"
  }'

Switching between invoicing and charging automatically

Call billing.update with invoice_mode as the only change to switch how an existing subscription is collected. The switch applies from the next renewal: nothing is charged or invoiced now, and invoices that are already open keep their payment method.

// Send invoices from the next renewal, due in 30 days, payable by card or ACH
await autumn.billing.update({
  customerId: "user_123",
  planId: "team",
  invoiceMode: {
    enabled: true,
    netTermsDays: 30,
    paymentMethodTypes: ["card", "us_bank_account"],
  },
});

// Charge the card on file automatically again
await autumn.billing.update({
  customerId: "user_123",
  planId: "team",
  invoiceMode: { enabled: false },
});

curl -X POST 'https://api.useautumn.com/v1/billing.update' \
  -H 'Authorization: Bearer am_sk_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer_id": "user_123",
    "plan_id": "team",
    "invoice_mode": {
      "enabled": true,
      "net_terms_days": 30,
      "payment_method_types": ["card", "us_bank_account"]
    }
  }'

Switching to charging automatically requires a payment method on file; otherwise the request is rejected.
payment_method_types overrides your organization’s default payment methods. Omit it to keep the defaults.
If the request changes anything else (plan, quantities, items), invoice_mode describes how that change is billed instead of switching the subscription.

To change the payment methods on an invoice that is already draft or open, use invoices.update.

How billing works

By default, updating a subscription with billing changes will generate an invoice:

Increasing quantity (e.g., adding seats) charges a prorated amount for the remainder of the billing cycle
Decreasing quantity (e.g., removing seats) generates a credit applied to the next invoice
Canceling immediately generates a negative invoice granting credits to the customer

Previewing changes before executing

Similar to billing.previewAttach, you can use billing.previewUpdate to see exactly what will be charged before making changes. This returns line items and totals that you can display in a confirmation UI.

const preview = await autumn.billing.previewUpdate({
  customerId: "user_123",
  planId: "team",
  featureQuantities: [
    { featureId: "seats", quantity: 10 }
  ],
});

// Display preview.lineItems, preview.total, preview.currency
// Then call billing.update to execute

preview = await autumn.billing.preview_update(
    customer_id="user_123",
    plan_id="team",
    feature_quantities=[
        { "feature_id": "seats", "quantity": 10 }
    ],
)

# Display preview.line_items, preview.total

curl -X POST 'https://api.useautumn.com/v1/billing/preview-update' \
  -H 'Authorization: Bearer am_sk_...' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer_id": "user_123",
    "plan_id": "team",
    "feature_quantities": [
      { "feature_id": "seats", "quantity": 10 }
    ]
  }'

Skipping charges

If you want to update a subscription without creating any charges or credits, pass prorationBehavior: "none":

await autumn.billing.update({
  customerId: "user_123",
  planId: "team",
  featureQuantities: [
    { featureId: "seats", quantity: 10 }
  ],
  prorationBehavior: "none", // No charges or credits created
});

This is useful for administrative adjustments or when you want to handle billing separately.

Getting Started

Configure Pricing

Billing & Subscriptions

Customers

Additional Resources

Updating Subscriptions

Updating prepaid feature quantities

Canceling a subscription

Switching between invoicing and charging automatically

How billing works

Previewing changes before executing

Skipping charges

​Updating prepaid feature quantities

​Canceling a subscription

​Switching between invoicing and charging automatically

​How billing works

​Previewing changes before executing

​Skipping charges

Updating prepaid feature quantities

Canceling a subscription

Switching between invoicing and charging automatically

How billing works

Previewing changes before executing

Skipping charges