> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coffeechats.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Billing tools

> Tools that read your subscription, your usage, your credit history and your referral credits.

These tools read your subscription, your usage, your credit history and your referral credits. They need the permission `billing:read`, which you grant on the Authorize access page when you connect.

This page is generated from the connector's tool catalogue. It describes 5 tools. Every tool reads or writes only your own account.

## Permissions this page needs

* `billing:read`: Read your subscription, usage, and referral information

The [permissions reference](/mcp/scopes.md) lists every permission you can grant.

## `billing.subscription.get`

Your agent host shows this tool as "Get subscription".

Read the authenticated student's sanitized subscription, bonus/referral credits and prepaid pack balance.

Permissions: This tool needs `billing:read`, which the Authorize access page describes as "Read your subscription, usage, and referral information".

Risk: `read`. This tool only reads your own data. It never changes anything and it never asks for your approval.

### Input

| Property | Type | Required | Bounds |
| - | - | - | - |
| `cursor` | string | no | 1 to 512 characters; pattern `^[A-Za-z0-9_-]+$` |

### Example call

```json billing.subscription.get input theme={"system"}
{}
```

### Result

A result is never larger than 16,384 bytes.
If the stored value does not fit, the tool returns a measured fragment and a cursor for the next one.

This tool's result takes one of these 2 forms, and one call returns exactly one of them. The field named beside each form below says which one you are looking at. Open a form to read its top-level fields.

> **Shape 1**
>
> ```json Top-level fields theme={"system"}
> [
>   "avatarOverageEnabled",
>   "billingInterval",
>   "cancelAtPeriodEnd",
>   "canceledAt",
>   "chatTokensOverageEnabled",
>   "currency",
>   "currentPeriodEndsAt",
>   "currentPeriodStartsAt",
>   "freeTrialEndsAt",
>   "jobCreditsOverageCapCents",
>   "jobCreditsOverageEnabled",
>   "lastSyncedAt",
>   "overageEnabled",
>   "pastDueSince",
>   "prepaidCreditBalance",
>   "referralCreditBalance",
>   "referralCreditsExpireAt",
>   "scheduledChangeAt",
>   "scheduledInterval",
>   "scheduledTier",
>   "status",
>   "tier",
>   "trialEndsAt",
>   "unitAmountCents",
>   "voiceOverageEnabled"
> ]
> ```

> **Shape 2**
>
> ```json Top-level fields theme={"system"}
> [
>   "fragment",
>   "nextCursor"
> ]
> ```

### Errors

A failed call returns one protocol error with no error code, and its text is `Tool call failed.` every time. This tool looks up no record by id, so it never sends a text that names a record. The [error codes](/mcp/errors.md) page gives every text a read failure can carry.

## `billing.usage.get`

Your agent host shows this tool as "Get usage".

Read the authenticated student's current stored usage without creating a period.

Permissions: This tool needs `billing:read`, which the Authorize access page describes as "Read your subscription, usage, and referral information".

Risk: `read`. This tool only reads your own data. It never changes anything and it never asks for your approval.

### Input

| Property | Type | Required | Bounds |
| - | - | - | - |
| `cursor` | string | no | 1 to 512 characters; pattern `^[A-Za-z0-9_-]+$` |

### Example call

```json billing.usage.get input theme={"system"}
{}
```

### Result

A result is never larger than 16,384 bytes.
If the stored value does not fit, the tool returns a measured fragment and a cursor for the next one.

This tool's result takes one of these 2 forms, and one call returns exactly one of them. The field named beside each form below says which one you are looking at. Open a form to read its top-level fields.

> **Shape 1**
>
> ```json Top-level fields theme={"system"}
> [
>   "aiAvatarMinutesUsed",
>   "aiChatTokensUsed",
>   "aiCreditsUsed",
>   "aiVoiceAgentMinutesUsed",
>   "avatarPracticeCreditsSettled",
>   "contactsReached",
>   "deepResearchUsed",
>   "fastLaneTokensUsed",
>   "found",
>   "jobCredits",
>   "modelBreakdownCount",
>   "overageAvatarMinutesUsed",
>   "overageChatTokensUsed",
>   "overageCreditsUsed",
>   "overageVoiceMinutesUsed",
>   "periodEnd",
>   "periodStart",
>   "projectsCreated",
>   "standardResearchUsed",
>   "tier",
>   "tokensMonthKey",
>   "voicePracticeCreditsSettled"
> ]
> ```

> **Shape 2**
>
> ```json Top-level fields theme={"system"}
> [
>   "fragment",
>   "nextCursor"
> ]
> ```

### Errors

A failed call returns one protocol error with no error code, and its text is `Tool call failed.` every time. This tool looks up no record by id, so it never sends a text that names a record. The [error codes](/mcp/errors.md) page gives every text a read failure can carry.

