Understanding Arcadia Tariff JSON

⚠️ Disclaimer: This guide was generated by an LLM (Claude Opus 4.5) based on Arcadia API documentation and tariff data. The content looks reasonable but has not been verified by domain experts. Please verify any claims before relying on them for production use.

This page explains the structure of tariff data returned by the Arcadia Signal API. For complete field definitions, see the Arcadia Tariff API Reference.

Data Hierarchy

Tariff data follows a three-level hierarchy:

Tariff (header)
├── properties[]      → Input parameters needed for bill calculations
└── rates[]           → Array of TariffRate objects (line items)
    └── rateBands[]   → Array of TariffRateBand objects (tiers/bands)

Tariff — The top-level object with metadata about the rate plan (name, utility, customer class, effective dates)
TariffRate — Individual charges like "Customer Charge" or "Summer Rate" — think of these as line items on a bill
TariffRateBand — Tiers within a rate (e.g., first 250 kWh at one price, remaining kWh at another)

Key Tariff Fields

Field	Description
`tariffId`	Unique ID for this version of the tariff
`masterTariffId`	Persistent ID across all revisions of a tariff
`tariffCode`	Utility's shortcode (e.g., "EL1", "E-1")
`tariffName`	Official tariff name
`lseId`	Load Serving Entity (utility) ID
`effectiveDate`	When this version became effective
`priorTariffId`	Previous version's `tariffId`
`customerClass`	Target segment: RESIDENTIAL, COMMERCIAL, INDUSTRIAL, etc.
`customerCount`	Approximate customers on this tariff

`tariffId` vs `masterTariffId`

Tariff data changes periodically — a residential tariff might update several times per year as rates are adjusted. Each revision gets a new tariffId, but they all share the same masterTariffId.

Use masterTariffId when tracking a tariff over time or fetching historical versions
Use tariffId when you need to reference a specific version

To get historical versions, use the Tariff History API.

Boolean Flags

These flags tell you what features a tariff has without parsing all the rates:

Flag	What It Tells You
`hasTimeOfUseRates`	Rates vary by time of day (peak/off-peak)
`hasTieredRates`	Some rates have consumption-based tiers
`hasContractedRates`	Includes supply charges (for bundled service)
`hasNetMetering`	Net metering is available for solar customers
`isActive`	Tariff is currently in effect

Properties

The properties array defines input parameters needed to calculate bills. When you call the Calculate API, you provide values for these properties, and the API uses them to determine which rates apply and compute charges.

What Properties Tell You

Before running any calculations, the properties array reveals:

What inputs you need — consumption (kWh), demand (kW), time-of-use period, etc.
What choices exist — Territory/zone options, service types, rate schedules
Default assumptions — What values are assumed if you don't specify (e.g., systemSize: 0 assumes no solar)
Tariff complexity — More properties usually means more rate variations

Common Property Types

`propertyTypes`	Meaning
`RATE_CRITERIA`	Input that affects which rates apply or how they're calculated
`SERVICE_TERMS`	Describes service characteristics (informational, not an input)

Common Properties

Property	Description	Typical Use
`consumption`	Energy usage (kWh)	All consumption-based charges
`demand`	Peak demand (kW)	Demand charges (commercial tariffs)
`territoryId`	Service zone/region	Zone-specific rates
`systemSize`	Solar system capacity (kW)	Solar-related charges (CBC, net metering)
`connectionType`	Single-phase vs. three-phase	Service charges
`chargeClass`	Categories to include	Filtering SUPPLY vs. DISTRIBUTION

Property Structure

Each property has metadata explaining what it is and how to use it:

{
  "keyName": "territoryId",
  "displayName": "Territory",
  "description": "Rate Baseline Region",
  "dataType": "CHOICE",
  "propertyTypes": "RATE_CRITERIA",
  "choices": [
    { "displayValue": "Zone H", "value": "3632" },
    { "displayValue": "Zone I", "value": "3633" },
    { "displayValue": "Zone J", "value": "3634" }
  ],
  "isDefault": true
}

keyName — The key to use in API calls
dataType — DECIMAL, CHOICE, STRING, BOOLEAN, etc.
choices — For CHOICE types, the valid options
propertyValue / isDefault — Default value if not specified

Rates

The rates array contains the actual charges. Each TariffRate object represents a line item like "Customer Charge" or "Summer Delivery Rate."

Key Rate Fields

Field	Description
`rateName`	Human-readable name
`rateGroupName`	Category grouping (e.g., "Delivery Charges")
`chargeType`	How it's calculated: FIXED_PRICE, CONSUMPTION_BASED, QUANTITY, MINIMUM
`chargeClass`	Category: DISTRIBUTION, SUPPLY, TRANSMISSION, TAX
`variableRateKey`	If present, rate value must be looked up via API
`territory`	If present, rate is zone-specific
`season`	If present, rate is seasonal
`rateBands`	Tier structure with actual rate amounts

Charge Types

`chargeType`	Meaning	Unit
`FIXED_PRICE`	Flat monthly fee	$/month
`CONSUMPTION_BASED`	Per-kWh charge	$/kWh
`QUANTITY`	Based on a property value	Varies ($/kW, %)
`DEMAND`	Based on peak demand	$/kW
`MINIMUM`	Floor on total bill	$/month

Variable Rates

Some rates change frequently (monthly supply charges, adjustment factors). These have:

rateAmount: 0.0 — Placeholder value
variableRateKey — Key to use with the Lookups API

Rate Bands

Each rate has a rateBands array containing one or more TariffRateBand objects. For simple rates, there's just one band. For tiered rates, there are multiple bands with consumption limits.

Key Rate Band Fields

Field	Description
`rateAmount`	The actual rate value
`rateUnit`	COST_PER_UNIT, PERCENTAGE, etc.
`consumptionUpperLimit`	For tiered rates, the kWh threshold
`rateSequenceNumber`	Order of tiers (1, 2, 3...)
`isCredit`	True if this is a credit (negative charge)

Tiered Rate Example

"rateBands": [
  {
    "rateSequenceNumber": 1,
    "consumptionUpperLimit": 250.0,
    "rateAmount": 0.16107
  },
  {
    "rateSequenceNumber": 2,
    "rateAmount": 0.18518
  }
]

This means: First 250 kWh at $0.16107/kWh, remaining kWh at $0.18518/kWh.

Riders

Riders are modular tariff components that can be attached to multiple base tariffs. They appear in the rates array with special fields:

riderId — Reference to a rider tariff (placeholder, no rate details)
riderTariffId — The actual rider implementation (contains rate details)

For bill calculations, use rates with riderTariffId — they have all the charge details already resolved.