Update Subscription

Updates an existing subscription. Use to modify feature quantities, cancel, or change plan configuration.

Use this endpoint to update prepaid quantities, cancel a subscription (immediately or at end of cycle), or modify subscription settings.

POST /v1/billing.update

Typescript (SDK)

TypeScript

import { Autumn } from 'autumn-js'

const autumn = new Autumn()

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

200

{
  "customer_id": "cus_123",
  "invoice": {
    "status": "paid",
    "stripe_id": "in_1234",
    "total": 1500,
    "currency": "usd",
    "hosted_invoice_url": "https://invoice.stripe.com/..."
  },
  "payment_url": null
}

The update endpoint modifies an existing subscription. Use this to change prepaid quantities, cancel subscriptions, or modify plan configuration. For subscribing to a new plan, use attach instead.

Common Use Cases

Update prepaid quantity

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

Body Parameters

Response

200

{
  "customer_id": "cus_123",
  "invoice": {
    "status": "paid",
    "stripe_id": "in_1234",
    "total": 1500,
    "currency": "usd",
    "hosted_invoice_url": "https://invoice.stripe.com/..."
  },
  "payment_url": null
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

x-api-version · string · default: 2.4.0 · required

Body

application/json

customer_id · string · required

The ID of the customer to attach the plan to.

entity_id · string

The ID of the entity to attach the plan to.

plan_id · string

The ID of the plan to update. Optional if subscription_id is provided, or if the customer has only one product.

feature_quantities · FeatureQuantity · object[]

If this plan contains prepaid features, use this field to specify the quantity of each prepaid feature. This quantity includes the included amount and billing units defined when setting up the plan.

Show child attributes

version · number

The version of the plan to attach.

free_trial · FreeTrialParams · object | null

Free trial for this plan. A shorthand for customize.free_trial, which takes precedence when both are given.

Show child attributes

customize · object

Customize the plan to attach. Can override the price, items, licenses, free trial, or a combination.

Show child attributes

invoice_mode · object

Invoice mode creates a draft or open invoice and sends it to the customer, instead of charging their card immediately. This uses Stripe's send_invoice collection method.

Show child attributes

proration_behavior · enum<string>

How to handle proration when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'none' skips creating any charges.

Available options: prorate_immediately, none

redirect_mode · enum<string> · default: if_required

Controls when to return a checkout URL. 'always' returns a URL even if payment succeeds, 'if_required' only when payment action is needed, 'never' disables redirects.

Available options: always, if_required, never

subscription_id · string

A unique ID to identify this subscription. Can be used to target specific subscriptions in update operations when a customer has multiple products with the same plan.

discounts · AttachDiscount · object[]

List of discounts to apply. Each discount can be an Autumn reward ID, Stripe coupon ID, or Stripe promotion code.

Show child attributes

cancel_action · enum<string>

Action to perform for cancellation. 'cancel_immediately' cancels now with prorated refund, 'cancel_end_of_cycle' cancels at period end, 'uncancel' reverses a pending cancellation.

Available options: cancel_immediately, cancel_end_of_cycle, uncancel

billing_cycle_anchor · any integer

Reset the billing cycle immediately with 'now', or schedule a reset at a future Unix timestamp in milliseconds.

no_billing_changes · boolean

If true, the subscription is updated internally without applying billing changes in Stripe.

refund_last_payment · enum<string>

Controls how the last payment is refunded on immediate cancellation. 'prorated' refunds the unused portion, 'full' refunds the entire last payment.

Available options: prorated, full

subscription_params · SubscriptionParams · object

Additional parameters to pass into the Stripe subscription update or cancel call.

Show child attributes

recalculate_balances · object

Controls whether balances should be recalculated during the subscription update.

Show child attributes

carry_over_usages · object

Whether to carry over usages from the previous plan.

Show child attributes

license_quantities · object[]

Total seat quantities (inclusive of the license's included count) per license plan offered by this plan. Licenses not listed keep their current paid quantity.

Show child attributes

Response

200 - application/json

OK

customer_id · string · required

The ID of the customer.

payment_url · string | null · required

URL to redirect the customer to complete payment. Null if no payment action is required.

entity_id · string

The ID of the entity, if the plan was attached to an entity.

invoice · object

Invoice details if an invoice was created. Only present when a charge was made.

Show child attributes

required_action · object

Details about any action required to complete the payment. Present when the payment could not be processed automatically.

Show child attributes