Electricity Offers

Overview

Electricity is a first-class service type on Offergrid. Rather than a free-form JSON blob, electricity offers carry a single, structured electricity object grouped into four sections — rate, term, plan, and disclosures — that models a deregulated retail electricity plan the way a Texas Electricity Facts Label (EFL) does.

This page is the narrative guide. The field-by-field reference is published in the API Reference as the ElectricityContractWrite, ElectricityContract, and ElectricityCharge schema components.

Identifying an electricity offer

Every offer response carries a top-level serviceType discriminator that mirrors category — check either field:

{
  "id": "…",
  "serviceType": "electricity",
  "category": "electricity",
  "name": "Amigo Fixed 12",
  "status": "active",
  "electricity": { /* the contract, see below */ }
}

Electricity offers additionally include the grouped electricity object. Other service types (internet, other) get their own top-level key.

The `electricity` contract

"electricity": {
  "rate": {
    "type": "fixed",                       // fixed | variable | indexed
    "charges": [ /* bill breakdown — the source of truth, see below */ ],
    "avgPriceAt1000Kwh": 16.2,             // ¢/kWh, the all-in EFL comparison number
    "estimatedMonthlyAt1000Kwh": 162.00    // READ-ONLY — derived from charges
  },
  "term": {
    "length": "months_12",                 // no_contract | month_to_month | months_12 | months_24 | months_36
    "earlyTerminationFee": 150,            // dollars
    "earlyTerminationFeeNotes": "Prorated by months remaining"
  },
  "plan": {
    "renewablePercentage": 100,            // 0–100
    "freeNightsWeekends": false,
    "noDeposit": true
  },
  "disclosures": {                         // Texas PUCT regulatory disclosures
    "electricityFactsLabel": {
      "url": "https://example.com/efl.pdf",
      "versionId": "EFL-2024-001",
      "avgPrice500kwh": 17.1,
      "avgPrice1000kwh": 16.2,
      "avgPrice2000kwh": 15.4,
      "renewablePercent": 100
    },
    "puctCertNumber": "10081",
    "puctCertifiedName": "Amigo Energy",
    "termsOfServiceUrl": "https://example.com/tos.pdf",
    "yourRightsUrl": "https://example.com/yrac.pdf"
  }
}

All four sections and all fields are optional on write, except the publish requirement. Send only what you have; unspecified fields are left untouched on update.

rate — how customers are billed

type — fixed, variable, or indexed.
charges — the ordered provider (REP) + utility (TDU) charge lines that define pricing. This is the source of truth — see The charge breakdown.
avgPriceAt1000Kwh — the EFL “average price at 1000 kWh” comparison number, in ¢/kWh (all-in).
estimatedMonthlyAt1000Kwh — read-only dollar headline, derived from charges (ignored on write).

term — contract length and cancellation

length — no_contract, month_to_month, months_12, months_24, or months_36.
earlyTerminationFee — cancellation fee in dollars.
earlyTerminationFeeNotes — free-text detail, e.g. “Prorated by months remaining”.

plan — green energy and perks

renewablePercentage — 0–100.
freeNightsWeekends — boolean.
noDeposit — boolean.

disclosures — Texas PUCT regulatory documents

electricityFactsLabel — the EFL: url, versionId, and the three benchmark prices (avgPrice500kwh, avgPrice1000kwh, avgPrice2000kwh) plus renewablePercent.
puctCertNumber / puctCertifiedName — your PUCT REP certification.
termsOfServiceUrl / yourRightsUrl — the Terms of Service and Your Rights as a Customer documents.

Creating an electricity offer

curl -X POST https://api.offergrid.io/provider/offers \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Amigo Fixed 12",
    "category": "electricity",
    "electricity": {
      "rate": {
        "type": "fixed",
        "charges": [
          { "type": "perKwh", "owner": "provider", "label": "Energy Charge", "centsPerKwh": 12.5 },
          { "type": "fixed",  "owner": "utility",  "label": "TDU Meter Charge", "amountDollars": 4.39 },
          { "type": "perKwh", "owner": "utility",  "label": "TDU Delivery", "centsPerKwh": 4.2 }
        ]
      },
      "term": { "length": "months_12", "earlyTerminationFee": 150 },
      "plan": { "renewablePercentage": 100, "noDeposit": true },
      "disclosures": {
        "puctCertNumber": "10081",
        "electricityFactsLabel": { "url": "https://example.com/efl.pdf" }
      }
    }
  }'

const response = await fetch('https://api.offergrid.io/provider/offers', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.OFFERGRID_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Amigo Fixed 12',
    category: 'electricity',
    electricity: {
      rate: {
        type: 'fixed',
        charges: [
          { type: 'perKwh', owner: 'provider', label: 'Energy Charge', centsPerKwh: 12.5 },
          { type: 'fixed',  owner: 'utility',  label: 'TDU Meter Charge', amountDollars: 4.39 },
          { type: 'perKwh', owner: 'utility',  label: 'TDU Delivery', centsPerKwh: 4.2 },
        ],
      },
      term: { length: 'months_12', earlyTerminationFee: 150 },
      plan: { renewablePercentage: 100, noDeposit: true },
      disclosures: {
        puctCertNumber: '10081',
        electricityFactsLabel: { url: 'https://example.com/efl.pdf' },
      },
    },
  }),
});

const offer = await response.json();

