Savings Analysis¶

The Savings API provides automated rate optimization analysis at the property and portfolio levels. It compares current tariffs against available alternatives and quantifies potential cost savings. All endpoints require authentication and are prefixed with /savings.

GET /savings/property/{property_id}¶

Run a savings analysis for a single property. Compares the property's current tariff against all eligible alternatives based on its service area, usage profile, and demand characteristics.


Auth required	Yes

Path Parameters¶

Parameter	Type	Description
`property_id`	string	Property ID

Example Request¶

curl https://app.meterbase.io/api/v1/savings/property/prop_abc123 \
  -H "Authorization: Bearer $TOKEN"

Example Response¶

200 OK

{
  "property_id": "prop_abc123",
  "property_name": "Sunset Apartments",
  "current_tariff": {
    "id": "trf_sce_tou_gs2",
    "name": "SCE TOU-GS-2",
    "utility_name": "Southern California Edison",
    "estimated_annual_cost": 37800.00,
    "effective_rate_per_kwh": 0.210
  },
  "best_alternative": {
    "id": "trf_sce_tou_gs3",
    "name": "SCE TOU-GS-3",
    "utility_name": "Southern California Edison",
    "estimated_annual_cost": 34200.00,
    "effective_rate_per_kwh": 0.190
  },
  "annual_savings": 3600.00,
  "monthly_savings": 300.00,
  "savings_percent": 9.5,
  "alternatives_analyzed": 6,
  "all_alternatives": [
    {
      "tariff_id": "trf_sce_tou_gs3",
      "name": "SCE TOU-GS-3",
      "estimated_annual_cost": 34200.00,
      "annual_savings": 3600.00,
      "savings_percent": 9.5
    },
    {
      "tariff_id": "trf_sce_tou_gs1",
      "name": "SCE TOU-GS-1",
      "estimated_annual_cost": 39600.00,
      "annual_savings": -1800.00,
      "savings_percent": -4.8
    },
    {
      "tariff_id": "trf_sce_flat_gs",
      "name": "SCE Flat-GS",
      "estimated_annual_cost": 41400.00,
      "annual_savings": -3600.00,
      "savings_percent": -9.5
    }
  ],
  "recommendation": "Switch to SCE TOU-GS-3 to save an estimated $3,600/year (9.5% reduction).",
  "analyzed_at": "2026-03-25T14:30:00Z"
}

Prerequisites

The property must have tariff_id and monthly_usage_kwh set. If monthly_demand_kw is also provided, demand tariffs will be included in the analysis.

Error Cases¶

Status	Detail	Cause
`404`	`"Property not found"`	Invalid or inaccessible property ID
`400`	`"Property has no current tariff assigned"`	`tariff_id` is not set
`400`	`"Property has no usage data"`	`monthly_usage_kwh` is not set

GET /savings/portfolio/{portfolio_id}¶

Run a savings analysis across all properties in a portfolio. Returns aggregate savings and per-property breakdowns.


Auth required	Yes

Path Parameters¶

Parameter	Type	Description
`portfolio_id`	string	Portfolio ID

Example Request¶

curl https://app.meterbase.io/api/v1/savings/portfolio/pf_abc123 \
  -H "Authorization: Bearer $TOKEN"

Example Response¶

200 OK

{
  "portfolio_id": "pf_abc123",
  "portfolio_name": "West Coast Holdings",
  "total_properties": 12,
  "properties_analyzed": 10,
  "properties_skipped": 2,
  "skip_reasons": [
    { "property_id": "prop_skip1", "reason": "No tariff assigned" },
    { "property_id": "prop_skip2", "reason": "No usage data" }
  ],
  "current_annual_cost": 585000.00,
  "optimized_annual_cost": 550800.00,
  "total_annual_savings": 34200.00,
  "total_savings_percent": 5.8,
  "properties_with_savings": 8,
  "property_savings": [
    {
      "property_id": "prop_002",
      "property_name": "Harbor View Plaza",
      "current_tariff": "SCE TOU-GS-2",
      "recommended_tariff": "SCE TOU-GS-3",
      "current_annual_cost": 96000.00,
      "optimized_annual_cost": 87600.00,
      "annual_savings": 8400.00,
      "savings_percent": 8.75
    },
    {
      "property_id": "prop_005",
      "property_name": "Oakwood Residences",
      "current_tariff": "PGE E-19",
      "recommended_tariff": "PGE B-19",
      "current_annual_cost": 72000.00,
      "optimized_annual_cost": 66000.00,
      "annual_savings": 6000.00,
      "savings_percent": 8.33
    },
    {
      "property_id": "prop_001",
      "property_name": "Sunset Apartments",
      "current_tariff": "SCE TOU-GS-2",
      "recommended_tariff": "SCE TOU-GS-3",
      "current_annual_cost": 37800.00,
      "optimized_annual_cost": 34200.00,
      "annual_savings": 3600.00,
      "savings_percent": 9.52
    }
  ],
  "analyzed_at": "2026-03-25T14:35:00Z"
}

Skipped Properties

Properties without a tariff_id or monthly_usage_kwh are skipped and listed in skip_reasons. They are not included in savings totals.

Error Cases¶

Status	Detail	Cause
`404`	`"Portfolio not found"`	Invalid or inaccessible portfolio ID
`400`	`"Portfolio has no properties"`	Portfolio is empty