---
name: Consume Ergon Energy Retail consumer energy data as an accredited CDR recipient
description: >-
  The full consented flow for an ACCC-accredited Consumer Data Right data
  recipient reading an Ergon Energy Retail customer's accounts, service points,
  interval usage, distributed energy resources, billing, invoices, balances,
  concessions and payment schedule. Includes the bulk-versus-specific-ids
  pattern, the AEMO secondary data holder caveat, and the exact scope each
  operation needs.
api: openapi/energy-queensland-cds-energy-openapi.yml
base_url: not publicly discoverable — published through the authenticated CDR Register
auth: FAPI 1.0 Advanced OAuth2 + OIDC over mutual TLS, per-consumer consent
operations:
  - getCustomer
  - getCustomerDetail
  - listEnergyAccounts
  - getEnergyAccountDetail
  - listElectricityServicePoints
  - getElectricityServicePointDetail
  - listElectricityUsageBulk
  - listElectricityUsageForServicePoints
  - getElectricityServicePointUsage
  - listElectricityDERBulk
  - getElectricityDERForServicePoint
  - listEnergyAccountBalancesBulk
  - getEnergyAccountBalance
  - listEnergyAccountBillingBulk
  - getBillingForEnergyAccount
  - listEnergyAccountInvoicesBulk
  - getEnergyAccountInvoices
  - getEnergyAccountConcessions
  - getEnergyAccountPaymentSchedule
generated: '2026-07-27'
method: generated
---

# Consume Ergon Energy Retail consumer energy data (accredited only)

**Read this first.** Nothing in this skill is callable without ACCC
accreditation. There is no sandbox published by Energy Queensland, no API key,
no partner tier and no commercial path. The gate is statutory. If you are not an
accredited CDR data recipient (or acting under the CDR representative or trusted
adviser pathways), stop here and use
`skills/energy-queensland-read-ergon-tariff-plans.md` instead.

Coverage limit worth knowing before you build: Ergon Energy Retail serves
**regional Queensland** only. South East Queensland is contestable and retailed
by third parties, so an Energex-area customer's data comes from AGL, Origin,
EnergyAustralia or whoever they buy from — not from Energy Queensland.

## Prerequisites

1. Accreditation with the ACCC (unrestricted or sponsored).
2. Client credentials plus transport and signing certificates from the CDR Register certificate authority.
3. Conformance Test Suite (CTS) testing completed.
4. Dynamic Client Registration with the data holder using a CDR Register software statement assertion.
5. A consent the individual customer approved, naming the scopes you need.

Resolve the data holder's InfoSec and resource base URIs through the
**authenticated** portion of the CDR Register — they are not public. Anonymous
`/.well-known/openid-configuration` on `public.cdr.ergonretail.com.au` returns
HTTP 404 by design. `api.cdr.ergonretail.com.au` demands a client certificate at
TLS handshake; that is the mTLS gate, not a fault.

## Required headers on every authenticated call

| Header | Notes |
|---|---|
| `x-v` | Mandatory. Endpoint version. |
| `x-min-v` | Optional lower bound for negotiation. |
| `x-fapi-interaction-id` | RFC 4122 UUID, played back in the response. |
| `x-fapi-auth-date` | Time the customer last authenticated. Customer-present calls. |
| `x-fapi-customer-ip-address` | Present for customer-present calls, **absent** for unattended calls — this is what distinguishes the two traffic classes for rate limiting and performance thresholds. |
| `x-cds-client-headers` | Base64 client headers. |

## Step 1 — identify the customer

`getCustomer` (`common:customer.basic:read`) then, if consented,
`getCustomerDetail` (`common:customer.detail:read`).

## Step 2 — enumerate accounts

`listEnergyAccounts` (`energy:accounts.basic:read`), filterable by
`open-status`. Each account carries `accountId` and `plans[]`, and each plan
carries `servicePointIds[]` — that array is the join to everything metered.

`getEnergyAccountDetail` (`energy:accounts.detail:read`) adds plan detail and
authorised contacts.

## Step 3 — pick bulk or specific

Every high-volume domain has a **bulk GET** and a **POST for specific ids**:

| Domain | Bulk | Specific ids | Scope |
|---|---|---|---|
| Balances | `listEnergyAccountBalancesBulk` | `listEnergyAccountBalancesSpecificAccounts` | `energy:billing:read` |
| Billing | `listEnergyAccountBillingBulk` | `listEnergyAccountBillingForSpecificAccounts` | `energy:billing:read` |
| Invoices | `listEnergyAccountInvoicesBulk` | `listEnergyInvoicesForSpecificAccounts` | `energy:billing:read` |
| Usage | `listElectricityUsageBulk` | `listElectricityUsageForServicePoints` | `energy:electricity.usage:read` |
| DER | `listElectricityDERBulk` | `listElectricityDERForSpecificServicePoints` | `energy:electricity.der:read` |

The POST variants create nothing — they exist only to carry an id list in a
body. There is no idempotency key anywhere on this surface, and none is needed.

Note the error-code shift: an unavailable or invalid id returns **404** when it
was supplied in the URI, and **422** when it was supplied in the request body
(`urn:au-cds:error:cds-energy:Authorisation/UnavailableEnergyAccount` /
`InvalidEnergyAccount`, and the ServicePoint equivalents).

## Step 4 — metered data

- `listElectricityServicePoints` (`energy:electricity.servicepoints.basic:read`) and `getElectricityServicePointDetail` (`...detail:read`) — NMI, jurisdiction, classification, status, meters, registers, distribution loss factor, related market participants.
- `getElectricityServicePointUsage` / `listElectricityUsageBulk` with `interval-reads`, `oldest-date`, `newest-date` — basic or interval reads.
- `getElectricityDERForServicePoint` / `listElectricityDERBulk` — approved capacity, phases, AC connections, DER devices, protection mode, islandable installation.

**Shared Responsibility caveat:** service point, usage and DER data originate
with **AEMO** as the CDR secondary data holder, not with Ergon. When AEMO is
unavailable these calls fail without breaching Ergon's own availability
obligation, and the error payload uses `PrimaryErrorV1`, which sets
`isSecondaryDataHolderError: true`. Handle that flag explicitly — it tells you
to retry rather than to treat the consent as broken.

## Step 5 — money

`getEnergyAccountBalance`, `getBillingForEnergyAccount` (usage, demand, once-off,
other-charge and payment transaction types), `getEnergyAccountInvoices`,
`getEnergyAccountConcessions` (`energy:accounts.concessions:read`) and
`getEnergyAccountPaymentSchedule` (`energy:accounts.paymentschedule:read`).

Billing, invoice and usage operations take date ranges — an unparseable date
returns `400 urn:au-cds:error:cds-all:Field/InvalidDateTime`.

## Pagination, throttling and identifiers

- `page` / `page-size` (default 25, max 1000), with `meta.totalRecords`, `meta.totalPages` and `links`.
- Customer-present: 10 TPS per customer, 50 TPS per software product, unlimited sessions. Unattended: 20 sessions per day per customer per software product, 100 calls per session, 5 TPS per session. See `rate-limits/energy-queensland-rate-limits.yml`.
- `accountId` and `servicePointId` are **consent-scoped tokenised** values. They differ per data recipient and do not survive consent revocation — never persist them as durable cross-system keys.

## Before you start a run

Poll `getStatus` and `getOutages` on
`https://public.cdr.ergonretail.com.au/cds-au/v1` — anonymous, cheap, and the
contractual availability signal. See
`skills/energy-queensland-check-cdr-availability.md`.