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

# Bill tools for AI assistants

> AI2Fin MCP bill tools to track recurring bills, see upcoming and overdue payments, mark bills as paid, attach receipts, and get country-aware financial-year summaries from ChatGPT, Claude or Cursor.

# Bill Tools

The AI2Fin MCP server gives your AI assistant the tools to stay on top of recurring bills: see what's coming up, catch anything overdue, mark payments off, attach receipts, and roll everything up into financial-year totals.

<Note>
  AI2Fin spots recurring payments in your transaction history and turns them into bills automatically — so subscriptions, rent, insurance and other regular costs show up without manual setup. You can also add or edit bills yourself at any time.
</Note>

***

## get\_bills

Retrieves all recurring bill patterns for the user.

### Parameters

| Parameter | Type    | Required | Description              |
| --------- | ------- | -------- | ------------------------ |
| `active`  | boolean | No       | Filter active bills only |

### Response fields

Each bill in the response includes:

| Field             | Description                                                  |
| ----------------- | ------------------------------------------------------------ |
| `id`              | Bill identifier                                              |
| `merchantName`    | Biller or provider name                                      |
| `description`     | What the bill is for                                         |
| `amount`          | Expected recurring amount                                    |
| `billFrequency`   | `WEEKLY`, `FORTNIGHTLY`, `MONTHLY`, `QUARTERLY`, or `YEARLY` |
| `nextDueDate`     | When the next payment is expected                            |
| `isActive`        | Whether the bill is still active                             |
| `category`        | Assigned category (`id`, `name`)                             |
| `occurrenceCount` | How many times this bill has occurred so far                 |

### Example Request

```json theme={null}
{
  "active": true
}
```

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "bills": [
      {
        "id": "bill_123",
        "merchantName": "Netflix",
        "description": "Netflix Subscription",
        "amount": 19.99,
        "billFrequency": "MONTHLY",
        "nextDueDate": "2025-11-15T00:00:00.000Z",
        "isActive": true,
        "category": { "id": "cat_subscriptions", "name": "Subscriptions" },
        "occurrenceCount": 24
      },
      {
        "id": "bill_456",
        "merchantName": "Office Rent",
        "description": "Monthly Office Rent",
        "amount": 2500.00,
        "billFrequency": "MONTHLY",
        "nextDueDate": "2025-11-01T00:00:00.000Z",
        "isActive": true,
        "category": { "id": "cat_rent", "name": "Rent" },
        "occurrenceCount": 36
      }
    ],
    "count": 2
  }
}
```

***

## get\_upcoming\_bills

Retrieves upcoming bill occurrences (due dates).

### Parameters

| Parameter | Type   | Required | Description                      |
| --------- | ------ | -------- | -------------------------------- |
| `days`    | number | No       | Days ahead to look (default: 30) |

### Response fields

Each upcoming bill occurrence includes:

| Field         | Description                                                                 |
| ------------- | --------------------------------------------------------------------------- |
| `id`          | Occurrence identifier                                                       |
| `dueDate`     | When the bill is due                                                        |
| `amount`      | Expected amount                                                             |
| `status`      | `pending`, `paid`, or `overdue`                                             |
| `paid`        | Whether it has been paid                                                    |
| `paidDate`    | When it was paid (if applicable)                                            |
| `billPattern` | Summary of the parent bill (`merchantName`, `description`, `billFrequency`) |

### Example Request

```json theme={null}
{
  "days": 30
}
```

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "occurrences": [
      {
        "id": "occ_789",
        "billPatternId": "bill_456",
        "dueDate": "2025-11-01T00:00:00.000Z",
        "amount": 2500.00,
        "status": "pending",
        "paid": false,
        "billPattern": {
          "merchantName": "Office Rent",
          "description": "Monthly Office Rent",
          "billFrequency": "MONTHLY"
        }
      },
      {
        "id": "occ_790",
        "billPatternId": "bill_123",
        "dueDate": "2025-11-15T00:00:00.000Z",
        "amount": 19.99,
        "status": "pending",
        "paid": false,
        "billPattern": {
          "merchantName": "Netflix",
          "description": "Netflix Subscription",
          "billFrequency": "MONTHLY"
        }
      }
    ],
    "count": 2,
    "daysAhead": 30
  }
}
```

***

## get\_bill\_summary

Calculates bill summary including monthly totals and frequency breakdown.

### Parameters

