Account Tariff

Overview

An account is a place where you can store your customers 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 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.

Name Type Fields Description
masterTariffId Integer The masterTariffId of the tariff.
effectiveDate Date The date the tariff is effective for the account. If multiple tariffs are set on the account, each must have the effective date set.

Operations

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 accounts 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 endopint are very similar to those for the Get Tariffs endpoint.

Name Type Description
serviceTypes String Comma separated string that indicates the service types to include. Choices are: ELECTRICITY, SOLAR_PV (Optional, defaults to ELECTRICITY only). If set to SOLAR_PV, the returned tariffs will not be restricted to those that have the same lseId as the account.
effectiveOn DateTime Only tariffs that are effective on this date (Optional)
fromDateTime DateTime Only include tariffs that are effective on or after this date (Optional)
toDateTime DateTime Only include tariffs that are effective on or before this date (Optional)
populateRates Boolean Populates the rate details for the returned tariffs (Optional. Defaults to false)
populateDocuments Boolean Populates the document links for the returned tariffs (Optional. Defaults to false)

Example

Lets query the example accounts tariffs.

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

Here's what we found...

{
   "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 aariff 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"

{
    "masterTariffId": 522,
    "serviceType": "ELECTRICITY",
    "customerLikelihood": 100,
    "effectiveDate": null,
    "endDate": null
}

From this call you will get back the following response.

{
   "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