Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/soker90/finper/llms.txt

Use this file to discover all available pages before exploring further.

The Supplies API is organised as a three-level hierarchy: 
Property
└── Supply (utility contract: electricity, water, gas, or other)
     └── SupplyReading (billing period with start date, end date, amount, and cost)
Properties are residential or commercial premises. Each property has one or more supplies — utility contracts. Each supply accumulates readings (invoices or meter reads) over time. The optional tariff-comparison endpoint projects what your readings would have cost under alternative tariff structures.
Route mounting order in server.ts is critical: /api/supplies/properties and /api/supplies/readings are registered before /api/supplies. If the order is reversed, Express captures the literal strings properties and readings as the /:id parameter on the supplies router.

​
Supply types

ValueUtility
electricityElectricity contract
waterWater contract
gasGas contract
otherAny other utility (requires a name)

​
Properties — /api/supplies/properties

Properties have no GET endpoint of their own. They are returned nested within the supplies listing at GET /api/supplies.

​
POST /api/supplies/properties

Create a new property.
​
name
string
required
Property name (e.g. "Main Residence", "Holiday Apartment").
curl -X POST http://localhost:3008/api/supplies/properties \
  -H 'token: <your-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Main Residence"}'
Response 201 — the created property object.

​
PUT /api/supplies/properties/:id

Edit a property’s name.
​
id
string
required
Property ID.
​
name
string
required
New property name.
curl -X PUT http://localhost:3008/api/supplies/properties/68a1e... \
  -H 'token: <your-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Holiday Apartment"}'
Response 200 — the updated property object.

​
DELETE /api/supplies/properties/:id

Delete a property.
​
id
string
required
Property ID.
curl -X DELETE http://localhost:3008/api/supplies/properties/68a1e... \
  -H 'token: <your-jwt>'
Response 204 — no content.

​
Supplies — /api/supplies

​
GET /api/supplies

List all supplies for the authenticated user, grouped by property. 
curl http://localhost:3008/api/supplies \
  -H 'token: <your-jwt>'
Response 200 
[
  {
    "_id": "68a1e...",
    "name": "Main Residence",
    "supplies": [
      {
        "_id": "68b2f...",
        "name": "Electricity",
        "type": "electricity",
        "propertyId": "68a1e...",
        "contractedPowerPeak": 5.75,
        "contractedPowerOffPeak": 9.2,
        "currentPricePowerPeak": 0.104,
        "currentPricePowerOffPeak": 0.057,
        "currentPriceEnergyPeak": 0.18,
        "currentPriceEnergyFlat": 0.14,
        "currentPriceEnergyOffPeak": 0.09
      }
    ]
  }
]

​
POST /api/supplies

Create a new supply. For type: "other", name is required. For the remaining types, name is optional (defaults to the type label). Tariff fields are only meaningful for electricity supplies.
​
propertyId
string
required
ID of the parent property. Must exist and belong to the authenticated user.
​
type
string
required
One of electricity, water, gas, other.
​
name
string
Required when type is other. Optional for the remaining types.
​
contractedPowerPeak
number
Contracted peak power in kW (electricity only).
​
contractedPowerOffPeak
number
Contracted off-peak power in kW (electricity only).
​
currentPricePowerPeak
number
Current price per kW for peak power (electricity only).
​
currentPricePowerOffPeak
number
Current price per kW for off-peak power (electricity only).
​
currentPriceEnergyPeak
number
Current price per kWh for peak energy consumption (electricity only).
​
currentPriceEnergyFlat
number
Current price per kWh for flat-rate energy consumption (electricity only).
​
currentPriceEnergyOffPeak
number
Current price per kWh for off-peak energy consumption (electricity only).
curl -X POST http://localhost:3008/api/supplies \
  -H 'token: <your-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{
    "propertyId": "68a1e...",
    "type": "electricity",
    "contractedPowerPeak": 5.75,
    "contractedPowerOffPeak": 9.2,
    "currentPricePowerPeak": 0.104,
    "currentPricePowerOffPeak": 0.057,
    "currentPriceEnergyPeak": 0.18,
    "currentPriceEnergyFlat": 0.14,
    "currentPriceEnergyOffPeak": 0.09
  }'
