Push charging sessions

POST /partner/sessions is for a partner that runs the back office of its customers' laadstations. You already receive every session from the charger, so you deliver them to Joulo yourself. We do not pull them from your system, and the customer never logs in with a charger brand.

We book each session on the customer's laadstation, exactly as the sessions of a charger we read ourselves. Every session counts toward the ERE position in GET /partner/ere-positions, and Joulo pays the customer every quarter.

The sequence

1. Upload the customer with POST /partner/customers and pre-couple the charge point. See below.
2. Let the customer onboard in your app with an auth-link. See Onboarding inside your app. When they activate, we attach the charge point to their account.
3. Push the history. Once GET /partner/customers shows the customer, send every finished session since 1 January 2026. Did the MID meter come later? Then start there.
4. Keep pushing. Send each session once it has stopped. Once a day is enough. Sooner is fine.

A session for a charge point we have not attached yet comes back as unknown_charger. Nothing is lost: send it again after step 2.

Pre-coupling the charge point

Send the charge point with the customer at upload. charger_brand is push, charger_id your own id for the charge point:

{
  "consent": true,
  "send_invite": false,
  "customers": [
    {
      "name": "Jan de Vries",
      "email": "[email protected]",
      "external_ref": "KLANT-8842",
      "postal_code": "6971LB",
      "house_number": "12",
      "charger_brand": "push",
      "charger_id": "PF-000123",
      "charger_vendor": "Alfen BV",
      "charger_model": "NG910-60027",
      "charger_serial": "ACE0012345",
      "charger_location": { "postal_code": "6971LB", "house_number": "12", "street": "Dorpsstraat", "city": "Brummen" }
    }
  ]
}

The upload answers with chargers: per created row the catalog model we matched and whether it has a MID meter. catalog_model: null means no match, and we review that charger by hand. location says whether we stored the address: used, ignored (no postcode or house number) or missing. mid_meter: false means the charger earns no ERE. A MID meter outside the charger, such as one in the meter cupboard, never counts for home charging.

Push sessions

Send at most 100 sessions per request, for any of your customers and in any order.

curl -X POST https://api.joulo.nl/functions/v1/api/partner/sessions \
  -H "Authorization: Bearer jpk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "sessions": [
      {
        "charger_id": "PF-000123",
        "transaction_id": "88213",
        "connector_id": 1,
        "started_at": "2026-10-01T18:02:11+02:00",
        "stopped_at": "2026-10-01T23:40:09+02:00",
        "meter_start_wh": 1203400,
        "meter_stop_wh": 1214950
      }
    ]
  }'

We book the meter range, never a number next to it. The verifier asks for the source data of the MID meter per session: transaction id, start, stop and the charge point. That is why the meter readings are required. We keep every session you send as evidence, also after a correction.

The answer

{
  "ok": true,
  "received": 2,
  "inserted": 1,
  "updated": 0,
  "unchanged": 0,
  "rejected": 1,
  "failed": 0,
  "results": [
    { "charger_id": "PF-000123", "transaction_id": "88213", "status": "inserted" },
    {
      "charger_id": "PF-000999",
      "transaction_id": "1204",
      "status": "rejected",
      "reason": "unknown_charger",
      "detail": "No active laadstation with this charger_id for your customers. Push sessions once the customer finished onboarding."
    }
  ]
}

results holds one entry per session, in request order. A rejected session never fails the request.

Resending and corrections

transaction_id is the key. Resending is always safe:

• The same values: unchanged. Resend a whole month if that is easier.
• More energy or a later stop: updated. We raise the booking.
• Less energy: rejected with lower_kwh. ERE may already be sold on the old value, so a correction downward goes through us.
• Another start: rejected with started_at_changed. A session is booked on its start, so a new start would count it twice. Contact us.

Rejection reasons

Not every session earns ERE

We book every session you send. Later we decide per session whether it counts, with the same rules as for every customer:

• the charger has a MID meter, and the session started after it was installed;
• the customer signed the machtiging, and the session falls inside it;
• the customer confirmed that the charger sits behind their EAN, and we approved the registration.

The ERE position in GET /partner/ere-positions shows the result per quarter. A session from before the MID meter never counts, also not when you send it later.

Errors

On the sandbox

The sandbox works the same. Mint your sandbox key in the partner portal after we enabled you. The key carries the same permission, and GET /partner/me shows it as session_push_source. Then upload a customer with a charge point, finish the onboarding with the sandbox helpers, and push sessions. Nothing reaches the NEa.