# Ferramentas · Assinaturas

> Ferramentas MCP para assinaturas: listar quem assina o quê, exportar o CSV, ver uma assinatura, cortesias, descontos, extensões e cancelamentos, com confirmação; e, para qualquer membro, as próprias assinaturas e compras, com cancelar, pausar, retomar, reativar e mudar de plano.

As assinaturas da comunidade, como em [Membros › Assinaturas](/pagamentos/gestao-de-assinaturas): quem assina, quanto paga, quem está em atraso, e as ações da equipe sobre cada assinatura, sempre com a sua confirmação. E o lado de quem assina: qualquer membro vê as próprias assinaturas e compras, cuida da própria assinatura e muda de plano pela conversa.

Cada ferramenta traz um selo: <span class="tool-kind tool-kind-read">Só consulta</span> não muda nada, <span class="tool-kind tool-kind-write">Altera</span> cria ou muda algo na hora, e <span class="tool-kind tool-kind-confirm">Pede confirmação</span> só age depois do seu sim a um resumo. Ver [Dinheiro e confirmação](/mcp/dinheiro-e-confirmacao).

## Em resumo

| Ferramenta | O que faz | Papel mínimo | Tipo |
|---|---|---|---|
| [`list_subscriptions`](#list-subscriptions) | Assinaturas com status, valor e próxima cobrança | Administrador ou financeiro | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`cancel_subscription`](#cancel-subscription) | Cancela a assinatura de um membro, com confirmação | Administrador ou financeiro | <span class="tool-kind tool-kind-confirm">Pede confirmação</span> |
| [`get_subscription`](#get-subscription) | Uma assinatura, com cobranças e próxima cobrança | Administrador ou financeiro | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`create_manual_subscription`](#create-manual-subscription) | Cortesia ou cobrança futura, sem checkout | Administrador ou financeiro | <span class="tool-kind tool-kind-confirm">Pede confirmação</span> |
| [`update_subscription`](#update-subscription) | Desconto, estender, adicionais, reativar, link de pagamento | Administrador ou financeiro | <span class="tool-kind tool-kind-confirm">Pede confirmação</span> |
| [`export_subscriptions_csv`](#export-subscriptions-csv) | As assinaturas em CSV, com os mesmos filtros | Administrador ou financeiro | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`list_my_subscriptions`](#list-my-subscriptions) | As suas assinaturas | Qualquer | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`list_my_purchases`](#list-my-purchases) | As suas compras avulsas | Qualquer | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`manage_my_subscription`](#manage-my-subscription) | Cancela, pausa, retoma ou reativa a sua assinatura | Qualquer | <span class="tool-kind tool-kind-confirm">Pede confirmação</span> |
| [`quote_plan_change`](#quote-plan-change) | Quanto custa e o que muda ao passar para outro plano | Qualquer, na própria assinatura | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`change_my_plan`](#change-my-plan) | Muda o seu plano, agora ou no fim do período | Qualquer, na própria assinatura | <span class="tool-kind tool-kind-confirm">Pede confirmação</span> |
| [`get_scheduled_plan_change`](#get-scheduled-plan-change) | A mudança de plano agendada | Qualquer | <span class="tool-kind tool-kind-read">Só consulta</span> |
| [`cancel_scheduled_plan_change`](#cancel-scheduled-plan-change) | Desfaz a mudança agendada | Qualquer, na própria assinatura | <span class="tool-kind tool-kind-confirm">Pede confirmação</span> |

## `list_subscriptions`

<span class="tool-kind tool-kind-read">Só consulta</span>

**Listar assinaturas.** As assinaturas, como em [Membros › Assinaturas](/pagamentos/gestao-de-assinaturas). *Papel mínimo: administrador ou financeiro.*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `status` | `ACTIVE`, `TRIALING`, `PAST_DUE`, `PAUSED`, `CANCELING`, `CANCELED`, `EXPIRED`, `COMPLIMENTARY` | Não | Só um status |
| `plan_id` | id | Não | Só um plano |
| `option_id` | id | Não | Só uma opção de cobrança |
| `from`, `to` | data ISO 8601 | Não | Data de início da assinatura |
| `search` | texto | Não | Nome ou e-mail do membro |
| `page`, `limit` | número | Não | Paginação |

**Devolve:** cada assinatura com id (que `cancel_subscription` pede), membro, plano, opção, status, valor, desconto, adicionais, forma de pagamento e próxima cobrança.

**Peça assim:** *"Quem está com a assinatura em atraso?"* · *"Quantos assinantes o plano Growth tem?"*

## `cancel_subscription`

<span class="tool-kind tool-kind-confirm">Pede confirmação</span>

**Cancelar assinatura de um membro.** Cancela a assinatura de um membro, no fim do período pago (o padrão) ou agora. *Papel mínimo: administrador ou financeiro.*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `subscription_id` | id | Sim | De `list_subscriptions` |
| `immediate` | sim ou não | Não | Padrão: não (cancela no fim do período pago) |
| `reason` | texto, até 500 | Não | Fica na linha do tempo da assinatura |

**O resumo:** a ação (*Cancelar no fim do período pago* ou *Cancelar a assinatura agora*), o membro, o plano, a opção, o status, o valor e o fim do período.

**Peça assim:** *"Cancele a assinatura da Ana Souza no fim do período, motivo: pediu por e-mail."*

**Notas:** a ação aparece na linha do tempo da assinatura, em [Gestão de assinaturas](/pagamentos/gestao-de-assinaturas), como feita por você. Nada já pago é estornado.

## `get_subscription`

<span class="tool-kind tool-kind-read">Só consulta</span>

**Ver assinatura.** Uma assinatura com membro, plano, valor, adicionais, cobranças e próxima cobrança. *Papel mínimo: financeiro.*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `subscription` | id ou link (`/billing?subscription=…`) | Sim | |

**Peça assim:** *"Mostre a assinatura da Ana: quanto paga e quando é a próxima cobrança."*

## `create_manual_subscription`

<span class="tool-kind tool-kind-confirm">Pede confirmação</span>

**Criar assinatura manual.** Dá uma assinatura a um membro sem passar pelo checkout: cortesia ou cobrança a partir de uma data. *Papel mínimo: proprietário, administrador ou financeiro.*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `member` | id de perfil | Sim | De `list_members` |
| `option_id` | id | Sim | A opção de cobrança, de `list_products` |
| `mode` | `COMPLIMENTARY`, `FUTURE_CHARGE` | Sim | Cortesia, sem cobrança, ou cobrança futura |
| `complimentary_until` | data ISO 8601 | Não | O fim da cortesia; vazio, sem fim |
| `charge_starts_at` | data ISO 8601 | Não | Com `FUTURE_CHARGE` |
| `payment_method` | `PIX`, `BOLETO`, `CREDIT_CARD` | Não | Com `FUTURE_CHARGE` |
| `note` | texto | Não | Fica na linha do tempo |

**Peça assim:** *"Dê ao palestrante Bruno o plano Growth de cortesia até 31/12."*

**Notas:** fica na auditoria de assinaturas. Ver [Gestão de assinaturas](/pagamentos/gestao-de-assinaturas).

## `update_subscription`

<span class="tool-kind tool-kind-confirm">Pede confirmação</span>

**Mudar uma assinatura.** As ações da equipe numa assinatura. *Papel mínimo: proprietário, administrador ou financeiro.*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `subscription` | id ou link | Sim | |
| `action` | `discount`, `remove_discount`, `extend`, `add_add_on`, `remove_add_on`, `reactivate`, `send_payment_link` | Sim | |
| `percent` | número | Não | Para `discount` |
| `until` | data ISO 8601 | Não | O fim do desconto, ou até quando estender |
| `days` | número, de 1 a 3.650 | Não | Para `extend` |
| `add_on_id` | id | Não | O adicional (para incluir) ou a assinatura do adicional (para remover) |

**Peça assim:** *"Dê 20% de desconto na assinatura da Ana até o fim do ano."* · *"Mande para o Bruno o link de pagamento."*

**Notas:** todas as ações pedem o seu sim e ficam na auditoria. Incluir um adicional ou estender não cobra agora. Para cancelar, use `cancel_subscription`.

## `export_subscriptions_csv`

<span class="tool-kind tool-kind-read">Só consulta</span>

**Exportar assinaturas (CSV).** O mesmo arquivo do botão **Exportar CSV** de **Membros › Assinaturas**. *Papel mínimo: administrador ou financeiro.*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `status` | um dos status | Não | |
| `plan_id`, `option_id` | id | Não | |
| `from`, `to` | data ISO 8601 | Não | Data de início da assinatura |

**Devolve:** quantas linhas e o conteúdo do CSV. Um arquivo muito grande vem cortado, com o aviso `truncated`; use os filtros.

**Peça assim:** *"Exporte as assinaturas ativas do Growth para eu mandar ao financeiro."*

## `list_my_subscriptions`

<span class="tool-kind tool-kind-read">Só consulta</span>

**Minhas assinaturas.** As suas próprias assinaturas na comunidade: plano, opção, status, valor e próxima cobrança. *Papel mínimo: qualquer.*

Parâmetros: nenhum.

**Peça assim:** *"Quando vence a minha próxima mensalidade?"*

## `list_my_purchases`

<span class="tool-kind tool-kind-read">Só consulta</span>

**Minhas compras.** As suas compras avulsas na comunidade (ingressos, cursos, produtos) e o status de cada uma. *Papel mínimo: qualquer.*

Parâmetros: nenhum.

## `manage_my_subscription`

<span class="tool-kind tool-kind-confirm">Pede confirmação</span>

**Gerenciar minha assinatura.** Cancela, pausa, retoma ou reativa a sua própria assinatura, como no [Faturamento](/pagamentos/faturamento-do-membro). *Papel mínimo: qualquer, na própria assinatura.*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `subscription_id` | id | Sim | De `list_my_subscriptions` |
| `action` | `cancel`, `pause`, `resume`, `reactivate` | Sim | Reativar só antes de o período acabar |
| `immediately` | sim ou não | Não | Só em `cancel`: encerra agora em vez de no fim do período |
| `reason` | texto, até 500 | Não | Só em `cancel` |

**Devolve:** na primeira chamada, a opção, o status, o valor e o que vai acontecer, e o código de confirmação.

**Peça assim:** *"Cancele a minha assinatura no fim do período."*

**Notas:** muda o que você paga, por isso pede o seu sim. Ver [Cancelamento](/pagamentos/faturamento-do-membro). Para passar para outro plano ou outra opção de cobrança, use [`quote_plan_change`](#quote-plan-change) e [`change_my_plan`](#change-my-plan).

## Mudar o seu plano

As quatro ferramentas abaixo fazem pela conversa o que **Faturamento › Mudar de plano** faz na tela, com as mesmas regras. Ver [Mudar de plano](/pagamentos/faturamento-do-membro#mudar-de-plano). Só quem assina muda o próprio plano: a equipe não tem ferramenta para trocar o plano de um membro.

**O plano de destino** pode ser dito de três jeitos, no parâmetro `target`:

| Jeito | Exemplo |
|---|---|
| O nome do plano e a periodicidade | *"o Growth anual"* (`target: "Growth"`, `billing: "YEARLY"`) |
| O link copiado da página de preços | `…/pricing/growth/anual` |
| O id da opção | quando você já o tem (a equipe acha em `list_plans`) |

Se o plano tem mais de uma opção e o pedido não diz qual, o assistente pergunta, listando as opções.

O prompt **Trocar meu plano** (`change_plan`) conduz a conversa inteira: compara os planos, mostra quanto custa e só troca depois do seu sim.

## `quote_plan_change`

<span class="tool-kind tool-kind-read">Só consulta</span>

**Simular mudança de plano.** O que acontece se você passar para outra opção, sem mudar nada. *Papel mínimo: qualquer, na própria assinatura.*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `target` | id, link da página de preços ou nome do plano | Sim | A opção para onde ir |
| `billing` | `MONTHLY`, `YEARLY`, ou o nome da opção | Não | Qual opção do plano, quando ele tem mais de uma |
| `subscription_id` | id | Não | De `list_my_subscriptions`. Padrão: a sua assinatura de plano nesta comunidade |
| `immediate` | sim ou não | Não | Só para uma opção mais cara. Padrão: sim (vale agora); não deixa para o fim do período |

**Devolve:** se a mudança vale agora ou fica agendada (e por quê), quanto é cobrado agora e em até quantas parcelas, a próxima cobrança e o total, o que acontece com cada extensão, o contrato, se o cupom deixa de valer e se substitui uma mudança já agendada.

**Peça assim:** *"Quanto custa passar para o Growth anual?"*

## `change_my_plan`

<span class="tool-kind tool-kind-confirm">Pede confirmação</span>

**Mudar meu plano.** Passa a sua assinatura para outra opção. Uma opção mais cara, na mesma periodicidade, vale agora e cobra na hora a diferença proporcional no seu **cartão padrão**; uma mais barata, de mesmo valor, de outra periodicidade ou que deixaria uma extensão de fora fica para o fim do período. *Papel mínimo: qualquer, na própria assinatura.*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `target`, `billing`, `subscription_id`, `immediate` | | | Os mesmos de `quote_plan_change` |
| `installments` | número, de 1 a 12 | Não | Parcelas da cobrança de agora, até o máximo que a simulação mostrou. Padrão: 1 |

**O resumo:** é a simulação: o valor agora e o cartão, quando a mudança vale, a próxima cobrança, as extensões, o contrato e o cupom.

**Peça assim:** *"Muda meu plano para o Growth mensal."*

**Notas:** mexe em dinheiro, por isso pede o seu sim. Sem cartão salvo, uma mudança que vale agora é recusada; cadastre um no [Faturamento](/pagamentos/faturamento-do-membro). Se o cartão é recusado, nada muda e nada é cobrado.

## `get_scheduled_plan_change`

<span class="tool-kind tool-kind-read">Só consulta</span>

**Ver mudança agendada.** A mudança de plano que espera o fim do período: de qual opção para qual, o tipo e a data. *Papel mínimo: qualquer, na própria assinatura; proprietário e administrador também leem a de um membro.*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `subscription_id` | id | Não | Padrão: a sua assinatura de plano |

**Peça assim:** *"Tenho troca agendada?"*

## `cancel_scheduled_plan_change`

<span class="tool-kind tool-kind-confirm">Pede confirmação</span>

**Desfazer mudança agendada.** Cancela a mudança de plano agendada; a assinatura renova na opção atual. *Papel mínimo: qualquer, só na própria assinatura.*

| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `subscription_id` | id | Não | Padrão: a sua assinatura de plano |

**Peça assim:** *"Desfaz a troca."*

**Notas:** recusada quando o PIX ou o boleto da renovação já foi gerado no preço do plano novo; a troca vale quando ele for pago.

## Relacionados

- [Ferramentas](/mcp/ferramentas)
- [Receitas](/mcp/receitas)
- [Dinheiro e confirmação](/mcp/dinheiro-e-confirmacao)