Sign in

v1

latestOpenAPI 3.1.02026-07-265817860.8 KB
billing

Previews the billing changes that would occur when updating a subscription, without actually making any changes.

Use this endpoint to show customers prorated charges or refunds before confirming subscription modifications.

post/v1/billing.preview_update

Headers

x-api-versionstring required

Request body

customer_idstring required

The ID of the customer to attach the plan to.

entity_idstring

The ID of the entity to attach the plan to.

plan_idstring

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

versionnumber

The version of the plan to attach.

proration_behavior'prorate_immediately' | 'none'

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

redirect_mode'always' | 'if_required' | 'never'

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.

subscription_idstring

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.

cancel_action'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.

billing_cycle_anchor'now'

Reset the billing cycle anchor immediately with 'now'

no_billing_changesboolean

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

refund_last_payment'prorated' | 'full'

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

Example request

{
  "customer_id": "cus_123",
  "plan_id": "pro_plan",
  "feature_quantities": [
    {
      "feature_id": "seats",
      "quantity": 15
    }
  ]
}

Response

OK

customer_idstring required

The ID of the customer.

subtotalnumber required

The total amount in cents before discounts and tax for the current billing period.

totalnumber required

The final amount in cents after discounts and tax for the current billing period.

currencystring required

The three-letter ISO currency code (e.g., 'usd').

expandstring[]

Expand the response with additional data.

intent'update_plan' | 'update_quantity' | 'cancel_immediately' | 'cancel_end_of_cycle' | 'uncancel' | 'none' required

Example response

{
  "customerId": "charles",
  "lineItems": [
    {
      "display_name": "Pro seed",
      "description": "Pro seed - Base Price (from 18 Feb 2026 to 18 Mar 2026)",
      "subtotal": 20,
      "total": 20,
      "discounts": []
    }
  ],
  "subtotal": 20,
  "total": 20,
  "currency": "usd"
}