None required.

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "totalBills": 5,
    "monthlyTotal": 3845.50,
    "byFrequency": {
      "MONTHLY": 3,
      "QUARTERLY": 1,
      "YEARLY": 1
    },
    "bills": [
      {
        "name": "Office Rent",
        "amount": 2500.00,
        "frequency": "MONTHLY"
      },
      {
        "name": "Netflix",
        "amount": 19.99,
        "frequency": "MONTHLY"
      },
      {
        "name": "Spotify",
        "amount": 12.99,
        "frequency": "MONTHLY"
      },
      {
        "name": "Professional Insurance",
        "amount": 1200.00,
        "frequency": "QUARTERLY"
      },
      {
        "name": "Software License",
        "amount": 599.00,
        "frequency": "YEARLY"
      }
    ]
  }
}
```

**Monthly Total Calculation**:

* WEEKLY bills × 4
* FORTNIGHTLY bills × 2
* MONTHLY bills × 1
* QUARTERLY bills ÷ 3
* YEARLY bills ÷ 12

***

## get\_bill\_occurrences

<Note>NEW - Flexible Historical Queries</Note>

Query bill occurrences with flexible filtering by payment status, date range, and merchant.

### Parameters

| Parameter       | Type    | Required | Description                                      |
| --------------- | ------- | -------- | ------------------------------------------------ |
| `isPaid`        | boolean | No       | true=paid only, false=unpaid only, undefined=all |
| `startDate`     | string  | No       | Start date (ISO 8601)                            |
| `endDate`       | string  | No       | End date (ISO 8601)                              |
| `merchantName`  | string  | No       | Filter by merchant (partial match)               |
| `billPatternId` | string  | No       | Specific pattern ID                              |
| `limit`         | number  | No       | Max results (default: 100)                       |

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "count": 4,
    "totalAmount": 63.96,
    "occurrences": [
      {
        "id": "occ_123",
        "dueDate": "2024-10-15",
        "amount": 15.99,
        "isPaid": true,
        "paidDate": "2024-10-15",
        "billPattern": {
          "merchantName": "Netflix",
          "frequency": "MONTHLY"
        }
      }
    ]
  }
}
```

***

## get\_overdue\_bills

<Note>NEW - Overdue Detection</Note>

Retrieves all overdue (unpaid) bills that have passed their due date.

### Parameters

| Parameter | Type   | Required | Description               |
| --------- | ------ | -------- | ------------------------- |
| `limit`   | number | No       | Max results (default: 50) |

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "count": 2,
    "totalOverdue": 28.98,
    "occurrences": [
      {
        "id": "occ_456",
        "dueDate": "2024-10-15",
        "amount": 15.99,
        "isPaid": false,
        "billPattern": {
          "merchantName": "Netflix"
        }
      }
    ]
  }
}
```

***

## get\_bill\_pattern\_financial\_summary

<Note>NEW - Financial Year Analysis</Note>

Get financial summary for a bill pattern with country-aware FY calculations and projections.

### Parameters

| Parameter            | Type    | Required | Description                                                                  |
| -------------------- | ------- | -------- | ---------------------------------------------------------------------------- |
| `billPatternId`      | string  | No\*     | Specific pattern ID                                                          |
| `merchantName`       | string  | No\*     | Merchant name (alternative to ID)                                            |
| `period`             | string  | Yes      | "financial\_year", "year\_to\_date", "calendar\_year", "all\_time", "custom" |
| `startDate`          | string  | No       | Custom start date (if period=custom)                                         |
| `endDate`            | string  | No       | Custom end date (if period=custom)                                           |
| `includeProjections` | boolean | No       | Include future/unpaid (default: true)                                        |

\*Either `billPatternId` OR `merchantName` required

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "billPattern": {
      "merchantName": "Netflix",
      "frequency": "MONTHLY",
      "baseAmount": 15.99
    },
    "period": {
      "type": "financial_year",
      "financialYear": "FY2024-2025",
      "country": "AU"
    },
    "actualPaid": {
      "count": 4,
      "total": 63.96
    },
    "projected": {
      "count": 8,
      "total": 127.92
    },
    "summary": {
      "actualPaidTotal": 63.96,
      "projectedTotal": 127.92,
      "totalExpected": 191.88,
      "averageActual": 15.99
    }
  }
}
```

***

## mark\_bill\_as\_paid

<Note>NEW - Payment Management</Note>

