Logo
Sign Up

Tariff API

Manage tariffs and tariff items — list, create, read, update, delete, and catalogue operations.

Tariff API Documentation

Overview

The Tariff API provides endpoints for managing tariffs and their pricing components (tariff items). Tariffs are associated with organizations and meter types, and can be cloned from a global read-only catalogue.

Authentication

All tariff endpoints require authentication. Include a valid Bearer token in the Authorization header: Authorization: Bearer <access_token>.

Account scoping

All endpoints require an account_id UUID to scope reads and writes to a specific organization.

  • List / read / delete — pass account_id as a query parameter
  • Create / update — include account_id in the JSON request body

Response format

All endpoints return a unified envelope:

{
  "success": true,
  "message": "optional human readable message",
  "data": {},
  "count": 1,
  "error": "error text"
}

Field reference

Tariff record (selected fields):

  • id (integer)
  • name (string)
  • description (string|null)
  • account_id (uuid)
  • meter_type (enum: ELECTRICITY | GAS | WATER | CARBON | SOLAR | GENSET | EV)
  • tariff_type (enum: FLAT | TIME_OF_USE | BLOCK)
  • currency (string)
  • tax_rate (decimal)
  • is_active (boolean)
  • effective_from / effective_to (ISO 8601 timestamp)
  • timezone (string)

Tariff item record (selected fields):

  • id (integer)
  • tariff_id (integer)
  • item_type_code (string)
  • price (decimal)
  • applies_to (string|null)
  • season (string|null)

Endpoints

Base path: /api/v1/tariffs

List Tariffs

GET /api/v1/tariffs

Query parameters:

  • account_id (uuid, required)
  • page (int, default 1)
  • limit (int, default 10, max 100)
  • query (string, optional — text search)
  • sortBy (string, default created_at)
  • sortOrder (asc | desc, default desc)
  • meter_type (enum: ELECTRICITY | GAS | WATER | CARBON | SOLAR | GENSET | EV, optional)
  • tariff_type (enum: FLAT | TIME_OF_USE | BLOCK, optional)
  • dso_id (int, optional)

Response 200 — list envelope with data array and count.

Create Tariff

POST /api/v1/tariffs

Request body (JSON):

  • account_id (uuid, required)
  • name (string, required)
  • description (string, optional)
  • meter_type (enum, optional)
  • tariff_type (enum, optional)
  • dso_id (int, optional)

Example:

{
  "account_id": "<account-uuid>",
  "name": "Residential Flat Rate",
  "description": "Standard residential plan",
  "meter_type": "ELECTRICITY",
  "tariff_type": "FLAT"
}

Response 201 — created tariff object in data.

Get Tariff

GET /api/v1/tariffs/:id

Query parameters:

  • account_id (uuid, required)

Returns 200 with the tariff and its nested tariff_items array.

Update Tariff

PUT /api/v1/tariffs/:id

Request body:

  • account_id (uuid, required)
  • Any updatable fields: name, description, timezone, notes, meter_type, tariff_type, dso_id

Response 200 — updated tariff object in data.

Delete Tariff

DELETE /api/v1/tariffs/:id

Query parameters:

  • account_id (uuid, required)

Response 204 — no content.

Catalogue guard: Attempts to create, update, or delete a tariff belonging to the catalogue account return 400 (Catalogue is read-only).

Catalogue (read-only)

The catalogue provides globally maintained, immutable tariff definitions that can be cloned into an organization's scope for customization. Catalogue tariffs and their items cannot be modified directly.

Base path: /api/v1/tariffs/catalogue

List Catalogue Tariffs

GET /api/v1/tariffs/catalogue

Query parameters:

  • page (int, default 1)
  • limit (int, default 10, max 100)
  • query (string, optional — fuzzy match against name/description)
  • sortBy (string, default created_at)
  • sortOrder (asc | desc, default desc)
  • meter_type (enum, optional)
  • tariff_type (enum, optional)

Response 200 — data array of catalogue tariff records with count.

Get Catalogue Tariff

GET /api/v1/tariffs/catalogue/:id

Path parameter:

  • id (integer)

Returns 200 with the catalogue tariff and its nested tariff_items. Returns 404 if not found.

Clone Catalogue Tariff

POST /api/v1/tariffs/catalogue/:id/clone

Creates a new fully mutable tariff in the destination account, copying all catalogue tariff fields and items.

Path parameter:

  • id (integer) — source catalogue tariff ID

Request body:

{
  "account_id": "<destination-account-uuid>",
  "name": "Optional override name"
}
  • account_id (uuid, required) — destination organization
  • name (string, optional) — falls back to source tariff name

Response 201 — cloned tariff with tariff_items array.

Errors: 400 invalid body, 404 catalogue tariff not found.

Tariff Items

List Items

GET /api/v1/tariffs/:id/items

Query parameters: page, limit, query, sortBy, sortOrder.

Returns paginated tariff_items.

Bulk Create Items

POST /api/v1/tariffs/:id/items

Body may be a single object or an array:

[
  { "price": 100.5, "item_type_code": "ENERGY" },
  { "price": 80.0, "item_type_code": "ENERGY", "season": "WINTER" }
]

Fields:

  • price (decimal, required)
  • item_type_code (string, required)
  • season (string, optional)
  • applies_to (string, optional)

Response 201 — array of created items.

Update Item

PUT /api/v1/tariffs/:id/items/:itemId

Body fields (all optional): price, item_type_code, season, applies_to.

Response 200 — updated item.

Delete Item

DELETE /api/v1/tariffs/:id/items/:itemId

Response 204 — no content.

Catalogue guard: Any attempt to modify items of a catalogue tariff returns 400 with Catalogue is read-only.