Response 201 — the created supply object.

​
PUT /api/supplies/:id

Edit an existing supply. Accepts the same fields as the create endpoint (all required fields still required).
​
id
string
required
Supply ID.
curl -X PUT http://localhost:3008/api/supplies/68b2f... \
  -H 'token: <your-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{
    "propertyId": "68a1e...",
    "type": "electricity",
    "currentPriceEnergyPeak": 0.195
  }'
Response 200 — the updated supply object.

​
DELETE /api/supplies/:id

Delete a supply.
​
id
string
required
Supply ID.
curl -X DELETE http://localhost:3008/api/supplies/68b2f... \
  -H 'token: <your-jwt>'
Response 204 — no content.

​
GET /api/supplies/:id/tariffs-comparison

Compare the actual cost of your readings against alternative electricity tariffs.
​
id
string
required
Supply ID. Must be of type: "electricity" with contractedPowerPeak, contractedPowerOffPeak, and all five currentPrice* fields populated.
This endpoint only works for electricity supplies that have contracted power and current price fields fully configured. Returns HTTP 400 if the supply type is not electricity or if the required tariff configuration is missing.
curl http://localhost:3008/api/supplies/68b2f.../tariffs-comparison \
  -H 'token: <your-jwt>'
Response 200 — comparison of current tariff costs versus alternative tariff structures for all existing readings.

​
Supply Readings — /api/supplies/readings

​
GET /api/supplies/readings/supply/:supplyId

List all readings for a specific supply.
​
supplyId
string
required
Supply ID to retrieve readings for.
curl http://localhost:3008/api/supplies/readings/supply/68b2f... \
  -H 'token: <your-jwt>'
Response 200 
[
  {
    "_id": "68c3g...",
    "supplyId": "68b2f...",
    "startDate": 1701388800000,
    "endDate": 1704067200000,
    "amount": 87.43,
    "consumption": 340,
    "consumptionPeak": 120,
    "consumptionFlat": 80,
    "consumptionOffPeak": 140,
    "user": "alice"
  }
]

​
POST /api/supplies/readings

Create a new reading for a billing period.
​
supplyId
string
required
ID of the supply this reading belongs to.
​
startDate
number
required
Start of the billing period as a Unix timestamp (ms).
​
endDate
number
required
End of the billing period as a Unix timestamp (ms). Must be strictly greater than startDate.
​
amount
number
required
Total cost (invoice amount) for this period.
​
consumption
number
Total energy or volume consumed in this period. Optional.
​
consumptionPeak
number
Peak-hours consumption (electricity only). Optional.
​
consumptionFlat
number
Flat-rate consumption (electricity only). Optional.
​
consumptionOffPeak
number
Off-peak consumption (electricity only). Optional.
curl -X POST http://localhost:3008/api/supplies/readings \
  -H 'token: <your-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{
    "supplyId": "68b2f...",
    "startDate": 1701388800000,
    "endDate": 1704067200000,
    "amount": 87.43,
    "consumption": 340,
    "consumptionPeak": 120,
    "consumptionFlat": 80,
    "consumptionOffPeak": 140
  }'
Response 201 — the created reading object.

​
PUT /api/supplies/readings/:id

Edit an existing reading. Accepts the same fields as the create endpoint.
​
id
string
required
Reading ID.
curl -X PUT http://localhost:3008/api/supplies/readings/68c3g... \
  -H 'token: <your-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{
    "supplyId": "68b2f...",
    "startDate": 1701388800000,
    "endDate": 1704067200000,
    "amount": 91.10
  }'
Response 200 — the updated reading object.

​
DELETE /api/supplies/readings/:id

Delete a reading.
​
id
string
required
Reading ID.
curl -X DELETE http://localhost:3008/api/supplies/readings/68c3g... \
  -H 'token: <your-jwt>'
Response 204 — no content.

Build docs developers (and LLMs) love

Get started for freeTalk to us