ERE positions

GET /partner/ere-positions • per-EAN ERE position for your attributed customers, in bulk

GET /partner/ere-positions returns the ERE position per connection (EAN) for every customer attributed to you, for one compliance year. It holds registered and sellable ERE, the expected net payout, and a per-quarter breakdown. Use it to reconcile positions per connection in bulk.

The connection (EAN) is the key. Every attributed customer with an EAN on their profile gets a row. That can happen during onboarding, before the registration is submitted. A customer without an EAN is not here yet. Find them in GET /partner/customers, or in GET /partner/drafts before they claim.

Attributed covers one more group than GET /partner/customers does. An energy supplier also gets a row for every customer who picked it as their supplier in their Joulo account. A customer linked to you only that way has no row in GET /partner/customers, so an EAN here can lack a matching customer there.

A row does not mean ERE yet. A new row starts empty: every amount is 0, quarters is [] and computed_at is null until the first recompute (see freshness). Read ere_eligible to see whether the customer has built up ERE.

Request

curl "https://api.joulo.nl/functions/v1/api/partner/ere-positions?year=2026&limit=200&offset=0" \
  -H "Authorization: Bearer jpk_live_..."

Query param	Required	Notes
`year`	no	Compliance year. Default `2026`.
`limit`	no	Page size, `1`–`500`. Default `200`.
`offset`	no	Page offset. Default `0`.

Response

{
  "positions": [
    {
      "ean": "871685920000123456",
      "external_ref": "KLANT-8842",
      "registration_status": "goedgekeurd",
      "ean_validation_status": "matched",
      "ere_eligible": true,
      "compliance_year": 2026,
      "registered_ere": 234.354,
      "allocatable_ere": 227.6865,
      "pending_ere": 6.6675,
      "expected_net_eur": 319.15,
      "ytd_expected_net_eur": 251.4,
      "realized_net_eur": 214.68,
      "quarters": [
        {
          "quarter": "2026 Q2",
          "registered_ere": 177.4433,
          "sold_ere": 177.4433,
          "unsold_ere": 0,
          "price_per_ere": 0.485,
          "realized_net_eur": 68.85,
          "net_eur_by_status": { "paid": 68.85, "payable": 0, "reserved": 0 },
          "final": true
        },
        {
          "quarter": "2026 Q3",
          "registered_ere": 50.2431,
          "sold_ere": 22.1,
          "unsold_ere": 28.1431,
          "price_per_ere": 0.4712,
          "realized_net_eur": 8.33,
          "net_eur_by_status": { "paid": 0, "payable": 0, "reserved": 8.33 },
          "final": false
        }
      ],
      "computed_at": "2026-07-21T10:00:00Z"
    }
  ],
  "limit": 200,
  "offset": 0,
  "count": 250,
  "compliance_year": 2026
}

Field	Meaning
`ean`	The connection this position belongs to.
`external_ref`	Your own customer reference, as supplied on upload. `null` when you did not supply one, when the customer did not come in through your upload, or when they objected under the GDPR. See Upload customers.
`registration_status`	Registration lifecycle: `concept` → `ingediend` → `in_review` → `goedgekeurd` (or `afgekeurd`).
`ean_validation_status`	EAN validation against the Dutch EAN register: `matched`, `unverified` (the register does not know the address yet, typical for new builds), `mismatched` (the register holds a different EAN at this address) or `unavailable` (the check could not run). See below.
`ere_eligible`	`true` when eligible ERE has been produced (sellable + in the settle buffer).
`registered_ere`	All eligible ERE this year: sellable plus what is still inside the 3-day settle buffer.
`allocatable_ere`	ERE that has cleared the settle buffer and is available to sell.
`pending_ere`	ERE inside the 3-day settle buffer • rolls into `allocatable_ere` over the next days.
`expected_net_eur`	Expected net payout to the customer for the full year (market-based, indicative).
`ytd_expected_net_eur`	Earned so far this year: realised, plus every ERE already charged but not yet sold, valued at market. Includes the 3-day settle buffer, so this covers all eligible kWh charged this year.
`realized_net_eur`	Net payout the customer has actually earned this year: every ERE that is sold, at the real trade price.
`quarters[]`	Per quarter: production, what was sold from it, and the money it produced. See below.
`computed_at`	When this position was last recomputed (see freshness below). `null` until the first recompute.
`count`	Total attributed connections, for pagination.

