---
title: "Update Subscription"
openapi: "openapi POST /v1/billing.update"
---

import { DynamicParamField } from "/components/dynamic-param-field.jsx";
import { DynamicResponseField } from "/components/dynamic-response-field.jsx";
import { DynamicResponseExample } from "/components/dynamic-response-example.jsx";

<Note>
  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](/api-reference/billing/billingAttach) instead.
</Note>

### Common Use Cases

<CodeGroup>

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

```typescript Cancel at end of cycle
const response = await autumn.billing.update({
  customerId: "cus_123",
  planId: "pro_plan",
  cancelAction: "cancel_end_of_cycle"
});
```

```typescript Uncancel subscription
const response = await autumn.billing.update({
  customerId: "cus_123",
  planId: "pro_plan",
  cancelAction: "uncancel"
});
```

</CodeGroup>

### Body Parameters

<DynamicParamField body="customer_id" type="string" required>
  The ID of the customer to attach the plan to.
</DynamicParamField>

<DynamicParamField body="entity_id" type="string">
  The ID of the entity to attach the plan to.
</DynamicParamField>

<DynamicParamField body="plan_id" type="string" required>
  The ID of the plan.
</DynamicParamField>

<DynamicParamField body="feature_quantities" type="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.
  <Expandable title="properties">
    <DynamicParamField body="feature_id" type="string" required />

    <DynamicParamField body="quantity" type="number" />

    <DynamicParamField body="adjustable" type="boolean" />

  </Expandable>
</DynamicParamField>

<DynamicParamField body="version" type="number">
  The version of the plan to attach.
</DynamicParamField>

<DynamicParamField body="free_trial" type="object | null">
  Override the plan's default free trial. Pass an object to set a custom trial, or null to remove the trial entirely.
  <Expandable title="properties">
    <DynamicParamField body="duration_length" type="number" required />

    <DynamicParamField body="duration_type" type="'day' | 'month' | 'year'" />

    <DynamicParamField body="card_required" type="boolean" />

  </Expandable>
</DynamicParamField>

<DynamicParamField body="customize" type="object">
  Customize the plan to attach. Can either override the price of the plan, the items in the plan, or both.
  <Expandable title="properties">
    <DynamicParamField body="price" type="object | null">
      <Expandable title="properties">
        <DynamicParamField body="amount" type="number" required />

        <DynamicParamField body="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" required />

        <DynamicParamField body="interval_count" type="number" />

      </Expandable>
    </DynamicParamField>

    <DynamicParamField body="items" type="object[]">
      <Expandable title="properties">
        <DynamicParamField body="feature_id" type="string" required />

        <DynamicParamField body="included" type="number" />

        <DynamicParamField body="unlimited" type="boolean" />

        <DynamicParamField body="reset" type="object">
          <Expandable title="properties">
            <DynamicParamField body="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" required />

            <DynamicParamField body="interval_count" type="number" />

          </Expandable>
        </DynamicParamField>

        <DynamicParamField body="price" type="object">
          <Expandable title="properties">
            <DynamicParamField body="amount" type="number" />

            <DynamicParamField body="tiers" type="object[]">
              <Expandable title="properties">
                <DynamicParamField body="to" type="number" required />

                <DynamicParamField body="amount" type="number" required />

              </Expandable>
            </DynamicParamField>

            <DynamicParamField body="interval" type="'one_off' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'" required />

            <DynamicParamField body="interval_count" type="number" />

            <DynamicParamField body="billing_units" type="number" />

            <DynamicParamField body="billing_method" type="'prepaid' | 'usage_based'" required />

            <DynamicParamField body="max_purchase" type="number" />

          </Expandable>
        </DynamicParamField>

        <DynamicParamField body="proration" type="object">
          <Expandable title="properties">
            <DynamicParamField body="on_increase" type="'bill_immediately' | 'prorate_immediately' | 'prorate_next_cycle' | 'bill_next_cycle'" required />

            <DynamicParamField body="on_decrease" type="'prorate' | 'prorate_immediately' | 'prorate_next_cycle' | 'none' | 'no_prorations'" required />

          </Expandable>
        </DynamicParamField>

        <DynamicParamField body="rollover" type="object">
          <Expandable title="properties">
            <DynamicParamField body="max" type="number" />

            <DynamicParamField body="expiry_duration_type" type="'month' | 'forever'" required />

            <DynamicParamField body="expiry_duration_length" type="number" />

          </Expandable>
        </DynamicParamField>

      </Expandable>
    </DynamicParamField>

  </Expandable>
</DynamicParamField>

<DynamicParamField body="invoice_mode" type="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.
  <Expandable title="properties">
    <DynamicParamField body="enabled" type="boolean" required>
      When true, creates an invoice and sends it to the customer instead of charging their card immediately. Uses Stripe's send_invoice collection method.
    </DynamicParamField>

    <DynamicParamField body="enable_plan_immediately" type="boolean">
      If true, enables the plan immediately even though the invoice is not paid yet.
    </DynamicParamField>

    <DynamicParamField body="finalize" type="boolean">
      If true, finalizes the invoice so it can be sent to the customer. If false, keeps it as a draft for manual review.
    </DynamicParamField>

  </Expandable>
</DynamicParamField>

<DynamicParamField body="billing_behavior" type="'prorate_immediately' | 'next_cycle_only'">
  How to handle billing when updating an existing subscription. 'prorate_immediately' charges/credits prorated amounts now, 'next_cycle_only' skips creating any charges and applies the change at the next billing cycle.
</DynamicParamField>

<DynamicParamField body="cancel_action" type="'cancel_immediately' | 'cancel_end_of_cycle' | 'uncancel'">
  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.
</DynamicParamField>


### Response

<DynamicResponseField name="customer_id" type="string">
  The ID of the customer.
</DynamicResponseField>

<DynamicResponseField name="entity_id" type="string">
  The ID of the entity, if the plan was attached to an entity.
</DynamicResponseField>

<DynamicResponseField name="invoice" type="object">
  Invoice details if an invoice was created. Only present when a charge was made.
  <Expandable title="properties">
    <DynamicResponseField name="status" type="string | null">
      The status of the invoice (e.g., 'paid', 'open', 'draft').
    </DynamicResponseField>

    <DynamicResponseField name="stripe_id" type="string">
      The Stripe invoice ID.
    </DynamicResponseField>

    <DynamicResponseField name="total" type="number">
      The total amount of the invoice in cents.
    </DynamicResponseField>

    <DynamicResponseField name="currency" type="string">
      The three-letter ISO currency code (e.g., 'usd').
    </DynamicResponseField>

    <DynamicResponseField name="hosted_invoice_url" type="string | null">
      URL to the hosted invoice page where the customer can view and pay the invoice.
    </DynamicResponseField>

  </Expandable>
</DynamicResponseField>

<DynamicResponseField name="payment_url" type="string | null">
  URL to redirect the customer to complete payment. Null if no payment action is required.
</DynamicResponseField>

<DynamicResponseField name="required_action" type="object">
  Details about any action required to complete the payment. Present when the payment could not be processed automatically.
  <Expandable title="properties">
    <DynamicResponseField name="code" type="'3ds_required' | 'payment_method_required' | 'payment_failed'">
      The type of action required to complete the payment.
    </DynamicResponseField>

    <DynamicResponseField name="reason" type="string">
      A human-readable explanation of why this action is required.
    </DynamicResponseField>

  </Expandable>
</DynamicResponseField>


<ResponseExample>
```json 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
}
```
</ResponseExample>