create_scheduled_transaction

Set up automated recurring transactions for future payments in your YNAB budget by specifying frequency, amount, and start date to maintain consistent financial planning.

Instructions

Create a scheduled transaction (for future/recurring transactions).

Args:
    budget_id: The ID of the budget (use 'last-used' for default budget)
    account_id: The account ID for this scheduled transaction
    date_first: The first date the transaction should occur (YYYY-MM-DD format)
    frequency: Frequency (never, daily, weekly, everyOtherWeek, twiceAMonth, every4Weeks, monthly, everyOtherMonth, every3Months, every4Months, twiceAYear, yearly, everyOtherYear)
    amount: Transaction amount (positive for inflow, negative for outflow)
    payee_name: Name of the payee (optional)
    category_id: Category ID (optional)
    memo: Transaction memo (optional)
    flag_color: Flag color - red, orange, yellow, green, blue, purple (optional)

Returns:
    JSON string with the created scheduled transaction

Input Schema

TableJSON Schema

Name	Required	Description	Default
`account_id`	Yes
`amount`	Yes
`budget_id`	Yes
`category_id`	No
`date_first`	Yes
`flag_color`	No
`frequency`	Yes
`memo`	No
`payee_name`	No

Implementation Reference

src/ynab_mcp/server.py:358-398 (handler)

MCP tool handler and registration for 'create_scheduled_transaction'. Decorated with @mcp.tool(), defines input schema via type hints and docstring, delegates to YNABClient.

@mcp.tool()
async def create_scheduled_transaction(
    budget_id: str,
    account_id: str,
    date_first: str,
    frequency: str,
    amount: float,
    payee_name: str = None,
    category_id: str = None,
    memo: str = None,
    flag_color: str = None,
) -> str:
    """Create a scheduled transaction (for future/recurring transactions).

    Args:
        budget_id: The ID of the budget (use 'last-used' for default budget)
        account_id: The account ID for this scheduled transaction
        date_first: The first date the transaction should occur (YYYY-MM-DD format)
        frequency: Frequency (never, daily, weekly, everyOtherWeek, twiceAMonth, every4Weeks, monthly, everyOtherMonth, every3Months, every4Months, twiceAYear, yearly, everyOtherYear)
        amount: Transaction amount (positive for inflow, negative for outflow)
        payee_name: Name of the payee (optional)
        category_id: Category ID (optional)
        memo: Transaction memo (optional)
        flag_color: Flag color - red, orange, yellow, green, blue, purple (optional)

    Returns:
        JSON string with the created scheduled transaction
    """
    client = get_ynab_client()
    result = await client.create_scheduled_transaction(
        budget_id,
        account_id,
        date_first,
        frequency,
        amount,
        payee_name,
        category_id,
        memo,
        flag_color,
    )
    return json.dumps(result, indent=2)

src/ynab_mcp/ynab_client.py:1123-1189 (helper)

Core implementation of scheduled transaction creation in YNABClient class. Constructs API payload and performs POST request to YNAB /scheduled_transactions endpoint.

async def create_scheduled_transaction(
    self,
    budget_id: str,
    account_id: str,
    date_first: str,
    frequency: str,
    amount: float,
    payee_name: str | None = None,
    category_id: str | None = None,
    memo: str | None = None,
    flag_color: str | None = None,
) -> dict[str, Any]:
    """Create a scheduled transaction.

    Args:
        budget_id: The budget ID or 'last-used'
        account_id: The account ID
        date_first: The first date the transaction should occur (YYYY-MM-DD)
        frequency: Frequency (never, daily, weekly, everyOtherWeek, twiceAMonth, every4Weeks, monthly, everyOtherMonth, every3Months, every4Months, twiceAYear, yearly, everyOtherYear)
        amount: Transaction amount (positive for inflow, negative for outflow)
        payee_name: Payee name (optional)
        category_id: Category ID (optional)
        memo: Transaction memo (optional)
        flag_color: Flag color (red, orange, yellow, green, blue, purple, optional)

    Returns:
        Created scheduled transaction dictionary
    """
    try:
        url = f"{self.api_base_url}/budgets/{budget_id}/scheduled_transactions"

        scheduled_transaction_data = {
            "account_id": account_id,
            "date": date_first,
            "frequency": frequency,
            "amount": int(amount * 1000),  # Convert to milliunits
        }

        if payee_name is not None:
            scheduled_transaction_data["payee_name"] = payee_name
        if category_id is not None:
            scheduled_transaction_data["category_id"] = category_id
        if memo is not None:
            scheduled_transaction_data["memo"] = memo
        if flag_color is not None:
            scheduled_transaction_data["flag_color"] = flag_color

        data = {"scheduled_transaction": scheduled_transaction_data}

        result = await self._make_request_with_retry("post", url, json=data)

        txn = result["data"]["scheduled_transaction"]

        return {
            "id": txn["id"],
            "date_first": txn.get("date_first"),
            "date_next": txn.get("date_next"),
            "frequency": txn.get("frequency"),
            "amount": txn["amount"] / 1000 if txn.get("amount") else 0,
            "memo": txn.get("memo"),
            "flag_color": txn.get("flag_color"),
            "account_id": txn.get("account_id"),
            "payee_name": txn.get("payee_name"),
            "category_id": txn.get("category_id"),
        }
    except Exception as e:
        raise Exception(f"Failed to create scheduled transaction: {e}") from e

YNAB MCP Server