All amounts are the customer's net payout, never Joulo's gross. realized_net_eur is money the customer has actually earned, at the real trade price; expected_net_eur is a market-based forecast and never a guarantee. Only connections attributed to you are returned.

Realised euros per quarter

Each quarter reports what it produced and what that produced in money.

Field	Meaning
`registered_ere`	Eligible ERE produced in that quarter, including what is still in the 3-day settle buffer. The quarters therefore add up to the top-level `registered_ere`.
`sold_ere`	Of that, how much is sold.
`unsold_ere`	The remainder, still waiting for a sale.
`price_per_ere`	Weighted gross trade price of the sold part. `null` while nothing is sold. Every sale is public in the sale log.
`realized_net_eur`	Net to the customer over `sold_ere`: paid, payable and reserved together.
`net_eur_by_status`	The same amount split into `paid`, `payable` and `reserved`.
`final`	`true` when the quarter has ended and nothing is unsold. The quarter is then definitive.

A quarter becomes definitive when its ERE is sold, not when the calendar turns. The sale sets the price and therefore the payout. We sell in tranches, so a closed quarter keeps filling up for a while after it ends. Read final rather than comparing the quarter to today's date.

A reserved allocation is not a guess. The price is fixed the moment the trade is agreed. Only the commission can still change at settle. By the LEAST(fee at reserve, fee at settle) rule it can only drop, in the customer's favour. That is why reserved counts in realized_net_eur in full, exactly as the customer's own Opbrengsten tab counts it.

These are the same figures and the same three buckets the customer sees in the Joulo dashboard. If your app and our dashboard ever disagree, that is a bug on our side. Report it.

final also stays false when the customer produced ERE that Joulo cannot sell, for example while an IBAN is missing. That is the honest answer: nothing is realised on that quarter yet.

A quarter that has just ended also stays false while its last sessions are in the 3-day settle buffer. Those kWh still belong to that quarter, and a meter reading can change until the buffer clears.

Per connection, not per person

A position belongs to a connection, because the authorization to register with the NEa is bound to one party per EAN. Two people at the same address never build separate positions on one EAN at the same time. There is exactly one authorization holder per period.

Successive occupants do happen. What was registered under the previous occupant's authorization stays on their account and is paid out to them. The new occupant builds up from their own authorization date. In that case the same ean appears on two rows with a different external_ref: one per customer, each with its own build-up.

What a switch of energy supplier changes: nothing

The ERE position hangs on the connection and on the authorization the customer gave Joulo, not on who supplies the electricity. A customer who switches supplier keeps the same position, and this endpoint keeps returning the full Joulo position for the compliance year. That includes kWh from before the switch. Joulo registers retroactively from 1 January 2026, as far back as the charger connection can deliver historical sessions.

One limit: if another registration service provider held the authorization on that EAN earlier and already registered kWh, those periods cannot be registered again. Those ERE stay with that party and never appear here.

EAN validation status

mismatched means the Dutch EAN register knows the address, but holds a different EAN there. It happens in three ways:

The customer submitted with a motivation. The EAN is registered at this postcode and house number, but the address label differs (a missing addition, another street spelling). A Joulo admin reviews it before anything reaches the NEa.
The registration went in as unverified (new build). Our weekly check found the address later, with a different EAN.
The address changed after submission, and the recheck found a different EAN.

The customer cannot fix this alone: after submission the EAN and address are read-only. Advise them to send us a message from their Joulo dashboard. We check the EAN with them and correct it.

unverified needs no action from the customer. We recheck it every week.

Freshness and polling

Positions are recomputed roughly every 15 minutes; computed_at tells you how fresh each row is. They move slowly (a 3-day settle buffer plus the daily sync), so polling a few times per day is plenty. There is no push webhook.

We recompute positions only for partners with an active API key. After you mint your first key, rows can stay empty until the next recompute.

Access

This endpoint is on the API-key allowlist, so your jpk_live_ key can read it directly. It only ever returns connections attributed to your own account.

On this page