AmeriGas Home Assistant Integration

HACS custom component for monitoring your AmeriGas propane account. Track tank levels, deliveries, payments, and integrate with the Energy Dashboard.

Some users with correct credentials were seeing a generic "Invalid authentication" error when adding the integration. AmeriGas's login endpoint returns the same shape of failure response (success: false) both for genuinely wrong credentials and for requests it suspects are automated — previously, the integration treated both cases identically and always reported "Invalid authentication."

The integration now checks the portal's actual rejection message. A recognized bad-credentials message (e.g. "The User ID or password is incorrect") still shows Invalid username or password. Any other rejection — most commonly AmeriGas's automated-traffic response, "Sorry, we are unable to process your request at this time" — now shows a distinct AmeriGas rejected this login attempt as automated traffic error instead, so you're not told to re-check a password that may be correct.

This does not fix the underlying automated-traffic rejection itself — see the Troubleshooting section below and the v3.2.3 notes for that work.

Added comprehensive tests for _calculate_used_since_delivery, including a guard (if not self.coordinator.data:) that prevents an AttributeError when the coordinator has no data yet. Builds on the tests/ package introduced in v3.2.0.

Will-call customers with a billing address separate from their tank location were seeing the local AmeriGas district office address in sensor.amerigas_propane_service_address rather than their actual tank address. This is a data limitation of accountSummaryViewModel — for will-call accounts, that JSON blob contains district billing fields, not the customer's delivery address.

A new sensor.amerigas_propane_delivery_address sensor is added. It parses the delivery address directly from the dashboard HTML, capturing the actual tank location regardless of account type. sensor.amerigas_propane_service_address is unchanged.

Pre-delivery level entity lookups now use async_get_entity_id() instead of scanning the full entity registry on every call. No behavioral change — this is a performance and correctness improvement.

Added tests/ package with boundary condition tests for _calculate_gallons_remaining and API initialization.

• Tank Level — current percentage and gallons remaining
• Days Remaining — estimated days until empty based on your actual usage
• Delivery Tracking — last and next delivery dates and amounts
• Cost Tracking — cost per gallon, cost since last delivery, estimated refill cost

• Automatic Pre-Delivery Capture — 100% accurate for any delivery size, zero configuration
• Lifetime Consumption — total propane used since installation, protected against data loss
• Daily Average Usage — your average consumption per day
• Energy Dashboard Integration — track propane alongside electricity and other utilities

• Lifetime sensors never reset to 0 on HA restart (race condition fixed)
• Data persists through API outages and integration reloads
• Energy Dashboard historical data permanently protected

• All sensors share the same pre-delivery level; changing it updates everything instantly
• Days Until Empty works correctly for any usage rate, including vacation homes
• Calculation transparency via sensor attributes

-OR-

1. Open HACS → Integrations
2. Search for "AmeriGas Propane"
3. Install and restart Home Assistant

1. Download the latest release from GitHub Releases
2. Copy custom_components/amerigas to your config/custom_components/ directory
3. Restart Home Assistant

1. Settings → Devices & Services → + Add Integration
2. Search "AmeriGas" and select it
3. Enter your MyAmeriGas account credentials and click Submit

If your password changes, go to Settings → Devices & Services → AmeriGas → Configure and re-enter your credentials. No restart needed and no historical data is lost.

API sensors (16): tank level, tank size, days remaining, amount due, account balance, last/next delivery date and gallons, last payment date/amount, last tank reading, auto-pay status, paperless billing, account number, service address, delivery address

Calculated sensors (11): gallons remaining, used since last delivery, energy consumption (display), daily average usage, days until empty, days since last delivery, cost per gallon, cost per cubic foot, cost since last delivery, estimated refill cost, days remaining difference

Lifetime sensors (2): Propane Lifetime Gallons, Propane Lifetime Energy (for Energy Dashboard)

Diagnostic entity (1): Pre-Delivery Tank Level number entity — auto-captured on each delivery, manually adjustable

1. Settings → Dashboards → Energy → Add Gas Source
2. Select Propane Lifetime Energy (sensor.propane_lifetime_energy)
3. Click Save

Update to v3.0.8 or later before using the Energy Dashboard to ensure historical data is never lost to the startup race condition.

The integration uses two independent triggers to detect a delivery:

Trigger 1 — Level-jump (telemetry-first): Fires immediately when the tank monitor reports an increase ≥ 10 gallons between consecutive coordinator polls. Captures both pre-fill and post-fill directly from the tank monitor — the most accurate baseline, independent of portal lag.

Trigger 2 — Date-change (API confirmation): Fires when last_delivery_date changes. If the level-jump trigger already captured the fill, this path confirms and skips re-capture. Otherwise it calculates pre_delivery = current_level - last_delivery_gallons. Capture is deferred if last_delivery_gallons hasn't updated yet in the same poll, firing on a subsequent poll once both values are current.

The captured pre-delivery level is stored in number.amerigas_pre_delivery_level and used by all consumption sensors. All sensors recalculate immediately when this value changes.

Example (level-jump path):

Pre-fill (tank monitor):  145 gal  ← captured at delivery time
Post-fill (tank monitor): 420 gal  ← captured at delivery time

Used since delivery:  420 - 395 (current) = 25 gal  ✅ (accuracy: 100%, tank monitor)

