Sign in

v1

latestOpenAPI 3.1.02026-07-265817860.8 KB
billing

Previews the billing changes of a multi-plan update without making any changes. Returns one core preview per affected subscription.

Use this endpoint to show customers the credits and next-cycle changes of canceling multiple plans before confirming.

post/v1/billing.preview_multi_update

Headers

x-api-versionstring required

Request body

customer_idstring required

The ID of the customer to update plans for.

entity_idstring

The ID of the entity to update plans for. Individual updates can override this with their own entity_id.

Example request

{
  "customer_id": "cus_123",
  "updates": [
    {
      "plan_id": "pro_plan",
      "cancel_action": "cancel_immediately"
    },
    {
      "plan_id": "addon_seats",
      "cancel_action": "cancel_immediately"
    }
  ]
}

Response

OK

customer_idstring required

The ID of the customer the preview applies to.

currencystring required

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

totalnumber required

The combined amount due today across all subscriptions (sum of subscriptions[].total).

Example response

{
  "customer_id": "cus_123",
  "currency": "usd",
  "total": -40,
  "subscriptions": [
    {
      "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",
      "plan_ids": [
        "pro_plan"
      ]
    },
    {
      "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",
      "plan_ids": [
        "addon_seats"
      ]
    }
  ]
}