API reference

One GraphQL endpoint, always POST, key in the x-api-key header. This reference is generated from the live schema — see Authentication for access and Pricing / Disclosures for the behaviors that matter.

Queries

Query	Arguments	Returns
residentialPlans	zipCode or utilityId (utilityId wins); optional monthlyUsage (default 1000), priceType	[ResidentialPlan!]! — empty list if unresolved
businessPlans	zipCode!; optional annualUsageInkWh, isMoveIn, startDate	[BusinessPlan!]
utilities	zipCode!	[Utility!]
nextStartDate	zipCode!; optional isMoveIn	PlanNextStartDate!
utilityAccounts	street or accountNumber required, plus address parts	[UtilityAccount!]
energyInfoByState	stateCode!, isBusiness!	EnergyInfo

Schema

type ResidentialPlan {
  id: ID!
  title: String!
  description: String!
  rateType: RateType                 # FIXED | VARIABLE | PREPAID | SUBSCRIPTION
  term: Int!                         # months
  renewablePercentage: Int!
  price: Float!                      # $/kWh at the requested monthlyUsage (seasonalized)
  rates: [PlanRate!]!               # advertised + all-in + est. bill at 500/1000/2000 kWh
  feeBreakdown: [PlanFee!]!
  documents: [PlanDocument!]!       # disclosure docs; types vary by state; may be empty
  supplier: Supplier!
  supplierScores: SupplierScores     # nullable
  earlyTerminationFeeUsd: Float
  earlyTerminationFeeType: EarlyTerminationFeeType
  isEarlyTerminationPenalized: Boolean!
  isBillCreditPlan: Boolean!
  isPetFriendly: Boolean!
  timeOfUse: Boolean!               # flag only; no per-period rate structure exposed
  minimumStartDate: Date
  maximumStartDate: Date
  tags: [PlanTag!]!
  utilityCode: String
  stateCode: String
  createdAt: DateTime
  enrollmentUrl: String!            # hosted full-page checkout
  headlessEnrollmentUrl: String!    # embeddable (iframe) checkout
}

type BusinessPlan {
  id: ID!  term: Int!  price: Float!  monthlyFee: Float!  renewablePercentage: Int!
  supplier: Supplier!  agreementUrl: String!  enrollmentUrl: String!  headlessEnrollmentUrl: String!
}

type PlanRate { usageKwh: Int!  advertisedPriceUsdPerKwh: Float!  allInRateUsdPerKwh: Float!  avgMonthlyBillUsd: Float! }
type PlanFee { feeType: FeeType!  amountUsd: Float!  applicability: FeeApplicability!  threshold: Float  rules: [RuleEntry!] }
type PlanDocument { type: LinkType!  url: String!  title: String }
type Supplier { id: ID!  name: String!  shortName: String  logoUrl: String!  registrationId: String }
type SupplierScores { energyBotRating: Float  plansAndRates: Float  customerService: Float  renewablePlans: Float  pucRating: Float }
type PlanTag { key: String!  value: String  label: String  reasons: [String!] }
type RuleEntry { key: String!  value: String! }
type Utility { id: ID!  name: String!  residentialPlans: [ResidentialPlan!] }
type UtilityAccount { id: ID!  accountNumber: String  accountStatus: AccountStatus  serviceAddress: Address!  displayAddress: String  isBusiness: Boolean!  utilityCode: String! }
type Address { street: String!  street2: String  city: String!  state: String!  zipCode: String! }
type PlanNextStartDate { nextStartDate: Date!  businessPlans: [BusinessPlan!] }
type EnergyInfo { averagePrice: Float!  stateCode: String!  stateName: String!  electricityGenerationPercentage: ElectricityGenerationPercentage }
type ElectricityGenerationPercentage { renewableGeneration: Int!  nonRenewableGeneration: Int! }

enum RateType { FIXED  VARIABLE  PREPAID  SUBSCRIPTION }
enum LinkType { EFL  TOS  YRAC  ENROLLMENT  PREPAID_DISCLOSURE_STATEMENT  CONTRACT_SUMMARY  ENVIRONMENTAL_DISCLOSURE  ARBITRATION_ADDENDUM  COMM_POLICY  PAYMENT_TERMS }
enum EarlyTerminationFeeType { FIXED  PER_MONTH_REMAINING_PERIOD  NONE  UNKNOWN }
enum AccountStatus { ACTIVE  INACTIVE  DE_ENERGIZED }
enum FeeApplicability { PER_KWH  MONTHLY  PER_KWH_BELOW_USAGE  MONTHLY_BELOW_USAGE  MONTHLY_ABOVE_USAGE  CREDIT_MONTHLY_ABOVE_USAGE  CREDIT_MONTHLY_BELOW_USAGE  SCHEDULE  DEVICE  PER_KW }
enum FeeType {
  ENERGY_CHARGE  UTILITY_PASS_THRU  BASE_CHARGE  MIN_USAGE_CHARGE  MAX_USAGE_CHARGE  BILL_CREDIT
  CREDIT_PER_KWH  UPCHARGE_PER_KWH  MSDF_UTILITY_PASS_THRU
  BUS_CUSTOMER_CHARGE  BUS_METERING_CHARGE  BUS_INCOME_TAX_REFUND  BUS_DISTRIBUTION_SYSTEM_CHARGE
  BUS_FRANCHISE_CHARGE  BUS_ASSET_RECOVER_VEG_MGMT_CHARGE  BUS_NUCLEAR_DECOM_CHARGE  BUS_TCRF  BUS_DCRF
  BUS_RCE  BUS_RCE_SURCHARGE  BUS_SRC  BUS_ADFIT  BUS_ENERGY_EFFICIENCY_FACTOR  BUS_TRANSITION_CHARGE
  BUS_TEMPORARY_EMERGENCY_CHARGE  BUS_DELIVERY_SERVICE_CHARGE
}

scalar Date       # YYYY-MM-DD
scalar DateTime   # ISO-8601
scalar Long       # 64-bit integer

Errors

Query/validation errors return HTTP 200 with an errors[] array (data: null). Auth/transport failures return 403 (bad key or non-allow-listed IP) or 400 (malformed). See Authentication.