Tariffs API — EV Charging Pricing Configuration

Create pricing tariffs with energy, time, and flat fee components. Assign tariffs to chargers and configure time-of-use schedules.

The tariffs API lets you define how drivers are charged for energy. Each tariff is built from one or more pricing components — you can charge per kWh, per minute, add a flat session fee, or combine all three. Once defined, you assign tariffs to specific chargers and optionally apply scheduled pricing that changes rates at different times of day.

Create a tariff

POST /api/v1/billing/tariffs

name · string · required

Display name for the tariff (e.g. “Standard AC Rate”).

currency · string · required

ISO 4217 currency code (e.g. GBP, EUR, USD).

components · object[] · required

Array of pricing components that make up this tariff.

Show component properties

type · string · required

Component type. Accepted values: energy (per kWh), time (per minute), flat (per session), parking (per minute after charging stops).

price · number · required

Price per unit in the tariff currency.

step_size · number

Billing step size. Energy is billed in multiples of this value (e.g. 0.1 bills to the nearest 0.1 kWh). Defaults to 1.

min_duration_minutes · number

For time and parking components — billing does not start until this many minutes have elapsed.

tax_rate_percent · number · default: "0"

Tax percentage to apply on top of the tariff components (e.g. 20 for 20% VAT).

curl -X POST "https://api.dynamo-csms.com/api/v1/billing/tariffs" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Standard AC Rate",
    "currency": "GBP",
    "tax_rate_percent": 20,
    "components": [
      {
        "type": "flat",
        "price": 0.50
      },
      {
        "type": "energy",
        "price": 0.28,
        "step_size": 0.1
      },
      {
        "type": "parking",
        "price": 0.10,
        "min_duration_minutes": 10
      }
    ]
  }'

{
  "tariff_id": "tariff_XM3",
  "name": "Standard AC Rate",
  "currency": "GBP",
  "tax_rate_percent": 20,
  "components": [
    { "type": "flat", "price": 0.50, "step_size": null, "min_duration_minutes": null },
    { "type": "energy", "price": 0.28, "step_size": 0.1, "min_duration_minutes": null },
    { "type": "parking", "price": 0.10, "step_size": null, "min_duration_minutes": 10 }
  ],
  "created_at": "2024-06-01T10:00:00Z"
}

tariff_id · string

Unique identifier for the created tariff.

components · object[]

Pricing components as stored. Null fields use system defaults.

---

List tariffs

GET /api/v1/billing/tariffs

Returns all tariffs defined in your organisation.

currency · string

Filter by currency code.

limit · number · default: "50"

Maximum number of tariffs to return.

curl "https://api.dynamo-csms.com/api/v1/billing/tariffs" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "tariffs": [
    {
      "tariff_id": "tariff_XM3",
      "name": "Standard AC Rate",
      "currency": "GBP",
      "tax_rate_percent": 20,
      "charger_count": 42,
      "created_at": "2024-06-01T10:00:00Z"
    }
  ],
  "total": 1
}

---

Update a tariff

PUT /api/v1/billing/tariffs/{tariff_id}

Replaces all fields on a tariff. This does not retroactively change billing on existing sessions — changes apply to new sessions only.

tariff_id · string · required

The unique identifier of the tariff to update.

name · string · required

Updated display name.

currency · string · required

ISO 4217 currency code.

components · object[] · required

Full replacement set of pricing components.

tax_rate_percent · number

Updated tax rate.

curl -X PUT "https://api.dynamo-csms.com/api/v1/billing/tariffs/tariff_XM3" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Standard AC Rate",
    "currency": "GBP",
    "tax_rate_percent": 20,
    "components": [
      { "type": "energy", "price": 0.30, "step_size": 0.1 }
    ]
  }'

---

Delete a tariff

DELETE /api/v1/billing/tariffs/{tariff_id}

You cannot delete a tariff that is currently assigned to one or more chargers. Unassign the tariff from all chargers first.

tariff_id · string · required

The unique identifier of the tariff to delete.

curl -X DELETE "https://api.dynamo-csms.com/api/v1/billing/tariffs/tariff_XM3" \
  -H "Authorization: Bearer YOUR_API_KEY"

Returns 204 No Content on success.

---

Get tariff rates

GET /api/v1/tariffs/{tariff_id}/rates

Returns the pricing rates associated with a tariff. For time-of-use tariffs, this includes all rate bands.

tariff_id · string · required

The unique identifier of the tariff.

curl "https://api.dynamo-csms.com/api/v1/tariffs/tariff_XM3/rates" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "tariff_id": "tariff_XM3",
  "rates": [
    {
      "rate_id": "rate_A1",
      "label": "Peak",
      "energy_price_per_kwh": 0.35,
      "time_range": { "start": "07:00", "end": "21:00" },
      "days": ["mon", "tue", "wed", "thu", "fri"]
    },
    {
      "rate_id": "rate_A2",
      "label": "Off-peak",
      "energy_price_per_kwh": 0.18,
      "time_range": { "start": "21:00", "end": "07:00" },
      "days": ["mon", "tue", "wed", "thu", "fri", "sat", "sun"]
    }
  ]
}

