Skip to main content

​
Upgrades

Upgrades happen when you attach a plan with a higher price than the customer’s current plan. Use billing.attach — Autumn handles the rest.
If a payment method exists, attaching the plan will immediately charge the customer. If upgrading from a free to a paid plan, a checkout URL is generated instead.
Pricing behavior:
  • Fixed prices are prorated based on time remaining in the billing period
  • Usage-based prices bill outstanding usage at the old rate immediately, then apply the new rate going forward

​
Downgrades

Downgrades happen when you attach a plan with a lower price. Unlike upgrades, downgrades are scheduled to take effect at the end of the current billing period. The new plan will have status scheduled until it activates. Customers can cancel a scheduled downgrade by re-attaching their current plan.
If you’ve set a group when creating plans, upgrades and downgrades only apply between plans in the same group. Attaching a plan from a different group adds it alongside the existing plan.

​
Cancellations

Cancel a subscription using billing.update with the cancelAction parameter. By default, cancellations take effect at the end of the billing period.

​
Cancel at end of billing period

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

const { updateSubscription } = useCustomer();

await updateSubscription({
  planId: "pro",
  cancelAction: "cancel_end_of_cycle",
});
The subscription remains active until the end of the current billing period. If you have a default plan (with is_default set), it will be activated after the cancellation takes effect.

​
Cancel immediately

To cancel a subscription right away with a prorated refund: 
import { useCustomer } from "autumn-js/react";

const { updateSubscription } = useCustomer();

await updateSubscription({
  planId: "pro",
  cancelAction: "cancel_immediately",
});
This ends the subscription immediately and issues a prorated refund for the remaining time in the billing period.

​
Uncanceling

If a subscription was scheduled for cancellation (via cancel_end_of_cycle), you can reverse it before the period ends using uncancel: 
import { useCustomer } from "autumn-js/react";

const { updateSubscription } = useCustomer();

await updateSubscription({
  planId: "pro",
  cancelAction: "uncancel",
});
This clears the pending cancellation and the subscription continues as normal. Any default plan that was scheduled to activate after cancellation is also removed.
You cannot uncancel a subscription that was already canceled immediately — only pending cancellations (scheduled for end of cycle) can be reversed.

​
Canceling a scheduled plan change

When a downgrade or other plan change is scheduled for the end of the billing period, canceling it works the same way as uncanceling. Call billing.update with cancelAction: "uncancel" on the customer’s active plan: 
import { useCustomer } from "autumn-js/react";

const { updateSubscription } = useCustomer();

// Customer is on Pro with a scheduled downgrade to Basic.
// Cancel the scheduled change and keep Pro.
await updateSubscription({
  planId: "pro",
  cancelAction: "uncancel",
});
This removes the scheduled replacement plan and keeps the customer on their current plan.

​
cancel_action reference

ValueBehavior
cancel_end_of_cycleSchedules cancellation at the end of the current billing period. Subscription stays active until then.
cancel_immediatelyCancels immediately with a prorated refund for remaining time.
uncancelReverses a pending cancellation or removes a scheduled plan change.

​
Usage reset behavior

When a new plan is enabled, you can control what happens to existing feature usage with the reset_usage_when_enabled property on the plan item:
  • true: Usage resets to 0 (typical for consumable features like credits)
  • false: Usage carries over to the new plan (typical for continuous features like seats)
Example: A customer on Free has used 20 of their 100 credits. They upgrade to Pro which includes 500 credits.
  • If reset_usage_when_enabled = true: They get 500 credits
  • If reset_usage_when_enabled = false: They get 480 credits (500 - 20 used)