## `billing.credit_history.list`

Your agent host shows this tool as "List credit history".

List the authenticated student's credit transactions with measured pagination.

Permissions: This tool needs `billing:read`, which the Authorize access page describes as "Read your subscription, usage, and referral information".

Risk: `read`. This tool only reads your own data. It never changes anything and it never asks for your approval.

### Input

| Property | Type | Required | Bounds |
| - | - | - | - |
| `cursor` | string | no | 1 to 512 characters; pattern `^[A-Za-z0-9_-]+$` |
| `limit` | integer | no | from 1 to 20 |

### Example call

```json billing.credit_history.list input theme={"system"}
{
  "limit": 10
}
```

### Result

A result is never larger than 16,384 bytes.
If the stored value does not fit, the tool returns a measured fragment and a cursor for the next one.

This tool's result takes one of these 2 forms, and one call returns exactly one of them. The field named beside each form below says which one you are looking at. Open a form to read its top-level fields.

> **Shape 1**
>
> ```json Top-level fields theme={"system"}
> [
>   "nextCursor",
>   "transactions"
> ]
> ```

> **Shape 2**
>
> ```json Top-level fields theme={"system"}
> [
>   "fragment",
>   "nextCursor",
>   "transactions"
> ]
> ```

### Errors

A failed call returns one protocol error with no error code, and its text is `Tool call failed.` every time. This tool looks up no record by id, so it never sends a text that names a record. The [error codes](/mcp/errors.md) page gives every text a read failure can carry.

## `billing.referrals.get`

Your agent host shows this tool as "Get referrals".

Read the authenticated student's referral code, credits, and invited count.

Permissions: This tool needs `billing:read`, which the Authorize access page describes as "Read your subscription, usage, and referral information".

Risk: `read`. This tool only reads your own data. It never changes anything and it never asks for your approval.

### Input

| Property | Type | Required | Bounds |
| - | - | - | - |
| `cursor` | string | no | 1 to 512 characters; pattern `^[A-Za-z0-9_-]+$` |

### Example call

```json billing.referrals.get input theme={"system"}
{}
```

### Result

A result is never larger than 16,384 bytes.
If the stored value does not fit, the tool returns a measured fragment and a cursor for the next one.

This tool's result takes one of these 2 forms, and one call returns exactly one of them. The field named beside each form below says which one you are looking at. Open a form to read its top-level fields.

> **Shape 1**
>
> ```json Top-level fields theme={"system"}
> [
>   "code",
>   "creditBalance",
>   "creditsExpireAt",
>   "invitedCount",
>   "lifetimeAsReferee",
>   "lifetimeAsReferrer"
> ]
> ```

> **Shape 2**
>
> ```json Top-level fields theme={"system"}
> [
>   "fragment",
>   "nextCursor"
> ]
> ```

### Errors

A failed call returns one protocol error with no error code, and its text is `Tool call failed.` every time. This tool looks up no record by id, so it never sends a text that names a record. The [error codes](/mcp/errors.md) page gives every text a read failure can carry.

## `billing.limits.get`

Your agent host shows this tool as "Get plan limits".

Read the authenticated student's plan tier, entitlement source, billing period and allowances, without creating a usage period.

Permissions: This tool needs `billing:read`, which the Authorize access page describes as "Read your subscription, usage, and referral information".

Risk: `read`. This tool only reads your own data. It never changes anything and it never asks for your approval.

### Input

| Property | Type | Required | Bounds |
| - | - | - | - |
| `cursor` | string | no | 1 to 512 characters; pattern `^[A-Za-z0-9_-]+$` |

### Example call

```json billing.limits.get input theme={"system"}
{}
```

### Result

A result is never larger than 16,384 bytes.
If the stored value does not fit, the tool returns a measured fragment and a cursor for the next one.

This tool's result takes one of these 2 forms, and one call returns exactly one of them. The field named beside each form below says which one you are looking at. Open a form to read its top-level fields.

> **Shape 1**
>
> ```json Top-level fields theme={"system"}
> [
>   "entitlementSource",
>   "freeTrial",
>   "jobCredits",
>   "limits",
>   "periodEnd",
>   "periodSource",
>   "periodStart",
>   "readOnly",
>   "selfTier",
>   "tier",
>   "tokenPeriodEnd"
> ]
> ```

> **Shape 2**
>
> ```json Top-level fields theme={"system"}
> [
>   "fragment",
>   "nextCursor"
> ]
> ```

### Errors

A failed call returns one protocol error with no error code, and its text is `Tool call failed.` every time. This tool looks up no record by id, so it never sends a text that names a record. The [error codes](/mcp/errors.md) page gives every text a read failure can carry.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.