# Tools · Credits

> MCP tools for booking credits: balance, statement, 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), 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> |
| [`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 |
|---|---|---|---|
| `profile_id` | id | No | Team only: whose. Without it, it's yours (a member asking for someone else's is refused) |

**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 |
|---|---|---|---|
| `profile_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."*

## `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 |
|---|---|---|---|
| `profile_id` | id | Yes | The member (`list_members`) |
| `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 |
|---|---|---|---|
| `profile_id` | id | Yes | The member |
| `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)