Bill tools for AI assistants - AI2Fin Documentation

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.

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.

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

{
  "active": true
}

Example Response

{
  "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

{
  "days": 30
}

Example Response

{
  "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

{
  "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

NEW - Flexible Historical Queries

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

{
  "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

NEW - Overdue Detection

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

{
  "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

NEW - Financial Year Analysis

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

{
  "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

NEW - Payment Management

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

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

upload_receipt_for_bill

NEW - Receipt Management

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

{
  "success": true,
  "data": {
    "message": "✅ Receipt uploaded and linked to Netflix payment."
  }
}

create_bill_pattern

NEW - Manual Bill Creation

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

Custom rules will automatically apply to the created bill pattern.

update_bill_pattern

NEW - Bill Management

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "tool": "get_bill_occurrences",
  "params": {
    "merchantName": "Woolworths",
    "isPaid": true,
    "startDate": "2024-03-01",
    "endDate": "2024-03-31"
  }
}

🌍 Financial Year Support

Country-Aware FY Calculations

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:

Recognises recurring merchants — payments to the same provider that repeat over time
Works out the frequency — weekly, fortnightly, monthly, quarterly or yearly
Checks the amounts line up — so genuine recurring costs are grouped together
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

Transaction Tools

Access transaction data

Subscription Tools

Check feature access

​get_bills

​Parameters

​Response fields

​Example Request

​Example Response

​get_upcoming_bills

​Parameters

​Response fields

​Example Request

​Example Response

​get_bill_summary

​Parameters

​Example Response

​get_bill_occurrences

​Parameters

​Example Response

​get_overdue_bills

​Parameters

​Example Response

​get_bill_pattern_financial_summary

​Parameters

​Example Response

​mark_bill_as_paid

​Parameters

​Example Response

​upload_receipt_for_bill

​Parameters

​Example Response

​create_bill_pattern

​Parameters

​update_bill_pattern

​Parameters

​Real-World Examples

​View All Bills

​Check Upcoming Payments

​Calculate Monthly Bill Cost

​Check Overdue Bills

​Financial Year Summary

​Mark Bill as Paid

​Query Historical Payments

​🌍 Financial Year Support

​Bill Frequencies

​How bills are detected

​Bill Status

​Bill Pattern Status

​Occurrence Status

​Important Notes

​Automatic Updates

​Manual Management

​Privacy and speed

​Next Steps

Transaction Tools

Subscription Tools

get_bills

Parameters

Response fields

Example Request

Example Response

get_upcoming_bills

Parameters

Response fields

Example Request

Example Response

get_bill_summary

Parameters

Example Response

get_bill_occurrences

Parameters

Example Response

get_overdue_bills

Parameters

Example Response

get_bill_pattern_financial_summary

Parameters

Example Response

mark_bill_as_paid

Parameters

Example Response

upload_receipt_for_bill

Parameters

Example Response

create_bill_pattern

Parameters

update_bill_pattern

Parameters

Real-World Examples

View All Bills

Check Upcoming Payments

Calculate Monthly Bill Cost

Check Overdue Bills

Financial Year Summary

Mark Bill as Paid

Query Historical Payments

🌍 Financial Year Support

Bill Frequencies

How bills are detected

Bill Status

Bill Pattern Status

Occurrence Status

Important Notes

Automatic Updates

Manual Management

Privacy and speed

Next Steps