> ## Documentation Index
> Fetch the complete documentation index at: https://dynamo-csms.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`

<ParamField body="name" type="string" required>
  Display name for the tariff (e.g. "Standard AC Rate").
</ParamField>

<ParamField body="currency" type="string" required>
  ISO 4217 currency code (e.g. `GBP`, `EUR`, `USD`).
</ParamField>

<ParamField body="components" type="object[]" required>
  Array of pricing components that make up this tariff.

  <Expandable title="component properties">
    <ParamField body="type" type="string" required>
      Component type. Accepted values: `energy` (per kWh), `time` (per minute), `flat` (per session), `parking` (per minute after charging stops).
    </ParamField>

    <ParamField body="price" type="number" required>
      Price per unit in the tariff currency.
    </ParamField>

    <ParamField body="step_size" type="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`.
    </ParamField>

    <ParamField body="min_duration_minutes" type="number">
      For `time` and `parking` components — billing does not start until this many minutes have elapsed.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="tax_rate_percent" type="number" default="0">
  Tax percentage to apply on top of the tariff components (e.g. `20` for 20% VAT).
</ParamField>

```bash theme={null}
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
      }
    ]
  }'
```

```json theme={null}
{
  "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"
}
```

<ResponseField name="tariff_id" type="string">
  Unique identifier for the created tariff.
</ResponseField>

<ResponseField name="components" type="object[]">
  Pricing components as stored. Null fields use system defaults.
</ResponseField>

***

## List tariffs

`GET /api/v1/billing/tariffs`

Returns all tariffs defined in your organisation.

<ParamField query="currency" type="string">
  Filter by currency code.
</ParamField>

<ParamField query="limit" type="number" default="50">
  Maximum number of tariffs to return.
</ParamField>

```bash theme={null}
curl "https://api.dynamo-csms.com/api/v1/billing/tariffs" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "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.

<ParamField path="tariff_id" type="string" required>
  The unique identifier of the tariff to update.
</ParamField>

<ParamField body="name" type="string" required>
  Updated display name.
</ParamField>

<ParamField body="currency" type="string" required>
  ISO 4217 currency code.
</ParamField>

<ParamField body="components" type="object[]" required>
  Full replacement set of pricing components.
</ParamField>

<ParamField body="tax_rate_percent" type="number">
  Updated tax rate.
</ParamField>

```bash theme={null}
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}`

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

<ParamField path="tariff_id" type="string" required>
  The unique identifier of the tariff to delete.
</ParamField>

```bash theme={null}
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.

<ParamField path="tariff_id" type="string" required>
  The unique identifier of the tariff.
</ParamField>

```bash theme={null}
curl "https://api.dynamo-csms.com/api/v1/tariffs/tariff_XM3/rates" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "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.

<ParamField path="tariff_id" type="string" required>
  The tariff to upload rates for.
</ParamField>

<ParamField body="rates" type="object[]" required>
  Array of rate band objects.

  <Expandable title="rate band properties">
    <ParamField body="label" type="string" required>Human-readable label for this rate band.</ParamField>
    <ParamField body="energy_price_per_kwh" type="number" required>Energy price in the tariff currency.</ParamField>
    <ParamField body="time_range" type="object">Start and end time in `HH:MM` format. If omitted, the rate applies at all times.</ParamField>
    <ParamField body="days" type="string[]">Days of the week this rate applies. Accepted values: `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun`. Defaults to all days.</ParamField>
  </Expandable>
</ParamField>

```bash theme={null}
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.

<ParamField path="tariff_id" type="string" required>
  The unique identifier of the tariff.
</ParamField>

```bash theme={null}
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.

<ParamField path="tariff_id" type="string" required>
  The tariff to set a schedule for.
</ParamField>

<ParamField body="schedule" type="object[]" required>
  Array of schedule entries, each mapping a time window to a specific rate.

  <Expandable title="schedule entry properties">
    <ParamField body="rate_id" type="string" required>The rate to apply during this window.</ParamField>
    <ParamField body="start_time" type="string" required>Start time in `HH:MM` (24-hour).</ParamField>
    <ParamField body="end_time" type="string" required>End time in `HH:MM` (24-hour).</ParamField>
    <ParamField body="days" type="string[]" required>Days of the week this window applies to.</ParamField>
  </Expandable>
</ParamField>

```bash theme={null}
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.

<ParamField path="tariff_id" type="string" required>
  The unique identifier of the tariff.
</ParamField>

```bash theme={null}
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.

<ParamField path="charge_point_id" type="string" required>
  The OCPP identity of the charger.
</ParamField>

```bash theme={null}
curl "https://api.dynamo-csms.com/api/v1/tariffs/chargers/CP-001/current-rate" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "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.

<ParamField path="charge_point_id" type="string" required>
  The OCPP identity of the charger.
</ParamField>

```bash theme={null}
curl "https://api.dynamo-csms.com/api/v1/chargepoints/CP-001/tariff" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "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.

<ParamField path="charge_point_id" type="string" required>
  The OCPP identity of the charger.
</ParamField>

<ParamField body="tariff_id" type="string" required>
  The tariff to assign to this charger.
</ParamField>

```bash theme={null}
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"}'
```

```json theme={null}
{
  "charge_point_id": "CP-001",
  "tariff_id": "tariff_XM3",
  "assigned_at": "2024-06-15T15:00:00Z"
}
```