SolarCost estimates electricity bills in Home Assistant using solar generation, household consumption, grid import and grid export. Enter your electricity tariff to track energy costs, export credit and optional fixed charges across daily, weekly, monthly and yearly periods.
SolarCost is available in the Home Assistant Marketplace: search for SolarCost to install it. It runs locally inside Home Assistant and is configured through the UI. No separate Supervisor app or SolarCost cloud account is required.
Tracking starts when you finish setup. SolarCost does not import energy history recorded before installation. Bill estimates show charges accrued so far, rather than a forecast of the final bill.
- Home Assistant 2026.9.0 or later.
- Four separate cumulative energy sensors for solar generation, household consumption, grid import and grid export.
- Your supplier's import prices, export payment and any applicable tariff times or fixed charges.
- Home Assistant 2026.11 or later for the built-in Marketplace; manual installation is also supported on earlier supported versions.
The Marketplace is built into Home Assistant 2026.11 and later. The integration and dashboard card are distributed together.
- Open Settings → Marketplace as an administrator and search for SolarCost.
- Accept the Marketplace notice if prompted, then select SolarCost → Install, review the version and confirm Install.
- Follow the setup flow that opens, using the setup steps below. If you close it, open Settings → Devices & services → Add integration → SolarCost later. Restart only if Home Assistant asks you to.
Already installed through HACS? Home Assistant migrates installed projects and custom repositories automatically when you upgrade to 2026.11; you do not need to reinstall SolarCost.
If SolarCost does not appear in your Marketplace search results, add it from its repository link:
- Open Settings → Marketplace → Add from link.
- Enter
https://github.com/jouwdan/SolarCostunder GitHub link and select Add. Connect your GitHub account if prompted; custom repositories require this connection. If asked for a type, choose Integration and select Add again. - Open SolarCost, then follow the installation steps above from step 2.
- Download solarcost.zip from the latest release.
- Create
custom_components/solarcostin your Home Assistant configuration directory and extract the ZIP's contents directly into it. - Check that the resulting path is
custom_components/solarcost/manifest.json, without an extra nestedsolarcostfolder. - Restart Home Assistant, then open Settings → Devices & services → Add integration → SolarCost.
No configuration.yaml entry is needed.
If you download GitHub's Source code archive instead, copy its custom_components/solarcost folder into your configuration's custom_components folder. The attached solarcost.zip contains only the integration files, with manifest.json at the ZIP root.
Enter a name, a three-letter currency code such as EUR, GBP or USD, and select these four sensors:
| Field | Sensor to select |
|---|---|
| Solar generation energy meter | Total energy produced by your solar panels |
| Home consumption energy meter | Total energy used by your household |
| Grid import energy meter | Total energy purchased from the grid |
| Grid export energy meter | Total energy sent to the grid |
Each sensor must use Wh, kWh or MWh and have a state class of total or total_increasing. Use a different sensor for each field. Prefer counters that report small energy increments frequently. Some inverter lifetime counters only advance in whole kWh, even when displayed with decimal places; SolarCost then has to wait for each 1 kWh increase. Daily counters can offer finer resolution and also work when their resets are reported correctly.
Select energy sensors, not instantaneous power sensors measured in W or kW. If your system only provides power sensors, first create Home Assistant Integral helpers to convert power readings into cumulative energy. Yesterday's totals, rolling totals, signed net import/export sensors and SolarCost's own sensors are not suitable sources.
For homes with batteries, use a measured household-consumption sensor. Calculating consumption as solar generation + grid import − grid export does not account for battery charging and discharging.
Check your Home Assistant time zone before setup. SolarCost keeps the currency and time zone selected at creation for that ledger; changing either requires a new setup with separate history.
SolarCost preserves fractional energy: 0.001 kWh = 1 Wh. Watts (W) measure current power; watt-hours (Wh) measure energy accumulated over time. If your source jumps in whole kWh, adding display decimals will not make the readings more precise.
For smoother estimates, use Home Assistant's built-in Integral helpers to accumulate energy from frequently updated power sensors. In Settings → Devices & services → Helpers → Create helper → Integral, select a power source in W, metric prefix k, integration time hours, precision 6, method Left, and a maximum sub-interval of 1 minute. This also accumulates energy while power remains constant. Repeat for solar, household consumption, import and export, then select the resulting energy helpers in SolarCost's Configure → Energy meters menu and save.
Import and export must be separate non-negative power sources. If your meter provides a signed grid-power sensor, the included power_meters.yaml package splits it and creates all four Integral helpers:
- Copy the file to your Home Assistant configuration directory as
solarcost_power.yaml. - Replace
sensor.solar_power,sensor.home_powerandsensor.grid_powerwith your W sensors. Verify the grid sensor's sign during known import or export. The example expects positive grid power for import and negative for export; reverse the signs in the two grid templates if your meter uses the opposite convention. - Include the package in
configuration.yamlas shown below. Merge with any existinghomeassistant/packagesconfiguration rather than creating duplicate keys. - Check the configuration and restart Home Assistant. In SolarCost's energy meter settings, select SolarCost Solar Meter, SolarCost Usage Meter, SolarCost Import Meter and SolarCost Export Meter, then save. If helper IDs already exist, use the actual IDs from your entity list in the package.
homeassistant:
packages:
solarcost_power: !include solarcost_power.yamlChoose either existing energy meters or these helpers for each source; do not add both together. Switching sources preserves recorded totals and establishes new baselines. Power-derived energy is still an estimate: its accuracy depends on sampling frequency, and it cannot recover energy used while Home Assistant or the power source is offline. Keep the edited package outside custom_components so integration updates do not overwrite it.
Enter prices in your chosen currency. For example, enter 0.30 for a price of 30 cents per kWh.
| Setting | What to enter |
|---|---|
| Base import price per kWh | The price you pay outside any configured time bands |
| Base export payment per kWh | The payment you receive outside any configured time bands; use 0 if exports are unpaid |
| Daily standing charge | Optional fixed charge per day; leave at 0 if unused |
| Monthly levy / fixed charge | Optional fixed charge per calendar month; leave at 0 if unused |
| Extra VAT for tax-exclusive prices | Leave at 0 for prices that already include VAT; otherwise enter the percentage to add |
| Import energy discount | Optional percentage discount on imported energy; leave at 0 if unused or already included in your entered prices |
| Number of months to track | The size of the Last N months reporting window; default 12, maximum 1,200 |
| Number of years to track | The size of the Last N years reporting window; default 5, maximum 100 |
VAT-inclusive prices are the default. The optional VAT adjustment applies to discounted import costs, standing charges and monthly fixed charges. If you use it, enter those prices consistently before VAT. SolarCost does not apply VAT or discounts to export payments.
A positive export payment creates a credit that reduces the bill. Negative import and export prices are also supported.
The month and year settings control reporting windows, not data retention. Recorded history is kept when you change these settings.
For a flat-rate tariff, choose Save without adding bands. The base prices will apply all day.
For a time-of-use tariff, choose Add a time band and enter a unique name, start time, end time, starting weekdays, import price and export payment. Add up to 48 non-overlapping bands, then choose Save. If your export payment is constant, enter the same export price in every band.
Bands use local time and whole minutes. The start time is included; the end time is excluded. For a band crossing midnight, the selected weekday is the day the band starts. For example, a Monday band from 22:00 to 01:00 ends on Tuesday morning.
A cheaper EV period inside a night tariff needs separate night bands on either side so the times do not overlap. This example uses illustrative prices in currency units per kWh, with VAT already included:
| Rate or band | Applies | Import price | Export payment |
|---|---|---|---|
| Base rate | All times outside the bands below | 0.30 | 0.10 |
| Night before EV | Every day, 22:00–01:00 | 0.15 | 0.10 |
| EV | Every day, 01:00–04:00 | 0.08 | 0.10 |
| Night after EV | Every day, 04:00–07:00 | 0.15 | 0.10 |
| Peak | Every day, 16:00–19:00 | 0.40 | 0.10 |
Replace these example prices and times with your own tariff. SolarCost starts tracking when you save the completed setup.
Most users can skip this feature: the usual setup still goes from energy meters to rates, optional time bands, then Save. For a provider that uses monthly consumption categories and progressive unit blocks, choose Monthly consumption blocks (advanced) from the time-band menu, or later from Configure.
Enable Use monthly consumption blocks, then add categories and their nested blocks using the native forms. Each category has a unique name, an upper monthly grid-import limit, and a list of progressive blocks. Each block has an upper cumulative kWh limit, an import price, and an optional monthly fixed fee. Enter limits in increasing order; leave the final category and its final block unlimited. A single unlimited category also supports an ordinary progressive tariff without category changes.
Limits are inclusive and measure cumulative grid import, not home consumption or import minus export. For example, limits of 30 and 60 mean the first 30 kWh and the next 30 kWh. The month resets at local midnight on the first day, using the ledger's time zone. Base import prices and time bands are inactive while blocks are enabled; the base export payment still applies. Disabling blocks restores standard pricing and retains the block configuration for reuse.
The illustrative schedule from issue #6 is also included in block_tariff.json. These are example prices, not a statement of current supplier rates. Its completed-month import charges and selected monthly fixed fees are:
| Imported kWh | Import charge | Monthly fixed fee |
|---|---|---|
| 30 | 150 | 80 |
| 60 | 420 | 210 |
| 61 | 860 | 400 |
| 90 | 1,440 | 400 |
| 120 | 2,280 | 1,000 |
| 180 | 4,920 | 1,500 |
| 181 | 5,950 | 2,500 |
The selected fixed fee accrues daily, using the actual days in that calendar month, rather than being charged in full immediately. Existing daily standing charges and additional monthly levies still apply; leave them at zero if the tier fee already covers them. Discounts apply to imported energy, and optional VAT applies to imported energy and fixed fees. Export payments remain separate.
Crossing a category threshold can change prices for earlier imported units and accrued tier fees in the same month. Daily sensors, history and date-range reports therefore remain provisional for an open month. Once the month is complete, its category stops changing with later months' consumption. Recorded tariff versions are retained: editing prices affects future energy and fee accrual, and does not replace the schedules used for earlier intervals. Consumption already recorded in the month still counts toward its block positions when switching models or changing tariffs.
The Costs view shows the category and consumption ranges for each import block. Current rates shows the current block's unit price and month-to-date import; that unit price excludes the additional effect of repricing earlier units at a category transition. Custom report dates select stored days without restarting the monthly block counters.
Tracking partway through a month cannot recover earlier unrecorded consumption, so its category and bill may be understated. Non-calendar supplier billing cycles are not supported by this monthly model. Version 0.3.0 upgrades the ledger schema while preserving existing totals; reverting to an older integration requires restoring a pre-upgrade database backup.
One card, one selected period. Switch between the energy overview, time-of-use costs and interactive bill or energy history. These screenshots use example data, not a household's readings.
The included SolarCost card brings energy, bill estimates, tariff costs and history into one card. It loads automatically with the integration; no separate frontend plugins or Recorder statistics are required.
- Refresh your browser after setup. After an update, restart Home Assistant first; also restart if Home Assistant requests it during installation.
- Open your dashboard and choose Edit → Add card → By card, then search for SolarCost.
- In the visual editor, choose your SolarCost bill sensor and optionally set a title or time-band display labels. Check the preview and save.
You can also choose Manual and paste the card template:
type: custom:solarcost-card
entity: sensor.solarcost_this_month_estimated_billChoose any Estimated bill sensor belonging to your SolarCost setup. Its reporting period is selected initially; the card finds the setup's other periods and current rates automatically, even if you rename their entity IDs or change your month/year windows. Look up the bill sensor under Settings → Devices & services → SolarCost → Entities. For multiple SolarCost setups, add a card for each setup. An optional title changes the card heading.
Use the period selector for Today, This week, This month, Last month, your configured month/year windows or All time. Every view follows the same selected period:
- Summary: a prominent estimated bill or credit, plus solar generation and home usage in kWh. Expand Grid exchange for grid import, export, imported electricity cost and export credit.
- Costs: horizontal bars compare costs by time-of-use band, with each band's kWh underneath. A green export-credit bar underneath uses the same scale to show the offset against imports. The bill breakdown includes standing charges, monthly fees and export credit. Expand Current rates to see the effective import and export prices now.
- History: switch between bill and energy charts, then select a date’s bars for exact amounts below the chart. With only one recorded period, its details are already shown. Short ranges use daily bars, medium ranges use months, and long ranges use years. Credit amounts extend below zero. Charts read SolarCost's own stored ledger.
For a two-month bill, choose Custom dates, enter the supplier's start and end dates, then select Apply. Both dates are included. Overview, Costs and History all use that report. Custom reports are snapshots; select Apply again to refresh them. Standard reporting periods update automatically.
When upgrading from the earlier dashboard template, replace the entire SolarCost vertical stack with the short configuration above. The older standalone custom:solarcost-tou-card remains supported. You can still build other dashboards using the individual SolarCost sensors.
The card waits for Home Assistant's frontend to finish registering its root element before registering itself. This prevents intermittent Custom element not found: solarcost-card errors during startup. After updating, restart Home Assistant and refresh the dashboard to load the new card. The card also follows optional --echo-* theme variables, with Home Assistant defaults when they are absent, and preserves the earlier custom:echo-solarcost-card name used by existing dashboards.
For each period, SolarCost provides solar generation, energy usage, grid import, grid export, import cost, export credit, standing charges, monthly fixed charges and the estimated bill.
| Period | Covers, in the configured local time zone |
|---|---|
| Today | Local midnight to now |
| This week | Monday midnight to now |
| This month | First day of this month to now |
| Last month | First through last day of the previous calendar month |
| Last N months | First day of the month N−1 months ago to now |
| This year | January 1 to now |
| Last N years | January 1 of the year N−1 years ago to now |
| All time | First setup to now |
Last N months and Last N years include the current partial calendar period. For example, Last 3 months during September includes July, August and September so far. They are not fixed 30-day or 365-day windows.
Last month is a separate completed calendar month. If you are billed every two months, you can compare it with This month, or set Number of months to track to 2 for a combined previous-and-current-month total. Use a date-range report when your supplier's billing dates differ from calendar months.
Estimated bill = import cost + standing charges + monthly fixed charges − export credit
A negative estimated bill means net credit. Amounts include the configured discount and VAT adjustment. Standing charges accrue through each day; monthly charges accrue across the actual days in each month. Setup partway through a day or month only includes charges from the tracking start time.
The Current import rate sensor shows the active import price after configured discounts and VAT. Current export rate shows the active export payment. Together with the period sensors, SolarCost creates 74 sensors per setup.
Every Import cost and Estimated bill sensor includes a time_of_use attribute with imported kWh and cost for each configured band, such as EV, Night or Peak. base means the price outside your time bands (often Day); named bands use keys such as band:EV. Costs include the discount and VAT applied when the energy was recorded. Export credit, standing charges and monthly fees remain separate.
The card's Costs view shows one reporting period at a time. Bars compare absolute costs, preserving minus signs for import credits. Bands with no imported energy are omitted. The smaller kWh figures show how much energy was billed at each rate. Nonzero amounts below one cent use up to six decimal places so small charges do not appear free.
Use Time-band labels in the visual editor, or add band_names in YAML, to relabel or combine bands for display. Bands mapped to the same name are added together in the chart; the ledger and reports retain the original bands. For example:
band_names:
base: Day
"band:Night before EV": Night
"band:Night after EV": NightBand names identify historical buckets: changing a band's rate preserves its previous costs, while renaming or removing a band keeps its recorded amounts under the old name. Separate time bands remain separate rows even if their prices match.
Time-band detail starts when version 0.1.3 or later first runs. Earlier imported energy and costs remain in an Unallocated row because older daily totals contain no time-band detail; they are never repriced or guessed. The time_of_use_since attribute shows when detailed tracking started. These breakdowns are stored in SolarCost's daily ledger rather than Home Assistant Recorder attributes, keeping long-term storage proportional to days and bands rather than meter updates.
Open a bill sensor's attributes to see its cost breakdown, tracking start and meter status. partial_history: true means that the requested period starts before SolarCost began recording. Weekly, monthly and yearly totals may therefore match when you first install it.
If a period ends before tracking began, its sensors show Unknown and has_history: false. For example, Last month has no history immediately after installation. Once a month has been recorded, the Last month sensors update automatically at the start of the next month. A partly recorded month shows its available totals with partial_history: true.
Open Settings → Devices & services → SolarCost → Configure. Choose Rates and reporting periods, Time-of-use bands or Energy meters, make your changes, then choose Save changes.
Saved tariff changes apply going forward. Previously recorded intervals keep their original tariff schedules; changing a rate does not recalculate old bills. With monthly blocks, a later category threshold can still reprice earlier intervals in the same month using their recorded schedules. Changing a source meter keeps recorded totals and establishes a new starting reading for that source.
Use this menu when your supplier changes prices or you replace a meter. Currency and time zone remain fixed for the existing ledger.
Use the SolarCost: Get bill report action to check a supplier's billing period or compare completed days, weeks, months or years.
- Open Developer tools → Actions and select SolarCost: Get bill report.
- Select the SolarCost integration to query.
- Enter the start and end dates. Both dates are included, in the ledger's local time zone.
- Choose grouping by day, week, month or year, then perform the action.
The response contains totals, a breakdown for each grouped period, currency, time zone, tracking start and partial-history information. time_of_use contains imported kWh and costs by band for the full date range and each grouped period. Weeks start on Monday. The end date must be today or earlier, and a request can cover up to 100 years. Only data recorded since setup is available; a report ending today includes charges recorded so far.
For an automation, use an action such as:
action: solarcost.get_report
data:
config_entry_id: YOUR_SOLARCOST_ENTRY_ID
start: "2026-01-01"
end: "2026-01-31"
group_by: month
response_variable: electricity_billReplace the entry ID and dates with your own values. The visual action editor lets you select your SolarCost integration without entering its ID manually. In an automation, the response is available in the electricity_bill variable for subsequent actions.
SolarCost estimates when energy was used by spreading the increase between consecutive meter readings across the elapsed time. It splits that energy at tariff changes and local day boundaries. Frequent meter updates improve accuracy, particularly around tariff changes.
- Daylight-saving changes are handled in the configured time zone. Both occurrences of a repeated hour use the same local tariff, and a full local day accrues one daily standing charge.
- Missing or unavailable readings leave existing totals visible. Later cumulative readings can recover energy used during a gap, but cannot reveal its exact timing. Energy lost by a meter resetting during an outage cannot always be recovered.
- Decreases in a
total_increasingsensor are treated as resets. Decreases in atotalsensor establish a new baseline without subtracting previous charges. A faulty meter briefly reporting zero can resemble a reset. - Supplier rounding, billing-specific levies, meter corrections and additional credits can cause differences from an invoice.
- Opening balances, payments, one-off credits, tiered usage prices and demand charges are not included.
SolarCost keeps its own daily history independently of Home Assistant's Recorder cleanup. The included card uses this ledger; any separate dashboard charts you build with Home Assistant statistics still depend on Recorder.
Published GitHub releases are the update source for Marketplace. Install available updates through Settings → Updates, then restart Home Assistant when prompted by the repair. For manual installations, replace the integration files with the new version and restart. Refresh dashboard browsers to load the matching card version. You do not need to remove or re-add the integration.
Include the solarcost folder in your Home Assistant configuration directory in backups. Its databases are stored as solarcost/<config_entry_id>.db. For a manual file copy, stop Home Assistant first so the database is not being written during the copy.
Removing the integration does not delete its stored history. Adding it again creates a separate ledger; it does not automatically reconnect to the old database. Keep backups of old ledgers if you need their history.
| Problem | What to check |
|---|---|
| SolarCost is missing from Add integration | Restart Home Assistant and check the installation path. manifest.json must be directly inside custom_components/solarcost. |
| A meter is rejected or missing from the selector | Check that it is an energy sensor in Wh, kWh or MWh with state class total or total_increasing. Use four distinct sensors. |
| Energy totals start at zero | This is expected. SolarCost starts from each meter's current reading and counts subsequent increases. Earlier meter totals are not imported. |
| Energy advances only in whole kWh | Check the source meter's history. If it also jumps by 1 kWh, use a finer-resolution energy meter or the power-to-energy helpers described above. SolarCost does not round energy to whole kWh. |
| The dashboard says Entity not found | Replace the example entity ID with the one shown in your SolarCost entity list. |
| The card or chart is missing | Restart Home Assistant after upgrading and refresh the browser. Check that the configured entity is a SolarCost estimated-bill sensor. History begins at installation; earlier periods have no recorded data. |
| A bill has partial history or several periods show the same total | The period may start before SolarCost was installed. Check the bill sensor's tracking_since and partial_history attributes. |
| Costs stop updating | Check the source sensors. A bill sensor's source_status and meter_diagnostics attributes show unavailable or invalid sources and the last accepted readings. |
| The active rate looks wrong | Check the local time zone, selected weekdays and band boundaries. The current import rate already includes configured discounts and VAT. |
| VAT or a discount appears to be applied twice | Leave the corresponding adjustment at 0 if it is already included in the prices you entered. |
For problems that remain, check Settings → System → Logs and open an issue. Include your Home Assistant and SolarCost versions, the steps to reproduce the problem, and relevant logs with credentials and personal details removed.
Pull requests run accounting and card tests, an installable-archive check, a Home Assistant lifecycle test, Hassfest and HACS validation (the publisher checks still used by Marketplace). The same checks run weekly and before every release. See the maintainer guide for local checks, the one-click release process, deployment and rollback, and submission to the Marketplace catalog.
SolarCost is available under the MIT License.