Site Power Limits

Site power limits control the total power output from all chargers on a site.

• Capacity limit: A hard cap. Flipturn will not allow the site to exceed this limit. Use for physical constraints (e.g. meter or transformer limits). Cannot be exceeded even by manual overrides.

• Cost limit: A soft cap. Use to avoid time of use rates or demand charges. Can be exceeded by a manual charging session override, setting an override schedule on a charger, or if the total minimum power for all vehicles plugged in exceeds the limit.

A site can have both a cost and a capacity limit. When both are set, the cost limit is applied first, and the capacity limit acts as a ceiling if more power is required by overrides than the cost limit allows.

Note: If either limit is set to 0, it will still allow vehicles to start charging at a minimum power, usually 8 A for L2 chargers and 5 kW for DCFCs.

POST /api/site/{site-id}/limits

Creates a new site power limit. Replaces the current limit of that type. Creating schedules that vary based on time of day or day of week is supported in app, and may be supported later via the API; please reach out to [email protected] if you have a use case for this API functionality.

Path parameters

• site-id: Flipturn site ID. Can be determined using the sites endpoint.

Request body

{
  sitePowerLimitSchedule: {
    type: 'cost' | 'capacity'; // See definitions above
    limit: number; // positive integer
    chargingRateUnit: 'W' | 'A'; // 'W' (watts) or 'A' (amps).
  }
}

Amp-based limits (chargingRateUnit: 'A') are not supported on sites that contain DCFC chargers.

Request example

This example will set a flat capacity limit of 100 kW on the site.

curl -X POST "https://api.getflipturn.com/api/site/42/limits" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "sitePowerLimitSchedule": {
      "type": "capacity",
      "limit": 100000,
      "chargingRateUnit": "W"
    }
  }'

To set an amp-based limit instead, set chargingRateUnit to "A" and provide limit in amps. The example below sets a 100 A capacity limit on a Level 2-only site:

curl -X POST "https://api.getflipturn.com/api/site/42/limits" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "sitePowerLimitSchedule": {
      "type": "capacity",
      "limit": 100,
      "chargingRateUnit": "A"
    }
  }'

Response

{
  sitePowerLimitScheduleId: string;
}

Example response

{
  "sitePowerLimitScheduleId": "YTA0",
}

GET /api/site/{site-id}/limits

Returns the active power limits for the site (cost and/or capacity). The response can contain up to one schedule per type. Will return an empty array if no schedules are set.

chargingRateUnit is "W" for watt-based limits (the units of the corresponding limit are watts) and "A" for amp-based limits (the units of limit are amps). Amp-based limits are only used on Level 2-only sites.

Path parameters

• site-id: Flipturn site ID.

Response

{
  sitePowerLimitSchedules: {
    id: string,
    createdAt: string, // DateTime from ISO 8601 as string
    source: string, // How the limit was created - "manual", "api", etc
    type: "cost" | "capacity",
    schedules: {
      daysOfWeek: number[],
      chargingRateUnit: "W" | "A",
      chargingSchedulePeriods: {
        limit: number; // watts if chargingRateUnit is "W", amps if "A"
        startPeriod: number;
      }[];
    }[]
  }[]
}

Example Request and Response

Request:

curl "https://api.getflipturn.com/api/site/42/limits" -H "Authorization: Bearer {token}"

Response:

{
  "sitePowerLimitSchedules": [
    {
      "id": "MTAx",
      "createdAt": "2024-01-15T10:00:00.000Z",
      "source": "api",
      "type": "cost",
      "schedules": [
        {
          "daysOfWeek": [1, 2, 3, 4, 5],
          "chargingRateUnit": "W",
          "chargingSchedulePeriods": [
            { "startPeriod": 0, "limit": 50000 },
            { "startPeriod": 28800, "limit": 80000 }
          ]
        },
        {
          "daysOfWeek": [6, 7],
          "chargingRateUnit": "W",
          "chargingSchedulePeriods": [{ "startPeriod": 0, "limit": 80000 }]
        }
      ]
    },
    {
      "id": "MTAy",
      "createdAt": "2024-01-10T14:00:00.000Z",
      "source": "manual",
      "type": "capacity",
      "schedules": [
        {
          "daysOfWeek": [1, 2, 3, 4, 5, 6, 7],
          "chargingRateUnit": "W",
          "chargingSchedulePeriods": [{ "startPeriod": 0, "limit": 100000 }]
        }
      ]
    }
  ]
}

Example response with an amp-based capacity limit (Level 2-only site):

{
  "sitePowerLimitSchedules": [
    {
      "id": "MTAz",
      "createdAt": "2024-01-15T10:00:00.000Z",
      "source": "api",
      "type": "capacity",
      "schedules": [
        {
          "daysOfWeek": [1, 2, 3, 4, 5, 6, 7],
          "chargingRateUnit": "A",
          "chargingSchedulePeriods": [{ "startPeriod": 0, "limit": 100 }]
        }
      ]
    }
  ]
}

DELETE /api/site/{site-id}/limits/{schedule-id}

Clears the site power limit for the given schedule.

Path parameters

• site-id: Site ID

• schedule-id: Schedule ID

Response

• 204: No response body, if delete is successful.

Errors

• 404: Site or schedule not found. Use GET to see the current schedules.

Example

Request:

curl -X DELETE "https://api.getflipturn.com/api/site/42/limits/MTAy" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \

Response: 204 No Content (empty body).