Skip to main content
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: 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 }
  ],
});

​
Canceling a subscription

Use cancelAction to cancel or uncancel a subscription:
ActionDescription
cancel_end_of_cycleCancel at the end of the current billing period. Customer retains access until then.
cancel_immediatelyCancel immediately with a prorated refund.
uncancelReverse 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",
});

​
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

​
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.