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 a compliance year: 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. Positions only appear once a customer has completed onboarding and produced eligible sessions • before that a customer shows up under GET /partner/drafts, not here.

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` if you did not supply one. See Upload customers.
`registration_status`	Registration lifecycle: `concept` → `ingediend` → `in_review` → `goedgekeurd` (or `afgekeurd`).
`ean_validation_status`	EAN validation: `matched`, `mismatched` or `unavailable`.
`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 ERE already charged but not yet sold, valued at market.
`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).
`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.
`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 is what sets the price and therefore the payout, and 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, and 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.

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 living at the same address therefore never build separate positions on the same 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 — including kWh from before the switch, since 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.

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.

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.