---
title: "Swap the subscription plan of a billable entity."
method: POST
path: "/api/subscription/swap-plan"
tags: ["Subscription"]
---

# Swap the subscription plan of a billable entity.

`POST /api/subscription/swap-plan`

## Request

- Base URL: `https://api.sponsorunited.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.sponsorunited.com/api/subscription/swap-plan`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/sponsorunited/apis/sponsorunited-api/docs/api/subscription/swap-plan/post.ts> (a function with typed inputs; its response is checked against the schema)

Swaps the Stripe subscription of the billable named by `billable_id` onto another plan without prorating, and records the new contracted monthly spend against that billable's organization. The target is the billable in the request, not the one belonging to the acting user.

## Request body

- SwapPlanRequest
  - `billable_id` integer, required: The billable entity whose plan is swapped. Soft-deleted billables are rejected.
  - `subscription_plan_id` string, required: The Stripe price ID to swap to.
  - `contract_monthly_spend` number, float, required: The contracted monthly spend for the new plan. Stored against the billable's organization.

## Response `200`

The swap was attempted. A successful swap returns the new plan; a billable that cannot be swapped (no Stripe customer, no Stripe subscription, or rejected by Stripe) returns an `error`.

- object
  - `subscription_plan_id` string: The plan now active on the subscription. Absent when `error` is present.
  - `error` string: Why the swap could not be completed. Absent on success.

## Other responses

- `403`: The user lacks the permission required to swap subscription plans.
- `422`: Validation failed — a missing or non-integer `billable_id`, one that matches no billable or a soft-deleted one, a missing plan, or a non-numeric monthly spend.

---

[API](https://skmtc.dev/sponsorunited/apis/sponsorunited-api.md) - [All operations](https://skmtc.dev/sponsorunited/apis/sponsorunited-api/llms.txt) - [OpenAPI document](https://skmtc.dev/sponsorunited/apis/sponsorunited-api/revisions/cbf1ca5bff8f?raw)