# Tools · Finance

> MCP tools for the community's money: sales summary, customers, sales one by one, statement, balance, payouts and the fee simulation; refunding a buyer and requesting or canceling payouts, with confirmation.

The community's cash: how much it sold, who pays, each sale, the statement, the available balance, payouts, and how much is left from a sale. Refunding a buyer and requesting or canceling a payout ask for your yes, with a summary. In amounts, only the platform fee shows up.

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 |
|---|---|---|---|
| [`get_sales_summary`](#get-sales-summary) | Revenue (gross, refunds, chargebacks and net) by currency, monthly series, revenue by product and subscribers | Admin or finance | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`list_customers`](#list-customers) | Who pays and how much they've paid | Admin or finance | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`list_purchases`](#list-purchases) | The sales, with the buyer, the amount, the status and the refund | Admin or finance | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`get_purchase`](#get-purchase) | One sale, with all its refunds and its timeline | Admin or finance | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`refund_purchase`](#refund-purchase) | Refunds a sale, choosing whether access continues, with confirmation | Admin or finance | <span class="tool-kind tool-kind-confirm">Asks to confirm</span> |
| [`list_abandoned_carts`](#list-abandoned-carts) | Who opened the checkout and did not buy, and who came back and paid | Admin or finance | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`list_ledger_entries`](#list-ledger-entries) | Statement entries | Admin or finance | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`get_balance`](#get-balance) | Balance per currency: available, pending (with the release dates), held, owed and how much you can withdraw | Admin or finance | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`list_payouts`](#list-payouts) | Payouts and their status | Admin or finance | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`simulate_fee`](#simulate-fee) | How much the community receives from a sale | Admin | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`request_payout`](#request-payout) | Requests a payout, with confirmation | Admin | <span class="tool-kind tool-kind-confirm">Asks to confirm</span> |
| [`cancel_payout`](#cancel-payout) | Cancels a pending payout, with confirmation | Admin | <span class="tool-kind tool-kind-confirm">Asks to confirm</span> |
| [`get_community_fees`](#get-community-fees) | The platform fee, minimum payout and methods | Admin or finance | <span class="tool-kind tool-kind-read">Read-only</span> |

## `get_sales_summary`

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

**Sales summary.** Revenue and subscribers for a period, with the same numbers as the [Monetization Revenue card](/monetizacao/visao-geral#revenue-for-the-period). *Minimum role: admin or finance.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `period` | `7d`, `30d`, `90d`, `1y`, `custom` | No | The period |
| `start_date` | ISO 8601 date | No | With `period: custom` |
| `end_date` | ISO 8601 date | No | With `period: custom` |
| `currency` | `BRL`, `USD`, `EUR`, `GBP`, `MXN`, `ARS` | No | One currency. Without it, the currency with the most sales |

**Returns:** from the statement, by payment date, the **gross** (what buyers paid) and the number of sales, **refunds** and **chargebacks** separately (amount and count; a chargeback includes the chargeback fee) and the **net** (gross minus refunds and chargebacks, before the platform fee). Also the month-by-month series, revenue by type and by product, the average order value, and active, past-due and canceled subscribers. Zero-value sales and deleted purchases don't count. One currency per answer: `currency` says which, and `currencies` lists the currencies the community has sold in, so the assistant can ask again for another one. For amounts, only the platform fee appears.

**Ask like this:** *"Chart the revenue for the last 12 months."* · *"Which product sold the most this quarter?"* · *"How much did I sell this month, how much did I refund and what's left?"* · *"And the sales in reais?"*

## `list_customers`

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

**Who pays and how much they've paid.** Paying customers and the total each one has paid. *Minimum role: admin or finance.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `page`, `limit` | number | No | Pagination |

**Returns:** the customers, with name, email and total paid.

**Ask like this:** *"Who are the 10 customers who've paid the most?"*

## `list_purchases`

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

**List sales.** The community's purchases (one-time products, plans and add-ons), newest first, as in the [Sales](/pagamentos/vendas) tab. *Minimum role: admin or finance.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `situation` | list of `PAID`, `PROCESSING`, `AWAITING_BALANCE`, `REFUNDED`, `PARTIALLY_REFUNDED`, `SETTLED_OUTSIDE`, `IN_REVIEW`, `DECLINED`, `DISPUTED`, `AWAITING_PAYMENT`, `FAILED` | No | One or more statuses, as the **Status** filter of the Sales tab |
| `status` | `COMPLETED`, `REFUNDED`, `DISPUTED`, `PENDING`, `PROCESSING`, `FAILED`, `CANCELED` | No | Only one status |
| `product_id` | id | No | From `list_products` |
| `payment_method` | `CREDIT_CARD`, `PIX`, `BOLETO`, `FREE`… | No | Only one payment method |
| `refunded` | yes/no | No | `true`: only purchases with some refund |
| `from`, `to` | ISO 8601 date | No | The range of the purchase date |
| `search` | text | No | The buyer's name or email |
| `page`, `limit` | number | No | Pagination |

**Returns:** each sale with its id (which `get_purchase` and `refund_purchase` need), buyer, product, amount, payment method, platform fee, net, what has already been refunded, what can still be, how the refund goes out (through Memberfy on card and PIX; directly by the community on boleto), the last refund and `refund_label`, the sentence that shows a purchase that kept access as **refunded**. When the purchase can't be refunded through Memberfy yet, `refund_blocked` carries the reason and Memberfy's sentence (the purchase has no charge at the provider). See [Purchase with no charge at the provider](/pagamentos/reembolsos-e-contestacoes#purchase-with-no-charge-at-the-provider). Each sale also carries `situation` and `situation_label`, the status with the Sales tab's name (such as **Partially refunded**).

**Ask like this:** *"What sales do we have from Maria?"* · *"Who was refunded this month?"* · *"Which sales were partially refunded this month?"*

## `get_purchase`

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

**View a sale.** One sale with all its refunds, newest first, and its timeline. *Minimum role: admin or finance.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `purchase_id` | id | Yes | From `list_purchases`, or the `purchaseId` of a charge in `get_subscription` |

**Returns:** the sale, with `refund_blocked`, and each refund with its state (done, processing, pending waiting for balance, declined with the reason, or under review by Memberfy, which completes or declines it), the amount, whether access stayed, the platform fee returned and what left the statement. A sale from another community is not found. And `timeline`, the sale's timeline oldest first, one line per event with the date, who did it and what: the payment, the balance release (with future dates), the chargeback reserve, each refund step, access, chargebacks and the e-mails to the buyer. To find the sale by name, use `list_purchases` first.

**Ask like this:** *"Has Maria's refund gone out yet?"* · *"Show me the timeline of Maria's sale."*

The timeline dates come in the community's time zone, with the zone name.

## `refund_purchase`

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

**Refund a sale.** Gives a purchase's money back through Memberfy, like the **Refund** button in the Sales tab, and emails the buyer. *Minimum role: admin or finance.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `purchase_id` | id | Yes | From `list_purchases`, or the `purchaseId` of a charge in `get_subscription` |
| `access` | `KEEP`, `REVOKE` | Yes | `KEEP` keeps access; `REVOKE` removes access and, on a subscription, cancels the subscription right away |
| `amount` | number | No | Default: what is left to refund. On card and PIX, it can be partial, from 0.01 up to what is left. At most 2 decimal places: with more, the first call is refused, never rounded (*Enter the amount with at most 2 decimal places, for example 49.90.*) |
| `reason` | text | No | The reason |
| `settled_outside` | `{ at, note }` | No | Boleto only: the community already returned the money directly to the buyer (date and note) |

**The summary:** the purchase, the buyer, the date, the payment method, what was paid, what has already been refunded, the refund amount, access (keep or revoke) and, on a subscription, that **revoking cancels the subscription now, with no new charges, whatever period is refunded**. The assistant asks first whether access continues. On a partial amount, the summary warns that the refund usually stays *processing* for a few minutes, while it is confirmed, before it is done.

**The result:** Memberfy's message and the refund's state:

| State | Meaning | The assistant suggests |
|---|---|---|
| Done | The money went back to the buyer | — |
| Processing | The refund was requested and is being confirmed; it usually takes a few minutes, and it's common on a partial refund | `get_purchase`, to follow it |
| Waiting for balance | The receiving account has no balance for the community's part: the refund goes out on its own, in order of arrival, the access choice already applies and the buyer gets the email when it goes out | `get_balance` (the reserved amount) and `get_purchase` |
| Declined | The provider declined: it comes back as an error, with the reason, and nothing changes | — |

**Refused before the summary**, with Memberfy's sentence and no confirmation code: nothing left to refund, a pending or disputed purchase, an amount above what is left, and a purchase with `refund_blocked` (no charge at the provider).

**Boleto.** Memberfy doesn't give a paid boleto back. The first call without `settled_outside` comes back with the guidance: the community contacts the buyer and returns the money directly, by PIX or bank transfer. When you say you've already returned it, the assistant calls again with `settled_outside`, which also asks for your yes. Then the amount can be partial, nothing leaves the balance and the platform fee doesn't come back. See [Boleto](/pagamentos/reembolsos-e-contestacoes#boleto-the-community-returns-it-directly).

**Ask like this:** *"Refund Maria's course purchase, keeping her access."* · *"I already returned João's boleto by PIX, US$ 150, record it."*

**Notes:** the confirmation is single-use, and a confirmed refund goes out only once, even if the call is repeated. The **Refund a buyer** prompt (`refund_buyer`) guides the whole conversation. See [Recipes](/mcp/receitas#18-refund-a-buyer).

A purchase paid with points is refunded in full (no `amount`, `ticket_ids` or `settled_outside`), and access goes (`access: REVOKE`); the points go back to the balance, and the answer carries `source: POINTS` and `points_returned`.

## `list_abandoned_carts`

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

**List abandoned carts.** Who opened the checkout of a paid product and did not buy within 60 minutes (`ABANDONED`), and who paid within 7 days after that (`RECOVERED`), most recent first, as in [Sales › Abandoned](/pagamentos/carrinhos-abandonados). *Minimum role: admin or finance.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `product_id` | id | No | From `list_products` |
| `plan_id` | id | No | From `list_plans` |
| `status` | `ABANDONED`, `RECOVERED` | No | Without it, both |
| `from`, `to` | ISO 8601 date | No | The abandonment period |
| `search` | text | No | The member's name or e-mail |
| `page`, `limit` | number | No | Pagination (up to 100 per page) |

**Returns:** each cart with the contact (name, e-mail, phone), the product, the plan, the amount and currency, the payment method of the last attempt, `abandonedAt`, `recoveredAt`, `recoveredAmount` and whether the recovery e-mail went out (`emailSent`, `emailSentAt`). The contact is personal data: the assistant shows it only to whoever asked. Carts are deleted 90 days after the abandonment.

**Suggested next step:** when there are abandoned carts without an e-mail, turn on the recovery e-mail with [`update_notification_settings`](/mcp/ferramentas-comunidade#update-notification-settings).

**Ask like this:** *"Who abandoned the annual plan checkout this week?"* · *"How much did the recovered carts bring in this month?"*

## `list_ledger_entries`

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

**Statement.** The statement entries, newest first. *Minimum role: admin or finance.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `entry_type` | text | No | One entry type: `SALE_GROSS`, `SALE_NET`, `PLATFORM_FEE`, `INSTALLMENT_INTEREST`, `REFUND`, `CHARGEBACK`, `PAYOUT_REQUESTED`… |
| `currency` | `BRL`, `USD`, `EUR`, `GBP`, `MXN`, `ARS` | No | Only the entries in this currency |
| `page`, `limit` | number | No | Pagination |

**Returns:** the entries, with date, type, description, amount, currency and **releases on** (`availableAt`, the date the amount becomes available for payout; empty or in the past, it is already available). On a card sale in installments, each installment is an entry with its own date. The chargeback reserve shows as a pair: the hold, on the sale's release date, and the return, 60 days after payment. See [Balance and statement](/pagamentos/saldo-e-extrato).

**Ask like this:** *"What refunds were there this month?"*

## `get_balance`

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

**Balance.** The community's balance, per currency, and when the pending money is released. *Minimum role: admin or finance.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `currency` | `BRL`, `USD`, `EUR`, `GBP`, `MXN`, `ARS` | No | The currency of the payout quote. Default: `BRL` |

**Returns:** one line per currency the community has a balance in, with **available** (which can be negative), **pending**, with the day each amount is released and the next release, **retained** (the chargeback reserve, 4% of the gross amount for 60 days with every payment method, with the day it comes back) and **owed**, when available went below zero. And, for the currency asked, how much can be paid out: the withdrawable amount, the payout fee, the **maximum** and the **minimum** (US$ 10.00; R$ 10.00 in reais). With refunds waiting for balance, `pending_refunds` says how much is reserved for them, out of payouts.

**It only offers a payout when the withdrawable amount reaches the minimum.** What is pending or retained is never offered for payout: the assistant says how much is pending and when it is released (*"US$ 1,200.00 is still pending and can't be withdrawn; the next release is US$ 300.00 on November 9, 2026."*). Below the minimum, it says so, and with available below zero, it says how much the community owes, which comes out of the next sales.

**Ask like this:** *"How much can I withdraw today, and when is the rest released?"*

## `list_payouts`

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

**Payouts.** The payouts requested, with status. *Minimum role: admin or finance.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `status` | `PENDING`, `PROCESSING`, `COMPLETED`, `FAILED`, `CANCELED` | No | Only one status |
| `page`, `limit` | number | No | Pagination |

**Returns:** the payouts, with id (which `cancel_payout` needs), amount, fee, status and dates. On a failed payout, the reason, already translated (*"The bank did not accept the transfer. The amount and the fee are back in your balance."*).

**Ask like this:** *"Did any payout fail?"*

## `simulate_fee`

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

**How much I receive from a sale.** Simulates a sale: the amount, the platform fee and what the community receives. *Minimum role: admin.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `amount` | number | Yes | The sale amount, in reais |
| `payment_method` | `PIX`, `CREDIT_CARD`, `BOLETO` | No | The payment method |
| `installments` | number | No | Number of card installments |

**Returns:** the amount, the platform fee (which doesn't depend on the payment method) and the net. See [Platform fee](/pagamentos/taxa-da-plataforma).

**Ask like this:** *"If I sell a US$ 97 course, how much does the community keep?"*

## `request_payout`

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

**Request payout.** Requests a payout from the available balance to the registered bank account. *Minimum role: admin; finance can only read.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `amount` | number | Yes | From the minimum (US$ 10.00; R$ 10.00 in reais) to the maximum (check with `get_balance`). At most 2 decimal places: with more, the first call is refused, never rounded (*Enter the payout amount with at most 2 decimal places.*) |

**The summary:** the action, the amount, the payout fee, the total that leaves the balance (amount + fee), the withdrawable amount and the maximum. It says the fee is charged on top (*"the account receives the full amount and the total leaves the balance"*) and that, after your yes, the payout is sent to the bank right away. With refunds waiting for balance, it says how much is reserved for them.

**Ask like this:** *"How much do I have available? Withdraw US$ 2,000."*

**Notes:** the payout fee (0.25% + US$ 0.25 in dollars, coming to communities) and the rules are the same as in the dashboard. See [Payouts](/pagamentos/saque).

Above the maximum, the first call is already refused with the amount you can withdraw, without a confirmation code. After your yes, the result shows the payout's real state: **Processing** (sent to the bank) or **Failed**, with the reason; the assistant suggests `list_payouts` to follow it until **Completed**. Below the minimum, the first call is refused too (*"The minimum payout is US$ 10.00."*). Pending or retained money never goes into a payout.

## `cancel_payout`

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

**Cancel payout.** Cancels a payout that is still pending. *Minimum role: admin.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `payout_id` | id | Yes | From `list_payouts` |

**The summary:** the action, the amount, the status and the request date.

**Ask like this:** *"Cancel the US$ 2,000 payout I requested today."*

## `get_community_fees`

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

**Community fees.** The community's platform fee, the minimum payout and the payment methods. *Minimum role: admin or finance.*

Parameters: none.

**Returns:** the platform fee (percentage and fixed per sale, and per payout), the minimum payout and the methods buyers can use. The platform fee is the same whatever the payment method.

**Ask like this:** *"What fee do I pay?"*

**Notes:** to see what a sale nets, the assistant follows with `simulate_fee`.

## Related

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