Bills
The Bills API manages utility bills for properties. Bills can be created manually, uploaded as PDFs for AI-powered extraction, or imported in bulk. All endpoints require authentication and are prefixed with /bills.
POST /bills
Create a bill manually by providing structured data.
Request Body
| Field |
Type |
Required |
Description |
property_id |
string |
Yes |
Property this bill belongs to |
billing_period_start |
string |
Yes |
Start date (YYYY-MM-DD) |
billing_period_end |
string |
Yes |
End date (YYYY-MM-DD) |
total_amount |
number |
Yes |
Total bill amount in USD |
total_usage_kwh |
number |
Yes |
Total energy consumed in kWh |
peak_demand_kw |
number |
No |
Peak demand in kW |
energy_charge |
number |
No |
Energy charge portion in USD |
demand_charge |
number |
No |
Demand charge portion in USD |
fixed_charge |
number |
No |
Fixed/service charge in USD |
taxes_and_fees |
number |
No |
Taxes and fees in USD |
tariff_id |
string |
No |
Tariff the bill was calculated under |
utility_name |
string |
No |
Name of the utility |
account_number |
string |
No |
Utility account number |
notes |
string |
No |
Freeform notes |
Example Request
curl -X POST https://app.meterbase.io/api/v1/bills \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"property_id": "prop_abc123",
"billing_period_start": "2026-02-01",
"billing_period_end": "2026-02-28",
"total_amount": 3247.85,
"total_usage_kwh": 16200,
"peak_demand_kw": 48.5,
"energy_charge": 2430.00,
"demand_charge": 485.00,
"fixed_charge": 125.00,
"taxes_and_fees": 207.85,
"tariff_id": "trf_sce_tou_gs2",
"utility_name": "Southern California Edison",
"notes": "Higher than usual due to HVAC maintenance"
}'
Example Response
201 Created
{
"id": "bill_xyz789",
"property_id": "prop_abc123",
"billing_period_start": "2026-02-01",
"billing_period_end": "2026-02-28",
"total_amount": 3247.85,
"total_usage_kwh": 16200,
"peak_demand_kw": 48.5,
"energy_charge": 2430.00,
"demand_charge": 485.00,
"fixed_charge": 125.00,
"taxes_and_fees": 207.85,
"tariff_id": "trf_sce_tou_gs2",
"utility_name": "Southern California Edison",
"account_number": null,
"notes": "Higher than usual due to HVAC maintenance",
"source": "manual",
"created_at": "2026-03-25T14:00:00Z"
}
Error Cases
| Status |
Detail |
Cause |
422 |
"field required" |
Missing required field |
404 |
"Property not found" |
Invalid property_id |
422 |
"billing_period_end must be after billing_period_start" |
Invalid date range |
GET /bills
List bills with optional filters. Results are ordered by billing_period_end descending.
Query Parameters
| Parameter |
Type |
Default |
Description |
property_id |
string |
- |
Filter by property |
start_date |
string |
- |
Minimum billing_period_start (YYYY-MM-DD) |
end_date |
string |
- |
Maximum billing_period_end (YYYY-MM-DD) |
page |
integer |
1 |
Page number |
per_page |
integer |
20 |
Items per page (max 100) |
Example Request
curl "https://app.meterbase.io/api/v1/bills?property_id=prop_abc123&start_date=2026-01-01&end_date=2026-03-31" \
-H "Authorization: Bearer $TOKEN"
Example Response
200 OK
{
"items": [
{
"id": "bill_xyz789",
"property_id": "prop_abc123",
"billing_period_start": "2026-02-01",
"billing_period_end": "2026-02-28",
"total_amount": 3247.85,
"total_usage_kwh": 16200,
"peak_demand_kw": 48.5,
"source": "manual",
"created_at": "2026-03-25T14:00:00Z"
},
{
"id": "bill_abc456",
"property_id": "prop_abc123",
"billing_period_start": "2026-01-01",
"billing_period_end": "2026-01-31",
"total_amount": 2980.50,
"total_usage_kwh": 14800,
"peak_demand_kw": 42.0,
"source": "ai_extracted",
"created_at": "2026-02-15T10:00:00Z"
}
],
"total": 2,
"page": 1,
"per_page": 20,
"pages": 1
}
GET /bills/{id}
Retrieve full details of a single bill.
Path Parameters
| Parameter |
Type |
Description |
id |
string |
Bill ID |
Example Request
curl https://app.meterbase.io/api/v1/bills/bill_xyz789 \
-H "Authorization: Bearer $TOKEN"
Example Response
200 OK
{
"id": "bill_xyz789",
"property_id": "prop_abc123",
"billing_period_start": "2026-02-01",
"billing_period_end": "2026-02-28",
"total_amount": 3247.85,
"total_usage_kwh": 16200,
"peak_demand_kw": 48.5,
"energy_charge": 2430.00,
"demand_charge": 485.00,
"fixed_charge": 125.00,
"taxes_and_fees": 207.85,
"tariff_id": "trf_sce_tou_gs2",
"utility_name": "Southern California Edison",
"account_number": null,
"notes": "Higher than usual due to HVAC maintenance",
"source": "manual",
"created_at": "2026-03-25T14:00:00Z"
}
Error Cases
| Status |
Detail |
Cause |
404 |
"Bill not found" |
Invalid or inaccessible bill ID |
POST /bills/upload
Upload a utility bill PDF for AI-powered data extraction. The system uses OCR and language models to extract billing period, charges, usage, and tariff information.
|
|
| Auth required |
Yes |
| Content-Type |
multipart/form-data |
Request Body (Form Data)
| Field |
Type |
Required |
Description |
file |
file |
Yes |
PDF file of the utility bill (max 10 MB) |
property_id |
string |
Yes |
Property this bill belongs to |
Example Request
curl -X POST https://app.meterbase.io/api/v1/bills/upload \
-H "Authorization: Bearer $TOKEN" \
-F "file=@/path/to/bill.pdf" \
-F "property_id=prop_abc123"
Example Response
201 Created
{
"id": "bill_ai_001",
"property_id": "prop_abc123",
"billing_period_start": "2026-02-03",
"billing_period_end": "2026-03-04",
"total_amount": 3412.67,
"total_usage_kwh": 17050,
"peak_demand_kw": 51.2,
"energy_charge": 2558.00,
"demand_charge": 512.00,
"fixed_charge": 125.00,
"taxes_and_fees": 217.67,
"tariff_id": null,
"utility_name": "Southern California Edison",
"account_number": "3-042-1567-89",
"source": "ai_extracted",
"confidence": 0.94,
"extraction_notes": "All fields extracted successfully. Tariff not matched.",
"created_at": "2026-03-25T14:05:00Z"
}
Extraction Confidence
The confidence field (0.0 to 1.0) indicates how confident the AI is in the extraction. Bills with confidence below 0.8 should be reviewed manually.
Error Cases
| Status |
Detail |
Cause |
400 |
"File must be a PDF" |
Non-PDF file uploaded |
400 |
"File too large (max 10 MB)" |
File exceeds size limit |
404 |
"Property not found" |
Invalid property_id |
422 |
"Could not extract bill data from PDF" |
AI extraction failed |
GET /bills/property/{property_id}/summary
Retrieve monthly cost and usage trends for a property.
Path Parameters
| Parameter |
Type |
Description |
property_id |
string |
Property ID |
Query Parameters
| Parameter |
Type |
Default |
Description |
months |
integer |
12 |
Number of months to include (max 60) |
Example Request
curl "https://app.meterbase.io/api/v1/bills/property/prop_abc123/summary?months=6" \
-H "Authorization: Bearer $TOKEN"
Example Response
200 OK
{
"property_id": "prop_abc123",
"months": [
{
"month": "2025-10",
"total_amount": 2870.00,
"total_usage_kwh": 14200,
"peak_demand_kw": 41.0,
"cost_per_kwh": 0.202
},
{
"month": "2025-11",
"total_amount": 2650.00,
"total_usage_kwh": 13100,
"peak_demand_kw": 38.5,
"cost_per_kwh": 0.202
},
{
"month": "2025-12",
"total_amount": 2920.00,
"total_usage_kwh": 14500,
"peak_demand_kw": 43.0,
"cost_per_kwh": 0.201
},
{
"month": "2026-01",
"total_amount": 2980.50,
"total_usage_kwh": 14800,
"peak_demand_kw": 42.0,
"cost_per_kwh": 0.201
},
{
"month": "2026-02",
"total_amount": 3247.85,
"total_usage_kwh": 16200,
"peak_demand_kw": 48.5,
"cost_per_kwh": 0.200
},
{
"month": "2026-03",
"total_amount": 3412.67,
"total_usage_kwh": 17050,
"peak_demand_kw": 51.2,
"cost_per_kwh": 0.200
}
],
"totals": {
"total_amount": 18081.02,
"total_usage_kwh": 89850,
"avg_monthly_cost": 3013.50,
"avg_cost_per_kwh": 0.201
}
}
Error Cases
| Status |
Detail |
Cause |
404 |
"Property not found" |
Invalid property ID |