Mark a bill occurrence as paid with optional transaction linking.

### Parameters

| Parameter       | Type   | Required | Description                   |
| --------------- | ------ | -------- | ----------------------------- |
| `occurrenceId`  | string | Yes      | Bill occurrence ID            |
| `paidDate`      | string | No       | Payment date (default: today) |
| `actualAmount`  | number | No       | Actual amount paid            |
| `transactionId` | string | No       | Link to transaction           |
| `notes`         | string | No       | Payment notes                 |

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "message": "✅ Marked Netflix ($15.99) as paid on Nov 3, 2024."
  }
}
```

***

## upload\_receipt\_for\_bill

<Note>NEW - Receipt Management</Note>

Link an uploaded receipt to a bill payment.

### Parameters

| Parameter         | Type   | Required | Description           |
| ----------------- | ------ | -------- | --------------------- |
| `occurrenceId`    | string | Yes      | Bill occurrence ID    |
| `receiptUrl`      | string | Yes      | Receipt file URL/path |
| `receiptFileName` | string | No       | Original file name    |
| `notes`           | string | No       | Additional notes      |

### Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "message": "✅ Receipt uploaded and linked to Netflix payment."
  }
}
```

***

## create\_bill\_pattern

<Note>NEW - Manual Bill Creation</Note>

Create a new recurring bill pattern manually.

### Parameters

| Parameter               | Type    | Required | Description                                               |
| ----------------------- | ------- | -------- | --------------------------------------------------------- |
| `merchantName`          | string  | Yes      | Merchant/biller name                                      |
| `amount`                | number  | Yes      | Bill amount (positive)                                    |
| `firstDueDate`          | string  | Yes      | First due date (ISO 8601)                                 |
| `frequency`             | string  | Yes      | "WEEKLY", "FORTNIGHTLY", "MONTHLY", "QUARTERLY", "YEARLY" |
| `description`           | string  | No       | Bill description                                          |
| `categoryId`            | string  | No       | Category ID                                               |
| `isTaxDeductible`       | boolean | No       | Tax deductible status                                     |
| `businessUsePercentage` | number  | No       | Business use % (0-100)                                    |
| `notes`                 | string  | No       | Additional notes                                          |

<Note>Custom rules will automatically apply to the created bill pattern.</Note>

***

## update\_bill\_pattern

<Note>NEW - Bill Management</Note>

Update an existing bill pattern.

### Parameters

| Parameter         | Type    | Required | Description           |
| ----------------- | ------- | -------- | --------------------- |
| `billPatternId`   | string  | Yes      | Pattern ID to update  |
| `merchantName`    | string  | No       | Updated merchant name |
| `amount`          | number  | No       | Updated amount        |
| `frequency`       | string  | No       | Updated frequency     |
| `categoryId`      | string  | No       | Updated category      |
| `isTaxDeductible` | boolean | No       | Updated tax status    |
| `isActive`        | boolean | No       | Active status         |

***

## Real-World Examples

### View All Bills

**User**: "What bills do I have?"

**AI calls**:

```json theme={null}
{
  "tool": "get_bills",
  "params": {
    "active": true
  }
}
```

**AI responds**: "You have 5 active recurring bills: Office Rent ($2,500/month), Netflix ($19.99/month), Spotify ($12.99/month), Professional Insurance ($1,200/quarter), and Software License (\$599/year)."

### Check Upcoming Payments

**User**: "What bills are due this month?"

**AI calls**:

```json theme={null}
{
  "tool": "get_upcoming_bills",
  "params": {
    "days": 30
  }
}
```

**AI responds**: "You have 2 bills due this month: Office Rent ($2,500) on November 1st and Netflix ($19.99) on November 15th. Total: \$2,519.99."

### Calculate Monthly Bill Cost

**User**: "How much do I spend on bills monthly?"

**AI calls**:

```json theme={null}
{
  "tool": "get_bill_summary",
  "params": {}
}
```

**AI responds**: "Your monthly bill total is approximately \$3,845.50. This includes 3 monthly bills, 1 quarterly bill (prorated), and 1 yearly bill (prorated)."

### Check Overdue Bills

**User**: "What are my overdue bills?"

**AI calls**:

```json theme={null}
{
  "tool": "get_overdue_bills",
  "params": {}
}
```

**AI responds**: "You have 2 overdue bills: Netflix ($15.99, due Oct 15) and Spotify ($12.99, due Oct 20). Total overdue: \$28.98."

