# Tools · Credits

> MCP tools for booking credits: balance, statement, the company wallet, granting, adjusting and taking back credits, and the community rules (accrual, cancellation window, late cancellation and no-shows). Minimum role and recipes.

[Credits](/monetizacao/creditos) through the assistant: seeing the balance and the statement (your own or, for the team, any member's), the wallet of a [company](/membros/empresas#the-company-s-credits), granting and adjusting credits, taking them back, and reading or changing the community rules. The credits of plans and products are set with [`create_plan` and `update_plan`](/mcp/ferramentas-vendas) (`monthly_credits`) and [`create_product` and `update_product`](/mcp/ferramentas-vendas) (`granted_credits` and `granted_credits_validity_days`); in a community with no Bookings or Scheduling space, the assistant explains that one has to be created first.

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_credit_balance`](#get-credit-balance) | The balance, what expires in 7 days and the batches | Any (yours); team (someone else's) | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`list_credit_entries`](#list-credit-entries) | The statement, newest first | Any (yours); team (someone else's) | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`get_company_credit_balance`](#get-company-credit-balance) | The wallet balance of a company | Any (the API checks who reads) | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`list_company_credit_entries`](#list-company-credit-entries) | The company wallet statement, with who used it | Any (the API checks who reads) | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`grant_credits`](#grant-credits) | Opens a new batch of credits, with a reason | Finance | <span class="tool-kind tool-kind-confirm">Asks to confirm</span> |
| [`adjust_credits`](#adjust-credits) | Adds credits as a correction, with a reason | Finance | <span class="tool-kind tool-kind-confirm">Asks to confirm</span> |
| [`revoke_credits`](#revoke-credits) | Takes credits back (negative adjustment) | Finance | <span class="tool-kind tool-kind-confirm">Asks to confirm</span> |
| [`get_credit_settings`](#get-credit-settings) | The community's credit rules | Moderator (or finance) | <span class="tool-kind tool-kind-read">Read-only</span> |
| [`update_credit_settings`](#update-credit-settings) | Changes the rules | Admin | <span class="tool-kind tool-kind-write">Changes</span> |

"Finance" here means **owner, admin or finance**; the **moderator only reads**. "Team" is the owner, the admin, the moderator and finance. The roles are the routes' roles: the assistant never does more than the connected person could do on screen. The platform variable that decides whether a paused or past-due subscription keeps using its balance belongs to the SuperAdmin and has no tool.

## `get_credit_balance`

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

**The balance.** The usable balance (the sum of the batches that haven't expired; it can be negative, which blocks booking), what expires in the next 7 days and the batches, each with its source (**Plan**, **Product** or **Team**), how much is left and when it expires. *Minimum role: any (yours); the team reads any member's.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `member_id` | id | No | Team only: whose. Without it, it's yours (a member asking for someone else's is refused) |

Whoever is on a company with a wallet also gets `company` (the company's id, name and balance), to choose which balance to book with.

**Ask like this:** *"How many credits do I have?"* · *"What is Maria Souza's balance?"*

## `list_credit_entries`

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

**The statement.** Each entry with its type (grant, used on a booking, refund, adjustment, expiration, revocation), the signed amount, the source, the booking, product or subscription behind it and the reason. The ledger only grows: nothing is edited or deleted. Paginated.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `member_id` | id | No | Team only: whose. Without it, it's yours |
| `kind` | `GRANT`, `DEBIT`, `REFUND`, `ADJUSTMENT`, `EXPIRATION` or `REVOCATION` | No | Filters by type |
| `page`, `limit` | number | No | Pagination (`limit` up to 200) |

**Ask like this:** *"Show Maria's credit statement for this month."*

## `get_company_credit_balance`

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

**The company's balance.** The wallet of a company: the credits of the plans the company bought and the manual grants, which its team spends on bookings (`pay_with: company`). Same shape as `get_credit_balance`, plus `company` (id and name). Readers are the owner, the admin, finance and that company's admin; the moderator and a plain employee get "no permission" (the employee sees the company balance in `get_credit_balance`). *Minimum role: any (the API checks who reads).*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `company_id` | id | Yes | The company (from `list_companies` or `get_my_company`) |

**Ask like this:** *"How many credits does Acme have left?"*

## `list_company_credit_entries`

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

**The company's statement**, newest first, like `list_credit_entries`; on booking uses, `usedBy` says who on the team used them. Same access as `get_company_credit_balance`. Paginated.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `company_id` | id | Yes | The company (from `list_companies` or `get_my_company`) |
| `kind`, `page`, `limit` | | No | As in `list_credit_entries` |

**Ask like this:** *"Who at Acme used the company's credits this month?"*

## `grant_credits`

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

**Grant credits.** Opens a **new batch** with a **required reason** and an optional validity (without it, they don't expire). Before acting, it shows a summary and only repeats the call after your yes. Returns the new balance and the entry. *Minimum role: finance.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `member_id` or `company_id` | id | One of the two | The member (`list_members`) or the company wallet (owner and admin only) |
| `amount` | integer, 1 to 100,000 | Yes | How many credits |
| `reason` | text (up to 255) | Yes | The reason: it stays in the statement |
| `expires_at` | future date and time | No | When they expire; without it or `null`, never |

**Ask like this:** *"Give John 10 courtesy credits, valid until the end of the month, because he referred a new member."*

## `adjust_credits`

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

**Adjust upward.** Adds credits as a **correction** (an adjustment entry: it's the way to fix a mistake, since the ledger never edits). Same parameters as `grant_credits` (up to 100,000 at a time), and it also asks to confirm. To take credits away, use [`revoke_credits`](#revoke-credits), which asks to confirm. *Minimum role: finance.*

## `revoke_credits`

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

**Take credits back.** A negative adjustment, with a required reason. It uses **the batches that expire first** and **doesn't go beyond the usable balance** (otherwise, `409`: read the balance first). Before acting, it shows a summary (how much, the balance now, the balance after and the reason) and only repeats the call with the `confirmation_token` after an explicit yes. *Minimum role: finance.*

| Parameter | Type | Required | Description |
|---|---|---|---|
| `member_id` or `company_id` | id | One of the two | The member or the company wallet (owner and admin only) |
| `amount` | integer, 1 or more | Yes | How many credits to remove |
| `reason` | text | Yes | The reason |

## `get_credit_settings`

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

**The rules.** Accrual (on, cap, months), first-month proration, cancellation window in hours, whether late cancellation and no-shows lose the credit, and the days of expiry notice. *Minimum role: moderator (or finance).*

## `update_credit_settings`

<span class="tool-kind tool-kind-write">Changes</span>

**Change the rules.** Changes only what you send. It applies from the next month turnover on and never changes a batch that already exists. *Minimum role: admin.*

| Parameter | Type | Description |
|---|---|---|
| `rollover_enabled` | true or false | Carry plan credits over to the next month (default: no) |
| `rollover_cap` | integer or `null` | The cap on what carries over; `null`, no cap |
| `rollover_max_cycles` | 1 to 12 | For how many months the accumulated credit is valid |
| `prorate_first_month` | true or false | Share for the days left in the first month |
| `change_window_hours` | 0 to 720 | Window to cancel or change without losing (default: 24) |
| `late_cancel_loses_credits` | true or false | Late cancellation loses the credit (default: yes) |
| `no_show_loses_credits` | true or false | A no-show loses the credit (default: yes) |
| `expiry_notice_days` | 0 to 30 | Days of notice before expiring (0 = no notice) |

**Ask like this:** *"Turn on credit accrual, with a cap of 20, for 2 months, and set the cancellation window to 12 hours."*

## Related

- [Credits](/monetizacao/creditos)
- [Tools · Bookings and Scheduling](/mcp/ferramentas-reservas)
- [Tools](/mcp/ferramentas)
- [Money and confirmation](/mcp/dinheiro-e-confirmacao)
- [Recipes](/mcp/receitas)