---

Upload tariff rates

POST /api/v1/tariffs/{tariff_id}/rates

Replaces the rate bands for a tariff. Use this to set up time-of-use pricing.

tariff_id · string · required

The tariff to upload rates for.

rates · object[] · required

Array of rate band objects.

Show rate band properties

label · string · required

Human-readable label for this rate band.

energy_price_per_kwh · number · required

Energy price in the tariff currency.

time_range · object

Start and end time in HH:MM format. If omitted, the rate applies at all times.

days · string[]

Days of the week this rate applies. Accepted values: mon, tue, wed, thu, fri, sat, sun. Defaults to all days.

curl -X POST "https://api.dynamo-csms.com/api/v1/tariffs/tariff_XM3/rates" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rates": [
      {
        "label": "Peak",
        "energy_price_per_kwh": 0.35,
        "time_range": { "start": "07:00", "end": "21:00" },
        "days": ["mon", "tue", "wed", "thu", "fri"]
      },
      {
        "label": "Off-peak",
        "energy_price_per_kwh": 0.18,
        "time_range": { "start": "21:00", "end": "07:00" },
        "days": ["mon", "tue", "wed", "thu", "fri", "sat", "sun"]
      }
    ]
  }'

---

Delete tariff rates

DELETE /api/v1/tariffs/{tariff_id}/rates

Removes all rate bands from a tariff, reverting it to flat-rate pricing as defined by its components.

tariff_id · string · required

The unique identifier of the tariff.

curl -X DELETE "https://api.dynamo-csms.com/api/v1/tariffs/tariff_XM3/rates" \
  -H "Authorization: Bearer YOUR_API_KEY"

---

Create a tariff schedule

PUT /api/v1/tariffs/{tariff_id}/schedule

Defines a recurring schedule that automatically switches which rate band is active based on time and day. Schedules are evaluated at session start time.

tariff_id · string · required

The tariff to set a schedule for.

schedule · object[] · required

Array of schedule entries, each mapping a time window to a specific rate.

Show schedule entry properties

rate_id · string · required

The rate to apply during this window.

start_time · string · required

Start time in HH:MM (24-hour).

end_time · string · required

End time in HH:MM (24-hour).

days · string[] · required

Days of the week this window applies to.

curl -X PUT "https://api.dynamo-csms.com/api/v1/tariffs/tariff_XM3/schedule" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": [
      {
        "rate_id": "rate_A1",
        "start_time": "07:00",
        "end_time": "21:00",
        "days": ["mon", "tue", "wed", "thu", "fri"]
      },
      {
        "rate_id": "rate_A2",
        "start_time": "21:00",
        "end_time": "07:00",
        "days": ["mon", "tue", "wed", "thu", "fri", "sat", "sun"]
      }
    ]
  }'

---

Get tariff schedule

GET /api/v1/tariffs/{tariff_id}/schedule

Returns the current schedule for a tariff.

tariff_id · string · required

The unique identifier of the tariff.

curl "https://api.dynamo-csms.com/api/v1/tariffs/tariff_XM3/schedule" \
  -H "Authorization: Bearer YOUR_API_KEY"

---

Get current rate for a charger

GET /api/v1/tariffs/chargers/{charge_point_id}/current-rate

Returns the pricing rate that would apply to a session started on this charger right now.

charge_point_id · string · required

The OCPP identity of the charger.

curl "https://api.dynamo-csms.com/api/v1/tariffs/chargers/CP-001/current-rate" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "charge_point_id": "CP-001",
  "tariff_id": "tariff_XM3",
  "tariff_name": "Standard AC Rate",
  "rate_label": "Peak",
  "energy_price_per_kwh": 0.35,
  "currency": "GBP",
  "tax_rate_percent": 20,
  "evaluated_at": "2024-06-15T14:30:00Z"
}

---

Get charger tariff assignment

GET /api/v1/chargepoints/{charge_point_id}/tariff

Returns the tariff currently assigned to a charger.

charge_point_id · string · required

The OCPP identity of the charger.

curl "https://api.dynamo-csms.com/api/v1/chargepoints/CP-001/tariff" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "charge_point_id": "CP-001",
  "tariff_id": "tariff_XM3",
  "tariff_name": "Standard AC Rate",
  "assigned_at": "2024-06-01T09:00:00Z"
}

---

Assign a tariff to a charger

PUT /api/v1/chargepoints/{charge_point_id}/tariff

Assigns a tariff to a charger. New sessions on this charger will be billed under the assigned tariff immediately.

charge_point_id · string · required

The OCPP identity of the charger.

tariff_id · string · required

The tariff to assign to this charger.

curl -X PUT "https://api.dynamo-csms.com/api/v1/chargepoints/CP-001/tariff" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tariff_id": "tariff_XM3"}'

{
  "charge_point_id": "CP-001",
  "tariff_id": "tariff_XM3",
  "assigned_at": "2024-06-15T15:00:00Z"
}