API Update to 3rd Party Supplier Data

Many utilities supported by our service allow their customers to purchase energy from a third party. UtilityAPI is making this information available through our suppliers block. This block includes a lot of new information about suppliers. We hope it's as useful to you as we think it will be. The suppliers block helps clarify where charges are coming from. It also simplifies cases where 3rd party supplier data is listed completely separately (e.g. on another page of the bill) by giving it to you all in one place. Here are the changes, and how to get started:

What's New?

The suppliers block includes the following information if it's provided on the bill:

• The type of the supplier (CCA, third party, direct access, etc.)
• The supplier's name
• The service identifier used by the supplier since it may be different from the main SAID
• The supplier tariff
• Any line item charges from the supplier
• The total cost charged by the supplier
• The total amount of energy supplied by the supplier

For details about any of this information see the API documentation here: https://utilityapi.com/docs/api/bills/blocks#suppliers-bill-block

Updates for Dashboard Users

You can now find the CCA data in the bills.csv and line items.csv files on your dashboard. You won't have to download and combine two sets of data, or search through the PDF bills, for the right CCA service on commercial accounts. All the data can now be found in these two files and also, of course, in the PDF bills. 

Line Items Changes for our API Users

Before the suppliers block, we combined all of the line item charges on a bill together in the line items block. Now that we present the supplier information separately, any line items from the supplier are shown separately from the first party (utility) line items. Note that all charges will remain combined on our line items CSV file. On the API, however, line items are shown with the supplier they came from.

The easiest way to show the difference is with an example. In this bill, the customer is charged separately for energy provided by Example Energy Services, LLC - here's how the line items look under the old system compared to how they look with the suppliers block.

Under the old system, all of the line items are combined together:

"line_items": [
    {
        "cost": 19.99,
        "end": "2018-12-01T04:00:00.000000+00:00",
        "name": "Customer Charge",
        "rate": null,
        "start": "2018-11-01T04:00:00.000000+00:00",
        "unit": null,
        "volume": null
    },
    {
        "cost": 16.01,
        "end": "2018-12-01T04:00:00.000000+00:00",
        "name": "Delivery Charges",
        "rate": 0.0915,
        "start": "2018-11-01T04:00:00.000000+00:00",
        "unit": "kwh",
        "volume": 175.0
    },
    {
        "cost": 12.09,
        "end": "2018-12-01T04:00:00.000000+00:00",
        "name": "Generation",
        "rate": 0.0691,
        "start": "2018-11-01T04:00:00.000000+00:00",
        "unit": "kwh",
        "volume": 175.0
    },
    {
        "cost": -2.15,
        "end": "2018-12-01T04:00:00.000000+00:00",
        "name": "Adjustment",
        "rate": null,
        "start": "2018-11-01T04:00:00.000000+00:00",
        "unit": null,
        "volume": null
    },
    {
        "cost": 0.72,
        "end": "2018-12-01T04:00:00.000000+00:00",
        "name": "Utility Users Tax",
        "rate": null,
        "start": "2018-11-01T04:00:00.000000+00:00",
        "unit": "percent",
        "volume": 1.5
    }
]

With the suppliers block, it's clear which line items come from the supplier and which ones come from the utility:

"line_items": [
    {
        "cost": 19.99,
        "end": "2018-12-01T04:00:00.000000+00:00",
        "name": "Customer Charge",
        "rate": null,
        "start": "2018-11-01T04:00:00.000000+00:00",
        "unit": null,
        "volume": null
    },
    {
        "cost": 16.01,
        "end": "2018-12-01T04:00:00.000000+00:00",
        "name": "Delivery Charges",
        "rate": 0.0915,
        "start": "2018-11-01T04:00:00.000000+00:00",
        "unit": "kwh",
        "volume": 175.0
    },
    {
        "cost": 0.72,
        "end": "2018-12-01T04:00:00.000000+00:00",
        "name": "Utility Users Tax",
        "rate": null,
        "start": "2018-11-01T04:00:00.000000+00:00",
        "unit": "percent",
        "volume": 1.5
    }
],
"suppliers": [
    {
        "supplier_line_items": [
            {
                "cost": 12.09,
                "end": "2018-12-01T04:00:00.000000+00:00",
                "name": "Generation",
                "rate": 0.0691,
                "start": "2018-11-01T04:00:00.000000+00:00",
                "unit": "kwh",
                "volume": 175.0
            },
            {
                "cost": -2.15,
                "end": "2018-12-01T04:00:00.000000+00:00",
                "name": "Adjustment",
                "rate": null,
                "start": "2018-11-01T04:00:00.000000+00:00",
                "unit": null,
                "volume": null
            }
        ],
        "supplier_name": "Example Energy Services, LLC",
        "supplier_service_id": "55134-91022",
        "supplier_tariff": "Residential R1",
        "supplier_total_cost": 9.94,
        "supplier_total_unit": "kwh",
        "supplier_total_volume": 175.0,
        "supplier_type": "third_party"
    }
]

In the second example, all of the line items that came from the third party supplier can be found in the suppliers block, along with additional information about the supplier. The result is that the same set of line items is available but now it's clear which ones are from the utility and which ones come from a third party supplier.

We hope these changes will make it much easier for our users to find and use third party supplier information so please let us know what you think and as always, feel free to contact us if you have any questions.