Sign in

v1

latestOpenAPI 3.1.02026-07-265817860.8 KB
billing

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

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": 10
    }
  ]
}

Response

OK

customer_idstring required

The ID of the customer.

entity_idstring

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

payment_urlstring nullable required

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

Example response

{
  "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
}