Bills

This is the object representing utility bill. This object contains bill data, including usage and pricing.

NOTE: Meter, Bill, and Interval objects have a different format philosophy than Templates, Forms, or Authorizations. Since utility data can be very different across utilities, we try to simplify and contain these differences inside smaller more managable, documented objects called Blocks.

API Endpoints

GET /api/v2/bills List or search your bills

Attributes

Attribute	Format	Description	Example
`uid`	UID String	Unique identifier of the Bill. These uids may appear as integers, but they are not guaranteed to stay that way, so you should treat them as strings.	`"12345b"`
`meter_uid`	UID String	The unique identifier of the Meter object to which this bill object belongs.	`"4847322-1"`
`authorization_uid`	UID String	The Authorization under which the Meter belongs.	`"847372c"`
`created`	ISO8601	When the Bill was created.	`"2016-01-01T12:30:24.653422+00:00"`
`updated`	ISO8601	When the bill data was last updated.	`"2016-01-01T12:30:24.653422+00:00"`
`notes`	List(Bill Note)	List of notes about the Bill. Will be an empty list if no notes.	`[{"type": "strange", ...}]`
`utility`	UtilityID	Utility for this Bill.	`"PG&E"`
`blocks`	List(BillBlockType)	What BillBlocks are included with this Bill.	`["base", ...]`
`{block_type}`	BillBlock	The bill contents of a BillBlock that was listed in the blocks list.	`{"bill_total_volume": 123.45, ...}`

Examples

// A bill with tier information
{
    "uid": "12382",
    "meter_uid": "58",
    "authorization_uid": "23",
    "created": "2015-03-19T20:50:41.206253+00:00",
    "updated": "2015-03-19T20:50:41.206253+00:00",
    "utility": "DEMO",
    "blocks": ["base", "sources", "line_items", "tiers"],
    "base": {
        "service_identifier": "1234567890",
        "service_tariff": "E1 XB Residential Service",
        "service_class": "res-electric",
        "service_address": "123 Main St #100, Anytown, CA 94612",
        "meter_numbers": ["A987654321"],
        "billing_contact": "ACME, INC.",
        "billing_address": "123 Main St #100, Anytown, CA 94612",
        "billing_account": "100-200-33333",
        "bill_start_date": "2015-01-07T00:00:00.000000-08:00",
        "bill_end_date": "2015-02-05T00:00:00.000000-08:00",
        "bill_total_kwh": 837.0,
        "bill_total_unit": "kwh",
        "bill_total_volume": 837.0,
        "bill_total_cost": 194.78,
    }
    "sources": [
        {
            "type": "pdf",
            "raw_url": "https://utilityapi.com/api/v2/files/abc123abc123abc123",
        }
    ]
    "line_items": [
        {
            "cost": 52.88,
            "end": "2015-02-05T08:00:00.000000+00:00",
            "name": "Tier 1 Usage",
            "rate": 0.1617,
            "start": "2015-01-07T08:00:00.000000+00:00",
            "unit": "kwh",
            "volume": 327.0
        },
        {
            "cost": 18.14,
            "end": "2015-02-05T08:00:00.000000+00:00",
            "name": "Tier 2 Usage",
            "rate": 0.18491,
            "start": "2015-01-07T08:00:00.000000+00:00",
            "unit": "kwh",
            "volume": 98.1
        },
        {
            "cost": 62.54,
            "end": "2015-02-05T08:00:00.000000+00:00",
            "name": "Tier 3 Usage",
            "rate": 0.27322,
            "start": "2015-01-07T08:00:00.000000+00:00",
            "unit": "kwh",
            "volume": 228.9
        },
        {
            "cost": 60.98,
            "end": "2015-02-05T08:00:00.000000+00:00",
            "name": "Tier 4 Usage",
            "rate": 0.33322,
            "start": "2015-01-07T08:00:00.000000+00:00",
            "unit": "kwh",
            "volume": 183.0
        },
        {
            "cost": 0.24,
            "end": "2015-02-05T08:00:00.000000+00:00",
            "name": "Energy Commission Tax",
            "rate": null,
            "start": "2015-01-07T08:00:00.000000+00:00",
            "unit": null,
            "volume": null
        }
    ]
    "tiers": [
        {
            "name": "Tier 1 Usage",
            "level": 1,
            "cost": 52.88,
            "volume": 327.0,
            "unit": "kwh"
        },
        {
            "name": "Tier 2 Usage",
            "level": 2,
            "cost": 18.14,
            "volume": 98.1,
            "unit": "kwh"
        },
        {
            "name": "Tier 3 Usage",
            "level": 3,
            "cost": 62.54,
            "volume": 228.9,
            "unit": "kwh"
        },
        {
            "name": "Tier 4 Usage",
            "level": 4,
            "cost": 60.98,
            "volume": 183.0,
            "unit": "kwh"
        }
    ]
}