Bill Tools

AI2Fin MCP provides 10 tools for managing recurring bill patterns, occurrences, payments, and financial year summaries.

Bills are automatically detected patterns in your transaction history. The AI identifies recurring payments and creates bill patterns.

get_bills

Retrieves all recurring bill patterns for the user.

Parameters

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

Real Bill Pattern Fields

{
  id: string;
  userId: string;
  merchantName: string;          // Bill merchant/provider
  description: string;           // Bill description
  amount: number;                // Base amount
  baseRecurringAmount: number;   // Recurring amount
  billFrequency: string;         // "WEEKLY" | "FORTNIGHTLY" | "MONTHLY" | "QUARTERLY" | "YEARLY"
  nextDueDate: Date;             // Next expected due date
  isActive: boolean;             // Is bill still active
  category?: {
    id: string;
    name: string;
  };
  firstOccurrence: Date;         // When first detected
  lastOccurrence: Date;          // Last occurrence
  occurrenceCount: number;       // Total occurrences
  confidence: number;            // AI confidence (0-1)
  createdAt: Date;
  updatedAt: Date;
}

Example Request

{
  "active": true
}

Example Response

{
  "success": true,
  "data": {
    "bills": [
      {
        "id": "bill_123",
        "merchantName": "Netflix",
        "description": "Netflix Subscription",
        "amount": 19.99,
        "baseRecurringAmount": 19.99,
        "billFrequency": "MONTHLY",
        "nextDueDate": "2025-11-15T00:00:00.000Z",
        "isActive": true,
        "occurrenceCount": 24,
        "confidence": 0.98,
        "firstOccurrence": "2023-11-15T00:00:00.000Z",
        "lastOccurrence": "2025-10-15T00:00:00.000Z"
      },
      {
        "id": "bill_456",
        "merchantName": "Office Rent",
        "description": "Monthly Office Rent",
        "amount": 2500.00,
        "baseRecurringAmount": 2500.00,
        "billFrequency": "MONTHLY",
        "nextDueDate": "2025-11-01T00:00:00.000Z",
        "isActive": true,
        "occurrenceCount": 36,
        "confidence": 1.0
      }
    ],
    "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)

Bill Occurrence Fields

{
  id: string;
  billPatternId: string;
  dueDate: Date;                // When bill is due
  amount: number;               // Expected amount
  status: string;               // "pending" | "paid" | "overdue"
  paid: boolean;                // Has been paid
  paidDate?: Date;              // When it was paid
  linkedTransactionId?: string; // Transaction that paid this bill
  billPattern: {                // Full pattern info
    merchantName: string;
    description: string;
    billFrequency: string;
  };
}

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:

Reads countryCode from user profile
Calculates correct FY start/end dates
Supports YTD (Year-to-Date) calculations
Distinguishes actual paid vs projected amounts

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

Bill Detection

Bills are automatically detected by AI analyzing your transaction history:

Pattern Recognition: Identifies recurring merchants
Frequency Detection: Determines payment frequency
Amount Consistency: Checks if amounts are consistent
Confidence Score: Assigns confidence (0-1)
Bill Creation: Creates pattern if confidence > 0.8

High Confidence (0.9+):

Same merchant
Same amount (±5%)
Consistent interval

Medium Confidence (0.7-0.9):

Same merchant
Varying amount (±20%)
Mostly consistent interval

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

Performance

Direct database access (~5-10ms)
No external API calls
User-isolated queries

Next Steps

Transaction Tools

Access transaction data

Subscription Tools

Check feature access

Getting Started

Authentication

Tools Reference

Integration

​Bill Tools

​get_bills

​Parameters

​Real Bill Pattern Fields

​Example Request

​Example Response

​get_upcoming_bills

​Parameters

​Bill Occurrence 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

​Bill Detection

​Bill Status

​Bill Pattern Status

​Occurrence Status

​Important Notes

​Automatic Updates

​Manual Management

​Performance

​Next Steps

Transaction Tools

Subscription Tools

Bill Tools

get_bills

Parameters

Real Bill Pattern Fields

Example Request

Example Response

get_upcoming_bills

Parameters

Bill Occurrence 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

Bill Detection

Bill Status

Bill Pattern Status

Occurrence Status

Important Notes

Automatic Updates

Manual Management

Performance

Next Steps