# 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 changing plans, adding an add-on and paying an overdue renewal; a company admin does the same on the company's subscription. 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. A [company](/membros/empresas#the-company-subscribes-and-pays) admin uses the same tools on the company's subscription (with `company_id` in the lists). Through the assistant, a new payment goes by PIX or boleto (a plan change can also use the card already saved); a new card, only in the app. Each tool carries a badge: Read-only changes nothing, Changes creates or changes something right away, and Asks to confirm 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 | Read-only | | [`cancel_subscription`](#cancel-subscription) | Cancels a member's subscription, with confirmation | Admin or finance | Asks to confirm | | [`get_subscription`](#get-subscription) | One subscription, with charges and next charge | Admin or finance | Read-only | | [`create_manual_subscription`](#create-manual-subscription) | Complimentary or future charge, without checkout | Admin or finance | Asks to confirm | | [`update_subscription`](#update-subscription) | Discount, extend, add-ons, reactivate, payment link | Admin or finance | Asks to confirm | | [`export_subscriptions_csv`](#export-subscriptions-csv) | The subscriptions as CSV, with the same filters | Admin or finance | Read-only | | [`list_my_subscriptions`](#list-my-subscriptions) | Your subscriptions | Any | Read-only | | [`get_my_subscription`](#get-my-subscription) | One of your subscriptions, with since when it is past due and the history | Any | Read-only | | [`list_my_purchases`](#list-my-purchases) | Your one-time purchases | Any | Read-only | | [`manage_my_subscription`](#manage-my-subscription) | Cancels, pauses, resumes or reactivates your subscription | Any | Asks to confirm | | [`quote_plan_change`](#quote-plan-change) | How much it costs and what changes when moving to another plan, with add-ons | Any, on your own subscription | Read-only | | [`change_my_plan`](#change-my-plan) | Changes your plan, with add-ons, now or at the end of the period | Any, on your own subscription | Asks to confirm | | [`get_scheduled_plan_change`](#get-scheduled-plan-change) | The scheduled plan change | Any | Read-only | | [`cancel_scheduled_plan_change`](#cancel-scheduled-plan-change) | Undoes the scheduled change | Any, on your own subscription | Asks to confirm | | [`list_my_subscription_charges`](#list-my-subscription-charges) | The charges of your subscription | Any | Read-only | | [`quote_my_add_on`](#quote-my-add-on) | How much adding an add-on to your subscription costs | Any, on their own subscription | Read-only | | [`add_my_add_on`](#add-my-add-on) | Adds the add-on, by PIX or boleto | Any, on their own subscription | Asks to confirm | | [`pay_my_subscription_now`](#pay-my-subscription-now) | Pays the overdue renewal, by PIX or boleto | Any, on their own subscription | Asks to confirm | ## `list_subscriptions` Read-only **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 and, for a past-due one, `pastDueSince` (since when). **Ask like this:** *"Whose subscription is past due?"* · *"How many subscribers does the Growth plan have?"* ## `cancel_subscription` Asks to confirm **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` Read-only **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 (`/account?tab=billing&subscription=…`; the old `/billing?subscription=…` also works) | Yes | | **Returns:** also `pastDueSince` and, in `events`, going into and out of past due (`PAST_DUE`, `RECOVERED`, `EXPIRED`) with `reason`: `no_card`, `card_expired`, `card_declined`, `retries_exhausted`, `provider`, `paid` or `staff`. See [Past due](/pagamentos/gestao-de-assinaturas#past-due). **Ask like this:** *"Show me Ana's subscription: how much she pays and when the next charge is."* · *"Since when is Bruno's subscription past due, and why?"* ## `create_manual_subscription` Asks to confirm **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` Asks to confirm **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` Read-only **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. Above 2,000 rows, the file does not come back in the conversation: the answer carries `status: "queued"`, `rows` and `email`, and the assistant tells you which address the email with the link (valid for 72 hours) goes to. **Ask like this:** *"Export the active Growth subscriptions so I can send them to finance."* ## `list_my_subscriptions` Read-only **My subscriptions.** Your own subscriptions in the community: plan, option, status, amount and next charge. With `company_id`, the company's (company admin only). *Minimum role: any.* | Parameter | Type | Required | Description | |---|---|---|---| | `company_id` | id | No | Your company (from `get_my_company`), if you are its admin | **Ask like this:** *"When is my next monthly payment due?"* ## `get_my_subscription` Read-only **See my subscription.** One of your subscriptions: product, status, amount, period, add-ons, next charge, the open renewal, `pastDueSince` (since when it is past due) and `events`, the past-due history, newest first, with the reason. A company admin reads the company's the same way. *Minimum role: any.* | Parameter | Type | Required | Description | |---|---|---|---| | `subscription_id` | id | Yes | From `list_my_subscriptions` | **Suggested next step:** past-due subscription → [`pay_my_subscription_now`](#pay-my-subscription-now). **Ask like this:** *"Why is my subscription past due?"* ## `list_my_purchases` Read-only **My purchases.** Your one-time purchases in the community (tickets, courses, products) and the status of each. With `company_id`, the company's (company admin only). *Minimum role: any.* | Parameter | Type | Required | Description | |---|---|---|---| | `company_id` | id | No | Your company, if you are its admin | **Returns:** each purchase with its status and, when it was refunded, `refund_label`: *"Refunded: US$ 97.00 on October 8, 2026 (access kept)."* A refunded purchase where you kept access shows as **Refunded**, even while it stays active. ## `manage_my_subscription` Asks to confirm **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). It also works for the company admin on the company's subscription (as do `quote_plan_change` and `change_my_plan`); with the company closed, resume and reactivate are refused. 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 the **Change plan** page does on screen, with the same rules, including the add-ons in the same change and the same charge. 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` Read-only **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 | | `add_on_ids` | list of ids, up to 20 | No | Add-ons of the new plan to include in the same change (from `list_plans` or `list_storefront_products`). | **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 lines of today's charge (`lines`: the plan difference and one per new add-on, prorated to the same days), the next charge and its total, what happens to each add-on (`addOns`: `KEPT` continues, `ENDS` ends with the change, `JOINS` joins with the change, now or at renewal), the contract, whether the coupon stops applying and whether it replaces a change already scheduled. And `allowedMethods`: the payment methods for the charge now (`CREDIT_CARD`, `PIX`, `BOLETO`), the ones the new option accepts at checkout, each with its total and the card installments; boleto only with more than 4 days to the renewal. If a change is already waiting for its PIX or boleto, the preview carries `pendingChange` with what to pay, and no other change starts. **With no saved card** and something to charge now, the preview carries `needsCard: true` and `finish_in_app`: the link to the app's **Change plan** page, already filled in with the plan, the option and the add-ons, where the person adds the card and confirms. The assistant never receives card details: in that case it offers to pay by PIX or boleto with [`change_my_plan`](#change-my-plan), when the option accepts them, or sends the link. **Ask like this:** *"How much does it cost to move to Growth yearly?"* or *"How much is Growth monthly with the Group mentoring?"* ## `change_my_plan` Asks to confirm **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, or by **PIX** or **boleto**, and then the plan only changes once the payment is confirmed; 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`, `add_on_ids` | | | 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 | | `payment_method` | `CREDIT_CARD`, `PIX` or `BOLETO` | No | How the charge now is paid, one of the `allowedMethods` in the preview. Default: `CREDIT_CARD` (the saved card). | **The summary:** it is the preview: when the change takes effect, the lines of today's charge and the total amount now, with the card or the chosen payment method (with PIX or boleto, *"once the payment is confirmed"*); the next charge; the add-ons that continue, leave or join; the contract and the coupon. On a scheduled change, the checked add-ons join at renewal, with no charge today. **Ask like this:** *"Change my plan to Growth monthly."*, *"Switch my plan to Growth monthly and include the Group mentoring."* or *"Switch my plan to Growth and pay by PIX."* **Notes:** it involves money, which is why it asks for your yes. **With PIX or boleto**, the answer comes with `mode: PENDING_PAYMENT` and what to pay: the PIX copy-and-paste code (and the QR code) or the boleto (link and barcode line), with its expiry, and the notice *"The plan only changes once this payment is confirmed (pay by 11/03, 2:00 PM). Nothing has changed yet."* The plan and the add-ons change once the payment is confirmed; if the subscription changes before that, the amount is refunded; if it expires, nothing changes. **A change waiting for its payment blocks another one**: the assistant refuses with *"A plan change is already waiting for its payment (pay by 11/03, 2:00 PM): pay it with the details below, or let it expire, before starting another one."* and shows the payment. Boleto only with more than 4 days to the renewal. **By card**, the charge always goes on the saved card; without one, the assistant does not issue the confirmation: it offers PIX or sends the link to the change page already filled in, where the card is added. On a plan that renews by PIX or boleto, add-ons only join on a change charged now. Each confirmation carries its own idempotency key (`idempotency_key` in the response): repeating the same confirmation never charges twice and comes back with `replayed: true` and the notice *"This change had already been made (same attempt): nothing was charged or changed again."* While another change charge for the same subscription is in progress (in the app or in another conversation), the change is refused. If the card is declined, nothing changes and nothing is charged. ## `get_scheduled_plan_change` Read-only **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` Asks to confirm **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. ## `list_my_subscription_charges` Read-only **My subscription charges.** The charges of your own subscription, newest first. *Minimum role: any.* | Parameter | Type | Required | Description | |---|---|---|---| | `subscription_id` | id | No | From `list_my_subscriptions`. Without it, your subscription to the community's plan | | `status` | `PENDING`, `PROCESSING`, `COMPLETED`, `ACTIVE`, `FAILED`, `REFUNDED`, `DISPUTED` | No | | | `page` | number | No | | | `limit` | number, up to 100 | No | | **Returns:** date, period, amount, status, when it was paid or failed and why, and the next attempt. **Ask like this:** *"Why did this month's charge fail?"* **Notes:** with a failed charge, the assistant suggests `manage_my_subscription`. ## Add-on and overdue payment ### `quote_my_add_on` Read-only **What an add-on costs.** Simulates adding an [add-on](/monetizacao/adicionais) to your plan subscription, with no effect: the amount per period, the prorated amount until the next charge, how much is paid now and the total of the next charge. The add-on must be one of the plan's, and the plan must be active, with no cancellation scheduled. *Minimum role: any, on their own subscription (or the company's, for its admin).* | Parameter | Type | Required | Description | |---|---|---|---| | `subscription_id` | id | Yes | From `list_my_subscriptions` (with `company_id`, for the company) | | `add_on_id` | id | Yes | The add-on (from `list_storefront_products` or `list_plans`) | **Ask like this:** *"How much would adding parking to my company's plan cost?"* ### `add_my_add_on` Asks to confirm **Add the add-on.** Charges the simulation's prorated amount now, in a separate order; from the next charge on, it comes together with the plan. When there is something to pay, `payment_method` is required (`PIX` or `BOLETO`) and the answer carries the PIX code or the boleto link: the add-on starts once the payment is confirmed. With nothing to pay now, nothing is charged. The summary is the simulation. *Minimum role: any, on their own subscription (or the company's, for its admin).* | Parameter | Type | Required | Description | |---|---|---|---| | `subscription_id` | id | Yes | The plan subscription | | `add_on_id` | id | Yes | The add-on | | `payment_method` | `PIX` or `BOLETO` | When there is something to pay | Card, only in the app | **Ask like this:** *"Add parking to Acme's plan and pay by PIX."* ### `pay_my_subscription_now` Asks to confirm **Pay now.** Pays a **past-due** subscription, like [Pay now](/pagamentos/pagar-agora): a new charge for the open period, with the add-ons together, by PIX or boleto. The answer carries the PIX code or the boleto link for whoever pays; once paid, the subscription is up to date again. The open PIX or boleto of the same renewal is canceled first, so nothing is paid twice. Refused if the subscription is not past due or if the company is closed. *Minimum role: the subscriber, the company admin on the company's subscription, or the owner and the admin on any subscription in the community.* | Parameter | Type | Required | Description | |---|---|---|---| | `subscription_id` | id | Yes | The past-due subscription (from `list_my_subscriptions`; the team, from `list_subscriptions`) | | `payment_method` | `PIX` or `BOLETO` | Yes | Card, only on the app's **Billing** page | **Ask like this:** *"My company's subscription is overdue. Generate a boleto."* ## Related - [Tools](/mcp/ferramentas) - [Recipes](/mcp/receitas) - [Money and confirmation](/mcp/dinheiro-e-confirmacao)