# Strumenti · Abbonamenti

> Strumenti MCP per gli abbonamenti: elencare chi è abbonato a cosa, esportare il CSV, vedere un abbonamento, omaggi, sconti, estensioni e annullamenti, con conferma; e, per qualsiasi membro, i propri abbonamenti e acquisti, con annullare, mettere in pausa, riprendere, riattivare e cambiare piano.

Gli abbonamenti della community, come in [Membri › Abbonamenti](/pagamentos/gestao-de-assinaturas): chi è abbonato, quanto paga, chi è in ritardo, e le azioni dello staff su ogni abbonamento, sempre con la tua conferma. E il lato di chi è abbonato: qualsiasi membro vede i propri abbonamenti e acquisti, gestisce il proprio abbonamento e cambia piano dalla conversazione.

Ogni strumento ha un'etichetta: <span class="tool-kind tool-kind-read">Solo lettura</span> non cambia nulla, <span class="tool-kind tool-kind-write">Modifica</span> crea o cambia qualcosa subito, e <span class="tool-kind tool-kind-confirm">Chiede conferma</span> agisce solo dopo il tuo sì a un riepilogo. Vedi [Denaro e conferma](/mcp/dinheiro-e-confirmacao).

## In sintesi

| Strumento | Cosa fa | Ruolo minimo | Tipo |
|---|---|---|---|
| [`list_subscriptions`](#list-subscriptions) | Abbonamenti con stato, importo e prossimo addebito | Admin o Finanza | <span class="tool-kind tool-kind-read">Solo lettura</span> |
| [`cancel_subscription`](#cancel-subscription) | Annulla l'abbonamento di un membro, con conferma | Admin o Finanza | <span class="tool-kind tool-kind-confirm">Chiede conferma</span> |
| [`get_subscription`](#get-subscription) | Un abbonamento, con addebiti e prossimo addebito | Admin o Finanza | <span class="tool-kind tool-kind-read">Solo lettura</span> |
| [`create_manual_subscription`](#create-manual-subscription) | Omaggio o addebito futuro, senza checkout | Admin o Finanza | <span class="tool-kind tool-kind-confirm">Chiede conferma</span> |
| [`update_subscription`](#update-subscription) | Sconto, estensione, componenti aggiuntivi, riattivazione, link di pagamento | Admin o Finanza | <span class="tool-kind tool-kind-confirm">Chiede conferma</span> |
| [`export_subscriptions_csv`](#export-subscriptions-csv) | Gli abbonamenti in CSV, con gli stessi filtri | Admin o Finanza | <span class="tool-kind tool-kind-read">Solo lettura</span> |
| [`list_my_subscriptions`](#list-my-subscriptions) | I tuoi abbonamenti | Qualsiasi | <span class="tool-kind tool-kind-read">Solo lettura</span> |
| [`list_my_purchases`](#list-my-purchases) | I tuoi acquisti singoli | Qualsiasi | <span class="tool-kind tool-kind-read">Solo lettura</span> |
| [`manage_my_subscription`](#manage-my-subscription) | Annulla, mette in pausa, riprende o riattiva il tuo abbonamento | Qualsiasi | <span class="tool-kind tool-kind-confirm">Chiede conferma</span> |
| [`quote_plan_change`](#quote-plan-change) | Quanto costa e cosa cambia passando a un altro piano | Qualsiasi, sul proprio abbonamento | <span class="tool-kind tool-kind-read">Solo lettura</span> |
| [`change_my_plan`](#change-my-plan) | Cambia il tuo piano, subito o alla fine del periodo | Qualsiasi, sul proprio abbonamento | <span class="tool-kind tool-kind-confirm">Chiede conferma</span> |
| [`get_scheduled_plan_change`](#get-scheduled-plan-change) | Il cambio di piano programmato | Qualsiasi | <span class="tool-kind tool-kind-read">Solo lettura</span> |
| [`cancel_scheduled_plan_change`](#cancel-scheduled-plan-change) | Annulla il cambio programmato | Qualsiasi, sul proprio abbonamento | <span class="tool-kind tool-kind-confirm">Chiede conferma</span> |

## `list_subscriptions`

<span class="tool-kind tool-kind-read">Solo lettura</span>

**Elencare gli abbonamenti.** Gli abbonamenti, come in [Membri › Abbonamenti](/pagamentos/gestao-de-assinaturas). *Ruolo minimo: Admin o Finanza.*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `status` | `ACTIVE`, `TRIALING`, `PAST_DUE`, `PAUSED`, `CANCELING`, `CANCELED`, `EXPIRED`, `COMPLIMENTARY` | No | Un solo stato |
| `plan_id` | id | No | Un solo piano |
| `option_id` | id | No | Una sola opzione di fatturazione |
| `from`, `to` | data ISO 8601 | No | Data di inizio dell'abbonamento |
| `search` | testo | No | Nome o e-mail del membro |
| `page`, `limit` | numero | No | Paginazione |

**Restituisce:** ogni abbonamento con id (che chiede `cancel_subscription`), membro, piano, opzione, stato, importo, sconto, componenti aggiuntivi, metodo di pagamento e prossimo addebito.

**Chiedi così:** *"Chi ha l'abbonamento in ritardo?"* · *"Quanti abbonati ha il piano Growth?"*

## `cancel_subscription`

<span class="tool-kind tool-kind-confirm">Chiede conferma</span>

**Annullare l'abbonamento di un membro.** Annulla l'abbonamento di un membro, alla fine del periodo pagato (predefinito) o subito. *Ruolo minimo: Admin o Finanza.*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `subscription_id` | id | Sì | Da `list_subscriptions` |
| `immediate` | sì o no | No | Predefinito: no (annulla alla fine del periodo pagato) |
| `reason` | testo, fino a 500 | No | Resta nella cronologia dell'abbonamento |

**Il riepilogo:** l'azione (*Cancelar no fim do período pago* o *Cancelar a assinatura agora*), il membro, il piano, l'opzione, lo stato, l'importo e la fine del periodo.

**Chiedi così:** *"Annulla l'abbonamento di Ana Souza alla fine del periodo, motivo: l'ha chiesto via e-mail."*

**Note:** l'azione compare nella cronologia dell'abbonamento, in [Gestione degli abbonamenti](/pagamentos/gestao-de-assinaturas), come fatta da te. Nulla di già pagato viene rimborsato.

## `get_subscription`

<span class="tool-kind tool-kind-read">Solo lettura</span>

**Vedere un abbonamento.** Un abbonamento con membro, piano, importo, componenti aggiuntivi, addebiti e prossimo addebito. *Ruolo minimo: Admin o Finanza.*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `subscription` | id o link (`/billing?subscription=…`) | Sì | |

**Chiedi così:** *"Mostrami l'abbonamento di Ana: quanto paga e quando è il prossimo addebito."*

## `create_manual_subscription`

<span class="tool-kind tool-kind-confirm">Chiede conferma</span>

**Creare un abbonamento manuale.** Dà un abbonamento a un membro senza passare dal checkout: omaggio o addebito a partire da una data. *Ruolo minimo: Admin o Finanza.*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `member` | id di profilo | Sì | Da `list_members` |
| `option_id` | id | Sì | L'opzione di fatturazione, da `list_products` |
| `mode` | `COMPLIMENTARY`, `FUTURE_CHARGE` | Sì | Omaggio, senza addebito, o addebito futuro |
| `complimentary_until` | data ISO 8601 | No | La fine dell'omaggio; vuoto, senza fine |
| `charge_starts_at` | data ISO 8601 | No | Con `FUTURE_CHARGE` |
| `payment_method` | `PIX`, `BOLETO`, `CREDIT_CARD` | No | Con `FUTURE_CHARGE` |
| `note` | testo | No | Resta nella cronologia |

**Chiedi così:** *"Dai al relatore Bruno il piano Growth in omaggio fino al 31/12."*

**Note:** resta nel registro degli abbonamenti. Vedi [Gestione degli abbonamenti](/pagamentos/gestao-de-assinaturas).

## `update_subscription`

<span class="tool-kind tool-kind-confirm">Chiede conferma</span>

**Cambiare un abbonamento.** Le azioni dello staff su un abbonamento. *Ruolo minimo: Admin o Finanza.*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `subscription` | id o link | Sì | |
| `action` | `discount`, `remove_discount`, `extend`, `add_add_on`, `remove_add_on`, `reactivate`, `send_payment_link` | Sì | |
| `percent` | numero | No | Per `discount` |
| `until` | data ISO 8601 | No | La fine dello sconto, o fino a quando estendere |
| `days` | numero, da 1 a 3.650 | No | Per `extend` |
| `add_on_id` | id | No | Il componente aggiuntivo (da includere) o l'abbonamento del componente (da togliere) |

**Chiedi così:** *"Dai il 20% di sconto sull'abbonamento di Ana fino a fine anno."* · *"Manda a Bruno il link di pagamento."*

**Note:** tutte le azioni chiedono il tuo sì e restano nel registro. Includere un componente aggiuntivo o estendere non addebita nulla ora. Per annullare, usa `cancel_subscription`.

## `export_subscriptions_csv`

<span class="tool-kind tool-kind-read">Solo lettura</span>

**Esporta abbonamenti (CSV).** Lo stesso file del pulsante **Esporta CSV** di **Membri › Abbonamenti**. *Ruolo minimo: Admin o Finanza.*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `status` | uno degli stati | No | |
| `plan_id`, `option_id` | id | No | |
| `from`, `to` | data ISO 8601 | No | Data di inizio dell'abbonamento |

**Restituisce:** quante righe e il contenuto del CSV. Un file molto grande arriva troncato, con l'avviso `truncated`; usa i filtri.

**Chiedi così:** *"Esporta gli abbonamenti attivi del Growth, devo mandarli all'amministrazione."*

## `list_my_subscriptions`

<span class="tool-kind tool-kind-read">Solo lettura</span>

**I miei abbonamenti.** I tuoi abbonamenti nella community: piano, opzione, stato, importo e prossimo addebito. *Ruolo minimo: qualsiasi.*

Parametri: nessuno.

**Chiedi così:** *"Quando scade la mia prossima mensilità?"*

## `list_my_purchases`

<span class="tool-kind tool-kind-read">Solo lettura</span>

**I miei acquisti.** I tuoi acquisti singoli nella community (biglietti, corsi, prodotti) e lo stato di ciascuno. *Ruolo minimo: qualsiasi.*

Parametri: nessuno.

## `manage_my_subscription`

<span class="tool-kind tool-kind-confirm">Chiede conferma</span>

**Gestisci il mio abbonamento.** Annulla, mette in pausa, riprende o riattiva il tuo abbonamento, come nella [Fatturazione](/pagamentos/faturamento-do-membro). *Ruolo minimo: qualsiasi, sul proprio abbonamento.*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `subscription_id` | id | Sì | Da `list_my_subscriptions` |
| `action` | `cancel`, `pause`, `resume`, `reactivate` | Sì | Riattivare solo prima che finisca il periodo |
| `immediately` | sì o no | No | Solo con `cancel`: termina subito invece che alla fine del periodo |
| `reason` | testo, fino a 500 | No | Solo con `cancel` |

**Restituisce:** alla prima chiamata, l'opzione, lo stato, l'importo e cosa succederà, più il codice di conferma.

**Chiedi così:** *"Annulla il mio abbonamento alla fine del periodo."*

**Note:** cambia quello che paghi, per questo chiede il tuo sì. Vedi [Annullamento](/pagamentos/faturamento-do-membro). Per passare a un altro piano o a un'altra opzione di fatturazione, usa [`quote_plan_change`](#quote-plan-change) e [`change_my_plan`](#change-my-plan).

## Cambiare il tuo piano

I quattro strumenti qui sotto fanno dalla conversazione ciò che **Fatturazione › Cambia piano** fa nella schermata, con le stesse regole. Vedi [Cambiare piano](/pagamentos/faturamento-do-membro#cambiare-piano). Solo chi è abbonato cambia il proprio piano: lo staff non ha uno strumento per cambiare il piano di un membro.

**Il piano di destinazione** si può indicare in tre modi, nel parametro `target`:

| Modo | Esempio |
|---|---|
| Il nome del piano e la periodicità | *"il Growth annuale"* (`target: "Growth"`, `billing: "YEARLY"`) |
| Il link copiato dalla pagina dei prezzi | `…/pricing/growth/anual` |
| L'id dell'opzione | quando lo hai già (lo staff lo trova con `list_plans`) |

Se il piano ha più di un'opzione e la richiesta non dice quale, l'assistente lo chiede, elencando le opzioni.

Il prompt **Cambia il mio piano** (`change_plan`) guida l'intera conversazione: confronta i piani, mostra quanto costa e cambia solo dopo il tuo sì.

## `quote_plan_change`

<span class="tool-kind tool-kind-read">Solo lettura</span>

**Simulare il cambio di piano.** Cosa succede se passi a un'altra opzione, senza cambiare nulla. *Ruolo minimo: qualsiasi, sul proprio abbonamento.*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `target` | id, link della pagina dei prezzi o nome del piano | Sì | L'opzione a cui passare |
| `billing` | `MONTHLY`, `YEARLY`, o il nome dell'opzione | No | Quale opzione del piano, quando ne ha più di una |
| `subscription_id` | id | No | Da `list_my_subscriptions`. Predefinito: il tuo abbonamento al piano in questa community |
| `immediate` | sì o no | No | Solo per un'opzione più cara. Predefinito: sì (vale da subito); no la rimanda alla fine del periodo |

**Restituisce:** se il cambio vale da subito o viene programmato (e perché), quanto viene addebitato ora e in quante rate al massimo, il prossimo addebito e il totale, cosa succede a ogni estensione, il contratto, se il coupon smette di valere e se sostituisce un cambio già programmato.

**Chiedi così:** *"Quanto costa passare al Growth annuale?"*

## `change_my_plan`

<span class="tool-kind tool-kind-confirm">Chiede conferma</span>

**Cambiare il mio piano.** Passa il tuo abbonamento a un'altra opzione. Un'opzione più cara, con la stessa periodicità, vale da subito e addebita subito la differenza proporzionale sulla tua **carta predefinita**; una più economica, dello stesso prezzo, di un'altra periodicità o che lascerebbe fuori un'estensione viene programmata per la fine del periodo. *Ruolo minimo: qualsiasi, sul proprio abbonamento.*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `target`, `billing`, `subscription_id`, `immediate` | | | Gli stessi di `quote_plan_change` |
| `installments` | numero, da 1 a 12 | No | Rate dell'addebito di ora, fino al massimo indicato dalla simulazione. Predefinito: 1 |

**Il riepilogo:** è la simulazione: l'importo ora e la carta, quando vale il cambio, il prossimo addebito, le estensioni, il contratto e il coupon.

**Chiedi così:** *"Cambia il mio piano al Growth mensile."*

**Note:** tocca il denaro, per questo chiede il tuo sì. Senza carta salvata, un cambio che vale da subito viene rifiutato; aggiungine una nella [Fatturazione](/pagamentos/faturamento-do-membro). Se la carta viene rifiutata, non cambia nulla e non viene addebitato nulla.

## `get_scheduled_plan_change`

<span class="tool-kind tool-kind-read">Solo lettura</span>

**Vedere il cambio programmato.** Il cambio di piano che aspetta la fine del periodo: da quale opzione a quale, il tipo e la data. *Ruolo minimo: qualsiasi, sul proprio abbonamento; proprietario e admin leggono anche quello di un membro.*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `subscription_id` | id | No | Predefinito: il tuo abbonamento al piano |

**Chiedi così:** *"Ho un cambio programmato?"*

## `cancel_scheduled_plan_change`

<span class="tool-kind tool-kind-confirm">Chiede conferma</span>

**Annullare il cambio programmato.** Annulla il cambio di piano programmato; l'abbonamento si rinnova sull'opzione attuale. *Ruolo minimo: qualsiasi, solo sul proprio abbonamento.*

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `subscription_id` | id | No | Predefinito: il tuo abbonamento al piano |

**Chiedi così:** *"Annulla il cambio."*

**Note:** rifiutato quando il PIX o il boleto del rinnovo è già stato emesso al prezzo del nuovo piano; il cambio vale quando viene pagato.

## Correlati

- [Strumenti](/mcp/ferramentas)
- [Ricette](/mcp/receitas)
- [Denaro e conferma](/mcp/dinheiro-e-confirmacao)