Example (API fallback path):

Post-delivery level:  420 gal
Delivery amount:      255.9 gal
Pre-delivery level:   164.1 gal  ← auto-captured once portal updates

Used since delivery:  420 - 395 (current) = 25 gal  ✅ (accuracy: ~95%, API)

Manually set the pre-delivery level — useful for deliveries that occurred before v3.0.5 or if auto-capture failed.

service: amerigas.set_pre_delivery_level
data:
  gallons: 145.0

Force an immediate API fetch instead of waiting for the next scheduled refresh.

service: amerigas.refresh_data

Data refreshes automatically at 00:00, 06:00, 12:00, and 18:00 daily, plus immediately on HA startup. Use amerigas.refresh_data to trigger an on-demand update.

Login fails with "AmeriGas rejected this login attempt as automated traffic" (or, on v3.2.1 and earlier, a generic "Invalid authentication" even with correct credentials) — AmeriGas's login endpoint occasionally flags non-browser requests as suspicious traffic and rejects them, independent of whether your username/password are correct. This is not a credentials problem. Things to try:

• Double check your credentials work by logging in directly at myamerigas.com in a normal browser first.
• Retry adding the integration — this rejection has been reported to be intermittent for some accounts.
• Check the Home Assistant logs (custom_components.amerigas) for the exact message AmeriGas returned; it's logged at WARNING level to help with diagnosis.
• If this persists, please comment on issue #38 with your log line (redact your email/username first) — ongoing work to make the login request look more like a real browser is tracked there.

Service address showing wrong address (Billing address instead of your tank location) — Fixed in v3.2.0 for some customers. After updating, use sensor.amerigas_propane_delivery_address for your tank location. sensor.amerigas_propane_service_address reflects the accountSummaryViewModel JSON data and is unchanged.

Sensors show wrong values right after a delivery — If the integration was not running at delivery time (e.g. you just installed v3.1.1), the level-jump trigger could not fire. Set the pre-delivery level manually: amerigas.set_pre_delivery_level with the tank level in gallons immediately before the delivery. Sensors correct immediately.

Cost per gallon looks wrong after a delivery — Expected until the invoice is paid. v3.1.1 automatically uses account_balance or amount_due as the cost basis when last_payment_date predates last_delivery_date. Once payment is recorded, it reverts to the standard calculation.

Need to update your password? — Use Settings → Devices & Services → AmeriGas → Configure (v3.1.0+). No reinstall required.

Daily Average Usage unit change prompt in Statistics — Expected after upgrading to v3.1.0. Go to Developer Tools → Statistics, find propane_daily_average_usage, and accept the unit fix. Safe to confirm.

Date sensors showing the wrong day (one day early) — Fixed in v3.0.11. Update and restart.

Next delivery date entity missing / HA prompting you to delete it — Fixed in v3.0.11. Update and restart; the entity will be recreated automatically.

Lifetime sensors reset to 0 on restart — Fixed in v3.0.8. Update immediately. After updating, check logs for State restoration complete. Lifetime total: XXX.XX gal.

Sensors not updating after setting pre-delivery level — Fixed in v3.0.7. Verify you are on v3.0.7+ and restart.

Daily Average Usage shows 0.0000 gal/day — Fixed in v3.0.7. Check that the pre-delivery level entity has a non-zero value and that the calculation_method attribute shows auto_captured or tank_monitor.

Days Until Empty shows a very large number — Expected for low-usage installations (e.g. vacation homes). The sensor caps at 9,999 days for usage below 0.001 gal/day. Check the calculation attribute for the exact math.

API timeouts / sensors unavailable — Timeout is 45 seconds (raised in v3.0.8). If timeouts persist, use amerigas.refresh_data to retry manually.

Finding the pre-delivery level entity — Developer Tools → States → search pre_delivery.

type: entities
title: Propane Tank
entities:
  - entity: sensor.amerigas_tank_level
    name: Tank Level
  - entity: sensor.amerigas_tank_gallons_remaining
    name: Gallons Remaining
  - entity: sensor.amerigas_used_since_last_delivery
    name: Used Since Delivery
    secondary_info: attribute:accuracy
  - entity: sensor.amerigas_daily_average_usage
    name: Daily Average
  - entity: sensor.amerigas_days_until_empty
    name: Days Until Empty
    secondary_info: attribute:calculation
  - type: divider
  - entity: sensor.amerigas_estimated_refill_cost
    name: Est. Refill Cost
  - entity: sensor.amerigas_cost_since_last_delivery
    name: Cost Since Delivery
  - entity: sensor.amerigas_last_delivery_date
    name: Last Delivery
  - entity: sensor.amerigas_next_delivery_date
    name: Next Delivery

No breaking changes, including the v3.2.1 test-coverage patch. Update via HACS and restart. All sensors, entities, and automations continue working without modification.

See MIGRATION.md for detailed instructions.

See CONTRIBUTING.md. Bug reports and PRs welcome via GitHub Issues and Discussions.

MIT License — see LICENSE

Unofficial integration, not affiliated with AmeriGas. Use at your own risk. Always verify propane levels manually. May break if AmeriGas changes their website.

Built for Home Assistant. Thanks to all contributors (@Ricket and others) and to the community for testing and feedback.