Account Tariffs API

Use the Account Tariffs API to store and manage the tariff rate plans, historical tariff changes, utility tax rates, and custom contracted rates associated with an account.

An Account stores customer energy cost and savings data. Its tariff information defines the rate plan the account is currently on and any historical rate plan changes that affect calculations and savings analyses.

Use account tariffs after you create or retrieve an account with Accounts API and set any required applicability values with Account Properties API. For the full account workflow, see Account APIs Overview.

Get Available Tariff Rate Plans with {accountId}

Retrieve available tariff rate plans using the Arcadia accountId.

Get Available Tariff Rate Plans with {providerAccountId}

Retrieve available tariff rate plans using your providerAccountId.

Add or Update Account Tariff with {accountId}

Set or update an account tariff using the Arcadia accountId.

Add or Update Account Tariff with {providerAccountId}

Set or update an account tariff using your providerAccountId.

Delete Account Tariff with {accountId}

Remove an account tariff using the Arcadia accountId.

Delete Account Tariff with {providerAccountId}

Remove an account tariff using your providerAccountId.

Data definitions

Account tariffs are saved directly on the Account object. An account tariff is similar to the Tariff object, but it represents the tariff assignment for a specific account.

Taxes

The Arcadia database includes rates that appear in utility tariff books. It does not include state, local, or other tax rates by default. You can still include taxes in calculations; see Handle taxes.

Account tariff

Store tariff rate plans for an account in its tariffs collection. Each account tariff has a masterTariffId.

To store multiple tariffs, set an effectiveDate for each account tariff. Account calculations use the account tariffs and their effective dates to determine which tariff applies to the calculation period. You can store electricity and solar tariffs; set 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 is not a dedicated endpoint for querying only the tariffs currently active on an account. Instead, call one of the Get Account endpoints and inspect the populated tariffs list.

Get Available Tariff Rate Plans

Use the Get Available Tariff Rate Plans endpoints to retrieve tariff rate plans available for a specific account. The account must have a valid address; specifically, the zip field must be populated. The account's customerClass property must also 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 similar to tariff search filters. For tariff data model details, see Tariffs API.

Name	Type	Description
serviceTypes	String	Comma-separated service types to include. Choices are `ELECTRICITY` and `SOLAR_PV`. Defaults to `ELECTRICITY` only. If set to `SOLAR_PV`, returned tariffs are not restricted to tariffs with the same `lseId` as the account. Optional.
effectiveOn	DateTime	Return tariffs that are effective on this date. Optional.
fromDateTime	DateTime	Return tariffs that are effective on or after this date. Optional.
toDateTime	DateTime	Return tariffs that are effective on or before this date. Optional.
populateRates	Boolean	When `true`, populates rate details for returned tariffs. Defaults to `false`. Optional.
populateDocuments	Boolean	When `true`, populates document links for returned tariffs. Defaults to `false`. Optional.

Example

This example queries available tariffs for an example account.

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

This abbreviated response shows matching tariff rate plans:

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

Set a tariff on an account for a given serviceType, such as ELECTRICITY or SOLAR_PV. You can optionally set an effective date, which is useful when the account switches tariffs. Account tariffs can also store supplier rates in deregulated markets.

Resource URI

PUT /rest/v1/accounts/{accountId}/tariffs

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

Request parameters

Place the account tariff to add or update in the request body. When editing an existing tariff entry, Switch matches the entry by service type and effective date.

Field	Type	Description
`masterTariffId`	Integer	Master tariff ID to assign to the account. Required.
`serviceType`	String	Service type for the tariff assignment, such as `ELECTRICITY` or `SOLAR_PV`. Defaults to `ELECTRICITY` when omitted. Optional.
`customerLikelihood`	Number	Likelihood that the account is on this tariff. Use `100` or `null` to confirm a defaulted tariff. Optional.
`effectiveDate`	Date	Date the tariff becomes effective for the account. Required when storing multiple tariff assignments. Optional otherwise.
`endDate`	Date	Date the tariff assignment ends. Use `null` for an open-ended tariff assignment. Optional.

When switching an account from one tariff to another at a specific point in time, set effectiveDate. Switch checks for overlapping effective ranges and returns an error if one exists. You can also confirm a defaulted tariff by passing null or 100 for customerLikelihood.

Example

This example sets or confirms a tariff on an account. Pass masterTariffId and serviceType; serviceType defaults to ELECTRICITY if not set.

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

This request payload includes optional customerLikelihood and date fields. You do not need to include customerLikelihood when the value is null or 100, and you do not need to include date fields when setting them to null.

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

A successful request returns the updated account tariff:

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

Delete a tariff from an 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, include an ISO 8601-formatted effective date to identify which account tariff to delete.

Example

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

Next steps

Return to Account APIs Overview to choose another account workflow.
Use Account Rates API to retrieve the rates associated with the account's assigned tariffs.
Use Account Cost Calculation to calculate costs after tariff assignments are configured.
Use Tariffs API to inspect the full tariff model, rates, and applicability rules.