The response is the created offer with serviceType: "electricity", the projected electricity object (now including the derived rate.estimatedMonthlyAt1000Kwh), and the standard offer fields.

Updating an electricity offer

Send only the sections you’re changing. The electricity object is merged onto the stored offer, so unrelated data is preserved:

PATCH /provider/offers/{id}

{
  "electricity": {
    "term": { "earlyTerminationFee": 200 },
    "plan": { "renewablePercentage": 100 }
  }
}

This changes only the early termination fee and renewable percentage; the existing rate, charges, and disclosures are untouched, and the derived headline is recomputed.

The electricity object is the only way to set an electricity offer’s pricing, term, plan, and disclosures — there is no flat/free-form alternative field to fall back to.

The charge breakdown (`rate.charges`)

A deregulated retail electricity bill has two legally distinct parts (Texas PUCT Rule 25.475 / the EFL): charges set by the provider (REP) and pass-through delivery charges set by the local utility (TDU, e.g. Oncor). rate.charges is an ordered list of charge lines that captures both, plus usage-tiered charges and threshold bill credits. Each charge line:

Field	Applies to	Meaning
`type`	all	`perKwh` \| `fixed` \| `credit`
`owner`	all	`provider` (REP) \| `utility` (TDU)
`label`	all	Display name, e.g. `"Energy Charge"`, `"TDU Delivery"`
`centsPerKwh`	`perKwh`	Rate in ¢/kWh
`amountDollars`	`fixed`, `credit`	Dollar amount (credits entered positive, subtracted from the bill)
`minUsageKwh` / `maxUsageKwh`	optional	Usage band (see below)

Usage bands:

perKwh bills only the kWh inside the band — "12¢ for the first 500 kWh" is { "minUsageKwh": 0, "maxUsageKwh": 500 }; "15¢ above 500 kWh" is { "minUsageKwh": 500 }.
fixed / credit applies only when total usage falls inside the band — e.g. "$125 credit if usage ≥ 1000 kWh" is a credit with { "minUsageKwh": 1000 }.

Bill estimate math

Offergrid folds charges into an itemized bill at any usage level. Line amounts are rounded to cents individually; subtotals and totals are sums of the rounded lines, so a breakdown always reconciles. Worked example at 1000 kWh for the create payload above:

Line	Owner	Calculation	Amount
Energy Charge	provider	12.5¢ × 1000 kWh	$125.00
TDU Meter Charge	utility	flat	$4.39
TDU Delivery	utility	4.2¢ × 1000 kWh	$42.00
Total			$171.39

Provider subtotal = $125.00
Utility subtotal = $46.39
Total = $171.39
Effective all-in rate = 171.39 × 100 ÷ 1000 = 17.139 ¢/kWh (the EFL metric)

rate.estimatedMonthlyAt1000Kwh in the response is this total at 1000 kWh.

Publishing requirements

POST /provider/offers/{id}/publish validates the offer. For electricity, the one contract-specific rule is:

rate.charges must include at least one provider perKwh energy charge.

If it doesn’t, publish returns 400 with structured validationErrors pointing at electricityDetails.charges. General offer requirements — name, SKU, description, at least one market, etc. — also apply.

Derived and read-only fields

rate.estimatedMonthlyAt1000Kwh is computed from rate.charges. It is output-only — setting it on a write has no effect.
Offergrid mirrors this figure into the generic monthlyPrice column so electricity offers sort and filter alongside fixed-price offers.

Storage

Electricity offer data lives in a dedicated typed relation — there is no free-form JSON blob involved. charges is the only accepted rate representation in the electricity contract; you never have to branch on a flat legacy rate format. Read everything electricity-related from .electricity.

Quick reference

You want to…	Use
Detect an electricity offer	top-level `serviceType === "electricity"`
Read pricing	`electricity.rate.charges` (+ derived `estimatedMonthlyAt1000Kwh`)
Read term / ETF	`electricity.term`
Read green %, perks	`electricity.plan`
Read EFL / PUCT	`electricity.disclosures`
Set pricing	send `electricity.rate.charges` on create/update
Publish	ensure ≥1 provider `perKwh` charge, then `POST …/publish`

Next steps

Creating Offers

The general offer create/publish flow

Service Categories

Fields for internet, electricity, and the other category

API Integration

Automate offer sync and order processing

API Reference

The ElectricityContract schema, field by field

Getting Started

Managing Offers

Order Fulfillment

Partner Management

Integration

Overview

Identifying an electricity offer

The `electricity` contract

Creating an electricity offer

Updating an electricity offer

The charge breakdown (`rate.charges`)

Bill estimate math

Publishing requirements

Derived and read-only fields

Storage

Quick reference

Next steps

Creating Offers

Service Categories

API Integration

API Reference

​Overview

​Identifying an electricity offer

​The electricity contract

​Creating an electricity offer

​Updating an electricity offer

​The charge breakdown (rate.charges)

​Bill estimate math

​Publishing requirements

​Derived and read-only fields

​Storage

​Quick reference

​Next steps

Creating Offers

Service Categories

API Integration

API Reference

Overview

Identifying an electricity offer

The `electricity` contract

Creating an electricity offer

Updating an electricity offer

The charge breakdown (`rate.charges`)

Bill estimate math

Publishing requirements

Derived and read-only fields

Storage

Quick reference

Next steps