Checking your plan and changing your organization's subscription

Your organization pays Rollfuse for its own seat on the platform, on whichever plan (Starter, Growth, Enterprise, and so on) it is currently assigned. This tutorial walks through three calls: listing the plans Rollfuse currently publishes, reading your organization's own subscription, and switching that subscription to a different plan. All three operate on your organization's relationship with Rollfuse itself; none of them expose a billing surface to your own end users.

List the published plan catalog

GET /v1/billing/plans returns every plan currently published, with its versions, seat/usage grants, and prices. Any authenticated Member of your organization can call it, regardless of role or permission; it is a read-only catalog, not a mutation.

const res = await fetch("https://api.rollfuse.com/v1/billing/plans", {
  headers: {
    Authorization: `Bearer ${token}`,
  },
});

const { plans } = await res.json();
// plans[].id, plans[].name, plans[].versions[].prices[]

Use this to find the plan_version_id and price_id you want to move to before calling the plan-change endpoint below.

Read your organization's current subscription

GET /v1/organizations/{organization_id}/billing/subscription returns the Subscription record for your own organization: which plan and price it is on, its current billing cycle, and whether a plan change is already scheduled for the next cycle. This call requires a Member session holding the billing:manage permission.

const organizationId = "org_9f2a";

const res = await fetch(
  `https://api.rollfuse.com/v1/organizations/${organizationId}/billing/subscription`,
  {
    headers: {
      Authorization: `Bearer ${token}`,
    },
  },
);

const subscription = await res.json();
// subscription.plan_version_id, subscription.status, subscription.scheduled_plan_change

If scheduled_plan_change is present, a plan change you (or another admin) already requested is queued to take effect at the end of the current billing cycle; the plan-change call below will reject a second request until that one lands.

Change your organization's plan

POST /v1/organizations/{organization_id}/billing/subscription/plan-change moves your organization's subscription to a different plan_version_id/price_id. It also requires billing:manage. An upgrade to a higher-priced plan takes effect immediately and is charged with the new price prorated for the rest of the current cycle; a downgrade is scheduled for the start of the next billing cycle instead, so you keep the plan you already paid for until it ends.

async function changePlan(organizationId, planVersionId, priceId) {
  const res = await fetch(
    `https://api.rollfuse.com/v1/organizations/${organizationId}/billing/subscription/plan-change`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${token}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        plan_version_id: planVersionId,
        price_id: priceId,
      }),
    },
  );

  if (!res.ok) {
    const error = await res.json();
    throw new Error(error.message);
  }

  return res.json();
}

await changePlan("org_9f2a", "planver_growth_2026_09", "price_growth_monthly");

The response is the updated Subscription: check plan_version_id for an immediate upgrade, or scheduled_plan_change for a downgrade that has not taken effect yet. Re-run the GET call above whenever you need to confirm which state your organization landed in, since an upgrade and a downgrade resolve on different timelines.

If your organization has never had a payment method on file (for example, it is still on the default free plan), the first move to a paid plan requires completing checkout before this endpoint accepts a plan change; the GET /v1/organizations/{organization_id}/billing/subscription response's requires_payment_method_to_activate field tells you whether that applies to your organization.