Account Tariff

An account is a place where you can store your customer’s energy cost and savings data (see the Account page for more details). Each account can have tariff information which defines the tariff rate plan the account is currently on as well as any historical rate plan changes. It can also capture utility tax rates as well as custom contracted rates (deregulated markets).

Data Definitions

Account tariffs are saved directly on the Account object. It is very similar to the Tariff object.

Taxes

The Genability database only has rates that appear in utility tariff books. That means that it does not have state, local, and other tax rates. That doesn’t mean that you can’t include them in a calculation though. We have a quick how-to on exactly how to do that.

Account Tariffs

You can specify the tariff rate plan for the account and store it in its tariffs property (a collection). Each tariff on the account will have a masterTariffId set. To specify multiple tariffs, an effective date must also be set for each account tariff. Calculations on the account will use the account’s tariffs and effective date of the tariff to determine which tariffs to run the calculation against. You can store electricity and/or solar tariffs. Make sure you set the serviceType accordingly.

Get an Account’s Active Tariffs

There isn’t an end point specifically dedicated to querying for the tariffs that are currently active on an account. Instead you just call one of the Get Account endpoints and the account’s tariff information will be populated in the tariffs list.

Get Available Tariff Rate Plans

To see what tariff rates plans are available for a specific account, use one of the Get Available Tariffs endpoints. In order to use this endpoint, the account must have a valid address. Specifically, the zip field must be populated. Also, the account’s customerClass property must be populated.

Resource URI

GET /rest/v1/accounts/{accountId}/tariffs
GET /rest/v1/accounts/pid/{providerAccountId}/tariffs

Request Parameters

The request parameters for this endpoint are very similar to those for the Get Tariffs endpoint.

Example

Let’s query the example account’s tariffs.

GET /rest/v1/accounts/pid/api-eg-008/tariffs

Here’s what we found…

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
{
   "status": "success",
   "count": 17,
   "type": "Tariff",
   "results": [
      {
         "tariffId": 3155887,
         "masterTariffId": 522,
         "tariffCode": "E-1",
         "tariffName": "Residential",
         "lseId": 734,
         "lseName": "Pacific Gas & Electric Co",
         "priorTariffId": 3154354,
         "tariffType": "DEFAULT",
         "customerClass": "RESIDENTIAL",
         "customerCount": 3321385,
         "customerLikelihood": 74.03,
         "territoryId": 807,
         "effectiveDate": "2013-01-01",
         "endDate": null,
         "timeZone": "US/Pacific",
         "billingPeriod": "MONTHLY",
         "currency": "USD",
         "chargeTypes": "CONSUMPTION_BASED,MINIMUM",
         "chargePeriod": "DAILY",
         "hasTimeOfUseRates": true,
         "hasTieredRates": true,
         "hasContractedRates": false,
         "hasRateApplicability": true,
         "isActive": true
      },
  
	  /* truncated for space */

      {
         "tariffId": 3155907,
         "masterTariffId": 3153889,
         "tariffCode": "E-7-FERA",
         "tariffName": "Residential - FERA, Time of Use",
         "lseId": 734,
         "lseName": "Pacific Gas & Electric Co",
         "priorTariffId": 3154806,
         "tariffType": "ALTERNATIVE",
         "customerClass": "RESIDENTIAL",
         "customerCount": 1,
         "customerLikelihood": 0,
         "territoryId": 807,
         "effectiveDate": "2013-01-01",
         "endDate": null,
         "timeZone": "US/Pacific",
         "billingPeriod": "MONTHLY",
         "currency": "USD",
         "chargeTypes": "CONSUMPTION_BASED,MINIMUM",
         "chargePeriod": "DAILY",
         "hasTimeOfUseRates": true,
         "hasTieredRates": true,
         "hasContractedRates": false,
         "hasRateApplicability": true,
         "isActive": true
      }
   ]
}

Add or Update an Account Tariff

This allows you to set a tariff on the account. You set the tariff for a given serviceType ("ELECTRICITY" or "SOLAR_PV" for instance). You can optionally set an effective date which is useful for when the account switches tariffs. Tariffs can also store supplier rate or rates in deregulated markets.

Resource URI

POST /rest/v1/accounts/{accountId}/tariffs
PUT /rest/v1/accounts/{accountId}/tariffs
POST /rest/v1/accounts/pid/{providerAccountId}/tariffs
PUT /rest/v1/accounts/pid/{providerAccountId}/tariffs

Request Parameters

The account tariff to add or update needs to be placed within the body of the request. If you are making an edit to an existing tariff entry, then the service type and effective date is used to match it. When you want to switch the account from an existing tariff to a new tariff as of a point in time, make sure to set the effectiveDate. Note that we check for overlaps and will return an error if it is, so take care with your effective ranges. You can use this endpoint to also confirm a defaulted tariff by passing in "null" or "100" for the customerLikelihood value.

Example

Here’s a simple example where you want to set or confirm a tariff on the account. Pass in the masterTariffId and the serviceType (defaults to "ELECTRICITY" if not set).

PUT /rest/v1/accounts/pid/api-eg-008/tariffs

Below is the request payload. You don’t actually need the customerLikelihood ("null" is the same as "100"). Nor do you need the dates if you are setting them to "null"

1
2
3
4
5
6
7
{
    "masterTariffId": 522,
    "serviceType": "ELECTRICITY",
    "customerLikelihood": 100,
    "effectiveDate": null,
    "endDate": null
}

From this call you will get back the following response.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
   "status": "success",
   "count": 1,
   "type": "Tariff",
   "results": [
      {
         "masterTariffId": 522,
         "customerClass": null,
         "customerLikelihood": 100,
         "endDate": null,
         "timeZone": "America/Los_Angeles",
         "billingPeriod": "MONTHLY",
         "currency": "USD"
      }
   ]
}

Delete an Account Tariff

This allows you to delete a tariff on the account.

Resource URI

DELETE /rest/v1/accounts/{accountId}/tariffs?effectiveDate={effectiveDate}
DELETE /rest/v1/accounts/pid/{providerAccountId}/tariffs?effectiveDate={effectiveDate}

Request Parameters

If more than one tariff is specified on the account, an effective date (ISO 8601 formatted) should be used to determine which account tariff to delete.

Example

DELETE /rest/v1/accounts/{accountId}/tariffs?effectiveDate=2012-12-01