# Tools · Subscriptions

> MCP tools for subscriptions: listing who subscribes to what, exporting the CSV, viewing a subscription, complimentary access, discounts, extensions and cancellations, with confirmation; and, for any member, their own subscriptions and purchases, with cancel, pause, resume, reactivate and changing plans.

The community's subscriptions, as in [Members › Subscriptions](/pagamentos/gestao-de-assinaturas): who subscribes, how much they pay, who is past due, and the team's actions on each subscription, always with your confirmation. And the subscriber's side: any member sees their own subscriptions and purchases, manages their own subscription and changes plans through the conversation.

Each tool carries a badge: <span class="tool-kind tool-kind-read">Read-only</span> changes nothing, <span class="tool-kind tool-kind-write">Changes</span> creates or changes something right away, and <span class="tool-kind tool-kind-confirm">Asks to confirm</span> only acts after your yes to a summary. See [Money and confirmation](/mcp/dinheiro-e-confirmacao).

## In short

| Tool | What it does | Minimum role | Type |
|---|---|---|---|
| [`list_subscriptions`](#list-subscriptions) | Subscriptions with status, amount and next charge | Admin or finance | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`cancel_subscription`](#cancel-subscription) | Cancels a member's subscription, with confirmation | Admin or finance | <span class="tool-kind tool-kind-confirm">Asks to confirm</span> |
| [`get_subscription`](#get-subscription) | One subscription, with charges and next charge | Admin or finance | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`create_manual_subscription`](#create-manual-subscription) | Complimentary or future charge, without checkout | Admin or finance | <span class="tool-kind tool-kind-confirm">Asks to confirm</span> |
| [`update_subscription`](#update-subscription) | Discount, extend, add-ons, reactivate, payment link | Admin or finance | <span class="tool-kind tool-kind-confirm">Asks to confirm</span> |
| [`export_subscriptions_csv`](#export-subscriptions-csv) | The subscriptions as CSV, with the same filters | Admin or finance | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`list_my_subscriptions`](#list-my-subscriptions) | Your subscriptions | Any | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`list_my_purchases`](#list-my-purchases) | Your one-time purchases | Any | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`manage_my_subscription`](#manage-my-subscription) | Cancels, pauses, resumes or reactivates your subscription | Any | <span class="tool-kind tool-kind-confirm">Asks to confirm</span> |
| [`quote_plan_change`](#quote-plan-change) | How much it costs and what changes when moving to another plan | Any, on your own subscription | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`change_my_plan`](#change-my-plan) | Changes your plan, now or at the end of the period | Any, on your own subscription | <span class="tool-kind tool-kind-confirm">Asks to confirm</span> |
| [`get_scheduled_plan_change`](#get-scheduled-plan-change) | The scheduled plan change | Any | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`cancel_scheduled_plan_change`](#cancel-scheduled-plan-change) | Undoes the scheduled change | Any, on your own subscription | <span class="tool-kind tool-kind-confirm">Asks to confirm</span> |

## `list_subscriptions`

<span class="tool-kind tool-kind-read">Read-only</span>

**List subscriptions.** The subscriptions, as in [Members › Subscriptions](/pagamentos/gestao-de-assinaturas). *Minimum role: admin or finance.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `status` | `ACTIVE`, `TRIALING`, `PAST_DUE`, `PAUSED`, `CANCELING`, `CANCELED`, `EXPIRED`, `COMPLIMENTARY` | No | Only one status |
| `plan_id` | id | No | Only one plan |
| `option_id` | id | No | Only one billing option |
| `from`, `to` | ISO 8601 date | No | The subscription's start date |
| `search` | text | No | The member's name or email |
| `page`, `limit` | number | No | Pagination |

**Returns:** each subscription with id (which `cancel_subscription` needs), member, plan, option, status, amount, discount, add-ons, payment method and next charge.

**Ask like this:** *"Whose subscription is past due?"* · *"How many subscribers does the Growth plan have?"*

## `cancel_subscription`

<span class="tool-kind tool-kind-confirm">Asks to confirm</span>

**Cancel a member's subscription.** Cancels a member's subscription, at the end of the paid period (the default) or now. *Minimum role: admin or finance.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `subscription_id` | id | Yes | From `list_subscriptions` |
| `immediate` | yes or no | No | Default: no (cancels at the end of the paid period) |
| `reason` | text, up to 500 | No | Recorded on the subscription's timeline |

**The summary:** the action (*Cancel at the end of the paid period* or *Cancel the subscription now*), the member, the plan, the option, the status, the amount and the end of the period.

**Ask like this:** *"Cancel Ana Souza's subscription at the end of the period, reason: she asked by email."*

**Notes:** the action appears on the subscription's timeline, in [Subscription management](/pagamentos/gestao-de-assinaturas), as done by you. Nothing already paid is refunded.

## `get_subscription`

<span class="tool-kind tool-kind-read">Read-only</span>

**View subscription.** A subscription with member, plan, amount, add-ons, charges and next charge. *Minimum role: finance.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `subscription` | id or link (`/billing?subscription=…`) | Yes | |

**Ask like this:** *"Show me Ana's subscription: how much she pays and when the next charge is."*

## `create_manual_subscription`

<span class="tool-kind tool-kind-confirm">Asks to confirm</span>

**Create manual subscription.** Gives a member a subscription without going through checkout: complimentary, or charging from a date. *Minimum role: owner, admin or finance.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `member` | profile id | Yes | From `list_members` |
| `option_id` | id | Yes | The billing option, from `list_products` |
| `mode` | `COMPLIMENTARY`, `FUTURE_CHARGE` | Yes | Complimentary, with no charge, or a future charge |
| `complimentary_until` | ISO 8601 date | No | When the complimentary access ends; empty, no end |
| `charge_starts_at` | ISO 8601 date | No | With `FUTURE_CHARGE` |
| `payment_method` | `PIX`, `BOLETO`, `CREDIT_CARD` | No | With `FUTURE_CHARGE` |
| `note` | text | No | Stays on the timeline |

**Ask like this:** *"Give the speaker Bruno the Growth plan as complimentary until 12/31."*

**Notes:** it goes into the subscriptions audit trail. See [Subscription management](/pagamentos/gestao-de-assinaturas).

## `update_subscription`

<span class="tool-kind tool-kind-confirm">Asks to confirm</span>

**Change a subscription.** The team's actions on a subscription. *Minimum role: owner, admin or finance.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `subscription` | id or link | Yes | |
| `action` | `discount`, `remove_discount`, `extend`, `add_add_on`, `remove_add_on`, `reactivate`, `send_payment_link` | Yes | Discount, remove discount, extend, add add-on, remove add-on, reactivate, send payment link |
| `percent` | number | No | For `discount` |
| `until` | ISO 8601 date | No | When the discount ends, or until when to extend |
| `days` | number, 1 to 3,650 | No | For `extend` |
| `add_on_id` | id | No | The add-on (to include) or the add-on's subscription (to remove) |

**Ask like this:** *"Give Ana's subscription 20% off until the end of the year."* · *"Send Bruno the payment link."*

**Notes:** every action asks for your yes and goes into the audit trail. Including an add-on or extending doesn't charge now. To cancel, use `cancel_subscription`.

## `export_subscriptions_csv`

<span class="tool-kind tool-kind-read">Read-only</span>

**Export subscriptions (CSV).** The same file as the **Export CSV** button in **Members › Subscriptions**. *Minimum role: admin or finance.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `status` | one of the statuses | No | |
| `plan_id`, `option_id` | id | No | |
| `from`, `to` | ISO 8601 date | No | The subscription's start date |

**Returns:** how many rows and the CSV content. A very large file comes back cut off, with the `truncated` warning; use the filters.

**Ask like this:** *"Export the active Growth subscriptions so I can send them to finance."*

## `list_my_subscriptions`

<span class="tool-kind tool-kind-read">Read-only</span>

**My subscriptions.** Your own subscriptions in the community: plan, option, status, amount and next charge. *Minimum role: any.*

Parameters: none.

**Ask like this:** *"When is my next monthly payment due?"*

## `list_my_purchases`

<span class="tool-kind tool-kind-read">Read-only</span>

**My purchases.** Your one-time purchases in the community (tickets, courses, products) and the status of each. *Minimum role: any.*

Parameters: none.

## `manage_my_subscription`

<span class="tool-kind tool-kind-confirm">Asks to confirm</span>

**Manage my subscription.** Cancels, pauses, resumes or reactivates your own subscription, as in [Billing](/pagamentos/faturamento-do-membro). *Minimum role: any, on your own subscription.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `subscription_id` | id | Yes | From `list_my_subscriptions` |
| `action` | `cancel`, `pause`, `resume`, `reactivate` | Yes | Reactivate only before the period ends |
| `immediately` | yes or no | No | Only with `cancel`: ends it now instead of at the end of the period |
| `reason` | text, up to 500 | No | Only with `cancel` |

**Returns:** on the first call, the option, the status, the amount and what is going to happen, and the confirmation code.

**Ask like this:** *"Cancel my subscription at the end of the period."*

**Notes:** it changes what you pay, which is why it asks for your yes. See [Cancellation](/pagamentos/faturamento-do-membro). To move to another plan or billing option, use [`quote_plan_change`](#quote-plan-change) and [`change_my_plan`](#change-my-plan).

## Change your plan

The four tools below do through the conversation what **Billing › Change plan** does on screen, with the same rules. See [Change plan](/pagamentos/faturamento-do-membro#change-plan). Only the subscriber changes their own plan: the team has no tool to change a member's plan.

**The target plan** can be given in three ways, in the `target` parameter:

| Way | Example |
|---|---|
| The plan name and the billing interval | *"Growth yearly"* (`target: "Growth"`, `billing: "YEARLY"`) |
| The link copied from the pricing page | `…/pricing/growth/anual` |
| The option id | when you already have it (the team finds it with `list_plans`) |

If the plan has more than one option and the request doesn't say which, the assistant asks, listing the options.

The **Change my plan** prompt (`change_plan`) guides the whole conversation: it compares the plans, shows how much it costs and only switches after your yes.

## `quote_plan_change`

<span class="tool-kind tool-kind-read">Read-only</span>

**Preview a plan change.** What happens if you move to another option, without changing anything. *Minimum role: any, on your own subscription.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `target` | id, pricing page link or plan name | Yes | The option to move to |
| `billing` | `MONTHLY`, `YEARLY`, or the option name | No | Which option of the plan, when it has more than one |
| `subscription_id` | id | No | From `list_my_subscriptions`. Default: your plan subscription in this community |
| `immediate` | yes or no | No | Only for a more expensive option. Default: yes (takes effect now); no leaves it for the end of the period |

**Returns:** whether the change takes effect now or is scheduled (and why), how much is charged now and in up to how many installments, the next charge and its total, what happens to each extension, the contract, whether the coupon stops applying and whether it replaces a change already scheduled.

**Ask like this:** *"How much does it cost to move to Growth yearly?"*

## `change_my_plan`

<span class="tool-kind tool-kind-confirm">Asks to confirm</span>

**Change my plan.** Moves your subscription to another option. A more expensive option, with the same billing interval, takes effect now and charges the prorated difference to your **default card** right away; a cheaper one, the same price, another billing interval, or one that would leave an extension out is scheduled for the end of the period. *Minimum role: any, on your own subscription.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `target`, `billing`, `subscription_id`, `immediate` | | | The same as `quote_plan_change` |
| `installments` | number, 1 to 12 | No | Installments for the charge now, up to the maximum the preview showed. Default: 1 |

**The summary:** it is the preview: the amount now and the card, when the change takes effect, the next charge, the extensions, the contract and the coupon.

**Ask like this:** *"Change my plan to Growth monthly."*

**Notes:** it involves money, which is why it asks for your yes. With no saved card, a change that takes effect now is refused; add one in [Billing](/pagamentos/faturamento-do-membro). If the card is declined, nothing changes and nothing is charged.

## `get_scheduled_plan_change`

<span class="tool-kind tool-kind-read">Read-only</span>

**View scheduled change.** The plan change waiting for the end of the period: from which option to which, the type and the date. *Minimum role: any, on your own subscription; owner and admin can also read a member's.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `subscription_id` | id | No | Default: your plan subscription |

**Ask like this:** *"Do I have a plan change scheduled?"*

## `cancel_scheduled_plan_change`

<span class="tool-kind tool-kind-confirm">Asks to confirm</span>

**Undo scheduled change.** Cancels the scheduled plan change; the subscription renews on the current option. *Minimum role: any, only on your own subscription.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `subscription_id` | id | No | Default: your plan subscription |

**Ask like this:** *"Undo the switch."*

**Notes:** refused once the renewal PIX or boleto has been generated at the new plan's price; the change applies when it is paid.

## Related

- [Tools](/mcp/ferramentas)
- [Recipes](/mcp/receitas)
- [Money and confirmation](/mcp/dinheiro-e-confirmacao)