Meter readings

Electricity meter readings (cumulative kWh) per pitch. Invoice generation uses the two most recent readings of a pitch: usage = latest − previous, priced at the site's configured GBP/kWh.

The meter reading object

{
  "id": "mR4nd0m",
  "object": "meter_reading",
  "pitch": "pitch-101",
  "pitch_number": "101",
  "pitch_accommodation_type": "Super Pitch",
  "reading": 15420.5,
  "date": 1793061121,
  "notes": null,
  "created": 1793061121,
  "metadata": {}
}

Endpoints

Method	Path	Description
GET	/v1/meter_readings	List (newest first; pitch filter for one pitch's history)
POST	/v1/meter_readings	Create one
POST	/v1/meter_readings/bulk	Paste endpoint — ingest a whole round
GET	/v1/meter_readings/{id}	Retrieve
DELETE	/v1/meter_readings/{id}	Delete (blocked when an invoice references it)

Bulk ingest (the paste endpoint)

Send an entire meter round in one request. Each row identifies its pitch by pitch (id) or pitch_number; date defaults to now. The response is a per-row report — valid rows are committed, invalid rows are listed with their index and a reason, so you can retry only the failures.

curl -s $API/v1/meter_readings/bulk -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: round-2026-11-30" -H "Content-Type: application/json" \
  -d '{"readings":[
        {"pitch_number":"101","reading":15420.5,"date":"2026-11-30"},
        {"pitch_number":"102","reading":10230.0,"date":"2026-11-30"},
        {"pitch":"pitch-103","reading":9033.25,"date":"2026-11-30"}
      ]}'

{
  "object": "bulk_meter_readings",
  "created": 2,
  "failed": 1,
  "data": [ ...created readings... ],
  "errors": [{"index": 2, "pitch_number": "999", "message": "No such pitch number: '999'"}]
}

Status codes: 200 when at least one row was committed (check errors for the rest), 400 when every row failed. With an Idempotency-Key, retrying the same request after a network failure replays the original result — no duplicate readings.

After ingesting, generate invoices with POST /v1/invoices/generate_all.