# 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](https://docs.arcadia.com/v2022-12-21-Signal/reference/tariff).

## 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](https://docs.arcadia.com/v2022-12-21-Signal/reference/tariff-history).

### 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:

```json
{
  "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](https://docs.arcadia.com/v2022-12-21-Signal/reference/lookups)

---

## 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

```json
"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.

---

## Further Reading

- [Arcadia Tariff API Reference](https://docs.arcadia.com/v2022-12-21-Signal/reference/tariff) — Complete field definitions
- [Lookups API](https://docs.arcadia.com/v2022-12-21-Signal/reference/lookups) — Retrieving variable rate values
- [Calculate API](https://docs.arcadia.com/v2022-12-21-Signal/reference/calculate) — Running bill calculations
- [Tariff History API](https://docs.arcadia.com/v2022-12-21-Signal/reference/tariff-history) — Historical tariff versions
