The Bill object represents billing information needed to calculate bill charge for energy use, and Bills API allows you to get or set a site’s billing information. You can also grab a list of supported suppliers and their rate plans, and get a rate plan schema for detailed information.

Note that if a site does not have billing information, Billing Usage API would return null for bill property.

The bill object

name type description
meterDate number monthly meter start date from 1 to 29
supplierId string supplier identifier
ratePlanId string ratePlan identifier
billSettings object billSettings object

The billSettings object

It represents a bill settings as custom key/value pair (as example below shows). Each rate plan has its own billSettings schema (which can be empty), so please refer to ‘GET rate plan schema’ API to build one.

{
    "contractOption": [1,3],
    "contractType": 1,
    "discount": 2,
    "contractDate": "2017-01-01",
    "contractPower": 299
}

Get billing information

Get a site’s billing information.

Endpoints

GET /sites/:siteId/bills

Parameters

name type description
siteId string (required) site identifier

Request Example

curl -X GET
  -H "Authorization: Bearer <access_token>"
  -H "accept-version: 2.0.0"
  "https://api2.enertalk.com/sites/11111111/bills"

Response

Retrieved bill object, or error if site not found.

Response Example

{
    "meterDate": 1,
    "supplierId": "eversource",
    "ratePlanId": "A1",
    "billSettings": null
}

Update bill information

Update site’s billing information.

Endpoints

PATCH /sites/:siteId/bills

Parameters

name type description
siteId string (required) site identifier
meterDate number integer from 1 to 29. Numbers greater than 29 will be set to 29.
supplierId string supplier identifier
ratePlanId string ratePlan identifier
billSettings object billSettings object

Note that updating supplierId requires ratePlanId to be updated as well.

Request Example

curl -X PATCH
  -H "Authorization: Bearer <access_token>"
  -H "accept-version: 2.0.0"
  -H "Content-Type: application/json"
  -d '{
    "meterDate": 2,
    "supplierId": "nationalGrid",
    "ratePlanId": "R1",
    "billSettings": {
      "contractOption": [1,3],
      "contractType": 1,
      "discount": 2,
      "contractDate": "2017-01-01",
      "contractPower": 299
    }
  }'
  "https://api2.enertalk.com/sites/11111111/bills"

Response

Updated bill object.

Response Example

{
    "meterDate": 2,
    "supplierId": "nationalGrid",
    "ratePlanId": "R1",
    "billSettings": {
      "contractOption": [1,3],
      "contractType": 1,
      "discount": 2,
      "contractDate": "2017-01-01",
      "contractPower": 299
    }
}

List suppliers

List supported suppliers and their rate plans.

Endpoints

GET /suppliers

Parameters

name type description
countryCode string (required) two-letter country code (per ISO 3166-1 alpha-2 spec)

Request Example

curl -X GET
  -H "Authorization: Bearer <access_token>"
  -H "accept-version: 2.0.0"
  "https://api2.enertalk.com/suppliers/?countryCode=US"

Response

List of suppliers and its own rate plans for specified country.

Response example

[
  {
    "id": "eversource",
    "name": "Eversource",
    "ratePlans": [
      {
        "id": "A1",
        "name": "A1 - Residential"
      }
    ]
  },
  {
    "id": "nationalGrid",
    "name": "National Grid",
    "ratePlans": [
      {
        "id": "R1",
        "name": "Residential Regular R-1"
      }
    ]
  }
]

Get rate plan schema

Get a supplier’s rate plan schema.

Endpoints

GET /suppliers/:supplierId/rateplans/:ratePlanId/schema

Parameters

name type description
supplierId string (required) supplier identifier
ratePlanId string (required) rate plan identifier

Request Example

curl -X GET
  -H "Authorization: Bearer <access_token>"
  -H "accept-version: 2.0.0"
  "https://api2.enertalk.com/suppliers/eversource/rateplans/A1/schema"

Response

Schema with id, name, tiers, and billSettings props.

  • id is ratePlanId
  • name is name of the rate plan
  • tiers
    • composed of base tiers and usage tiers
    • a tier is an object with amount (kWh) and cost props
    • amount can be 0 for the last or only tier
  • billSettings
    • composed of custom key/value pairs
    • billSettings schema provided here should be used as guidance
    • to build billSettings object for PATCH /sites/:siteId/bills API
    • each child can have following common props
    • title {string} name of the UI
    • uiType {string} type of the UI
    • description {string} description of the UI
    • uiType specific props are listed below
    • it tells you what value type (such as number, date, or a list) to use when building billSettings object.

    uiType props

    • radiobox
    • kinds {Object} list of options with key/value pair
    • use one of kinds keys when building billSettings object
      • type: number, example: 1
    • dropdown
    • kinds {Object} list of options with key/value pair
    • use one of kinds keys when building billSettings object
      • type: number, example: 2
    • checkbox
    • kinds {Object} list of options with key/value pair
    • use one or more of kinds keys when building billSettings object
      • type: number[], example: [1,2]
    • date
    • max {number} newest date allowed (inclusive)
    • min {number} oldest date allowed (inclusive)
    • use ‘YYYY-MM-DD’ string when building billSettings object
      • type: string, example: “2016-12-31”
    • number

    • max {number} maximum number allowed (inclusive)
    • min {number} minimum number allowed (inclusive)
    • unit{string} unit such as ‘kW’
    • value {number} default value to be pre-populated
    • use a number when building billSettings object
      • type: number, example: 7

Response Example

{
  "id": "A1",
  "name": "A1 - Residential",
  "tiers": {
    "base": [
      {
        "amount": 0,
        "cost": 6.43
      }
    ],
    "usage": [
      {
        "amount": 100,
        "cost": 0.01
      },
      {
        "amount": 0,
        "cost": 0.18982
      }
    ]
  },
  "billSettings": {
    "contractOption": {
      "title": "Contract Option",
      "uiType": "checkbox",
      "kinds": {
        "1": {
          "displayName": "Checkbox 1"
        },
        "2": {
          "displayName": "Checkbox 2"
        },
        "3": {
          "displayName": "Checkbox 3"
        }
      }
    },
    "contractType": {
      "title": "Contract Type",
      "uiType": "radiobox",
      "kinds": {
        "1": {
          "displayName": "Radiobox 1"
        },
        "2": {
          "displayName": "Radiobox 2"
        }
      }
    },
    "discount": {
      "title": "Discount Options",
      "uiType": "dropdown",
      "kinds": {
        "1": {
          "displayName": "None"
        },
        "2": {
          "displayName": "Dropdown 1"
        },
        "3": {
          "displayName": "Dropdown 2"
        },
        "4": {
          "displayName": "Dropdown 3"
        },
        "5": {
          "displayName": "Option 4"
        }
      }
    },
    "contractDate": {
      "title": "Contract Date",
      "uiType": "date",
      "min": "2013-01-01"
    },
    "contractPower": {
      "title": "Contract Power",
      "uiType": "number",
      "min": 4,
      "max": 300,
      "unit": "kW"
    }
  }
}

From billSettings schema above, billSettings object for PATCH /sites/:siteId/bills API can be built as shown below.

{
  "billSettings": {
    "contractOption": [1,3],
    "contractType": 1,
    "discount": 2,
    "contractDate": "2017-01-01",
    "contractPower": 299
  }
}