### Financial Year Summary

**User**: "How much have I paid for Netflix this financial year?"

**AI calls**:

```json theme={null}
{
  "tool": "get_bill_pattern_financial_summary",
  "params": {
    "merchantName": "Netflix",
    "period": "financial_year",
    "includeProjections": false
  }
}
```

**AI responds**: "Netflix FY2024-2025 (AU): You've paid $63.96 so far (4 payments). Projected remaining FY cost: $127.92."

### Mark Bill as Paid

**User**: "Mark my Netflix bill as paid"

**AI calls**:

```json theme={null}
{
  "tool": "mark_bill_as_paid",
  "params": {
    "occurrenceId": "occ_123",
    "paidDate": "2024-11-03"
  }
}
```

### Query Historical Payments

**User**: "Show me all Woolworths bills I paid in March"

**AI calls**:

```json theme={null}
{
  "tool": "get_bill_occurrences",
  "params": {
    "merchantName": "Woolworths",
    "isPaid": true,
    "startDate": "2024-03-01",
    "endDate": "2024-03-31"
  }
}
```

***

## 🌍 Financial Year Support

<Note>Country-Aware FY Calculations</Note>

The `get_bill_pattern_financial_summary` tool automatically detects your country and uses the correct financial year dates:

| Country             | FY Start  | FY End       | Example                                  |
| ------------------- | --------- | ------------ | ---------------------------------------- |
| Australia (AU)      | July 1    | June 30      | FY2024-2025 = Jul 1, 2024 - Jun 30, 2025 |
| New Zealand (NZ)    | July 1    | June 30      | Same as AU                               |
| United Kingdom (UK) | April 1   | March 31     | FY2024-2025 = Apr 1, 2024 - Mar 31, 2025 |
| United States (US)  | October 1 | September 30 | FY2025 = Oct 1, 2024 - Sep 30, 2025      |
| India (IN)          | April 1   | March 31     | Same as UK                               |
| Canada (CA)         | April 1   | March 31     | Same as UK                               |
| Singapore (SG)      | April 1   | March 31     | Same as UK                               |
| Others              | January 1 | December 31  | Calendar year                            |

**Automatic Detection:**

* Uses the country set in your AI2Fin profile
* Calculates the correct FY start and end dates for you
* Supports Year-to-Date (YTD) calculations
* Separates what you've actually paid from what's still projected

***

## Bill Frequencies

| Frequency     | Description    | Monthly Calculation |
| ------------- | -------------- | ------------------- |
| `WEEKLY`      | Every week     | Amount × 4          |
| `FORTNIGHTLY` | Every 2 weeks  | Amount × 2          |
| `MONTHLY`     | Every month    | Amount × 1          |
| `QUARTERLY`   | Every 3 months | Amount ÷ 3          |
| `YEARLY`      | Once per year  | Amount ÷ 12         |

***

## How bills are detected

AI2Fin looks at your transaction history and turns recurring payments into bills for you, so you don't have to set them up by hand:

1. **Recognises recurring merchants** — payments to the same provider that repeat over time
2. **Works out the frequency** — weekly, fortnightly, monthly, quarterly or yearly
3. **Checks the amounts line up** — so genuine recurring costs are grouped together
4. **Creates the bill** when there's a clear, reliable pattern

The clearer and steadier the pattern (same provider, consistent amount, regular timing), the more confident AI2Fin is — and you can always confirm, edit, or remove a detected bill yourself.

***

## Bill Status

### Bill Pattern Status

* `isActive: true` - Bill is currently active
* `isActive: false` - Bill stopped/cancelled

### Occurrence Status

* `pending` - Not yet paid
* `paid` - Payment processed
* `overdue` - Past due date, not paid

***

## Important Notes

### Automatic Updates

Bills update automatically when:

* New matching transaction detected
* Payment processed for occurrence
* Pattern changes (amount, frequency)

### Manual Management

Users can:

* Mark bills as inactive
* Edit bill details
* Link transactions manually
* Override AI detection

### Privacy and speed

* Bill queries are fast, so your assistant responds quickly.
* Every request is scoped to your account — you only ever see your own bills.

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Transaction Tools" icon="list" href="/mcp/transaction-tools">
    Access transaction data
  </Card>

  <Card title="Subscription Tools" icon="credit-card" href="/mcp/subscription-tools">
    Check feature access
  </Card>
</CardGroup>