Consultando seu plano e mudando a assinatura da sua organização

Sua organização paga a Rollfuse pela própria vaga na plataforma, seja no plano Starter, Growth, Enterprise ou outro que esteja atribuído a ela no momento. Este tutorial mostra três chamadas: listar os planos que a Rollfuse publica hoje, ler a assinatura da própria organização e trocar essa assinatura para outro plano. As três operam sobre a relação da sua organização com a própria Rollfuse; nenhuma delas expõe uma superfície de cobrança para os usuários finais do seu produto.

Listando o catálogo de planos publicados

GET /v1/billing/plans retorna todos os planos publicados no momento, com suas versões, os limites de assento/uso concedidos e os preços. Qualquer Member autenticado da sua organização pode chamar esse endpoint, independente do papel ou permissão que tenha: é um catálogo somente leitura, não uma mutação.

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 essa consulta para descobrir o plan_version_id e o price_id do plano para o qual você quer migrar, antes de chamar o endpoint de troca de plano mais abaixo.

Lendo a assinatura atual da sua organização

GET /v1/organizations/{organization_id}/billing/subscription retorna o registro de Subscription da sua própria organização: em qual plano e preço ela está, o ciclo de cobrança atual e se já existe uma troca de plano agendada para o próximo ciclo. Essa chamada exige uma sessão de Member com a permissão billing:manage.

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

Se scheduled_plan_change vier preenchido, já existe uma troca de plano pedida antes (por você ou outro admin) esperando para valer no início do próximo ciclo de cobrança; a chamada de troca de plano abaixo vai rejeitar um segundo pedido até essa primeira ser aplicada.

Trocando o plano da sua organização

POST /v1/organizations/{organization_id}/billing/subscription/plan-change move a assinatura da sua organização para outro plan_version_id/price_id. Também exige billing:manage. Um upgrade para um plano mais caro vale imediatamente e é cobrado com o novo preço, rateado pelo tempo restante do ciclo atual; um downgrade fica agendado para o início do próximo ciclo de cobrança, então você continua com o plano que já pagou até ele terminar.

async function trocarPlano(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 trocarPlano("org_9f2a", "planver_growth_2026_09", "price_growth_monthly");

A resposta é a Subscription atualizada: confira plan_version_id para um upgrade imediato, ou scheduled_plan_change para um downgrade que ainda não valeu. Rode de novo a chamada GET acima sempre que precisar confirmar em que estado a sua organização ficou, já que upgrade e downgrade resolvem em prazos diferentes.

Se a sua organização nunca teve uma forma de pagamento cadastrada (por exemplo, ainda está no plano gratuito padrão), a primeira migração para um plano pago exige concluir o checkout antes desse endpoint aceitar a troca de plano; o campo requires_payment_method_to_activate na resposta de GET /v1/organizations/{organization_id}/billing/subscription diz se isso se aplica à sua organização.