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 Arcadia 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 the 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	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.

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.

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

Let's query the example account's 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 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"

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