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.

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

Creates a new site power limit. Replaces the current limit of that type. Can be set either as a flat limit or as a schedule that varies among time of day or days of the week.

Path parameters

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

Request body option A: flat limit

{
  sitePowerLimitSchedule: {
    type: 'cost' | 'capacity'; // See definitions above
    limit: number;
    chargingRateUnit: 'W'; // Required to be 'W' for now, will support other units in the future
  }
}

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"
    }
  }'

Request body option B: daily or weekly schedule

{
  sitePowerLimitSchedule: {
    type: "cost" | "capacity";
    schedules: {
      daysOfWeek: number[];
      chargingRateUnit: "W";
      chargingSchedulePeriods: {
        startPeriod: number;
        limit: number;
      }[];
    }[];
  };
}

Here's a detailed description of all the fields:

• type: "cost" or "capacity". See the description of these above.

• schedules: Array of schedules that define limits for different days of the week. They must cover all days of the week, with each day appearing in exactly one schedule. Each schedule contains:

  • daysOfWeek: Array of integers 1–7 for when this schedule applies (Monday = 1, Sunday = 7).

  • chargingRateUnit: Must be "W" for now, other units will be supported in the future.

  • chargingSchedulePeriods: Array of limits that apply to each day in this schedule. Each period defines:

    • startPeriod: When this limit takes effect each day, measured in seconds from midnight. For example, 0 = 12:00 AM (midnight) and 64800 = 6:00 PM (18:00). Each schedule must include a period with startPeriod: 0.

    • limit: The limit for this period in units specified by chargingRateUnit.

Request example

This example sets a cost-based schedule:

• Weekdays, Mon–Fri, allow 100 kW except between 4:00 PM and 9:00 PM when the limit is 0, to avoid on-peak rates

• Weekends, Sat–Sun, allow 100 kW all day

Note that when the cost limit is set to 0, it will still allow vehicles to charge at minimum power, usually 8 A for L2 chargers and 5 kW for DC.

curl -X POST "https://api.getflipturn.com/api/site/42/limits" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "sitePowerLimitSchedule": {
      "type": "cost",
      "schedules": [
        {
          "daysOfWeek": [1, 2, 3, 4, 5],
          "chargingRateUnit": "W",
          "chargingSchedulePeriods": [
            { "startPeriod": 0, "limit": 100000 },
            { "startPeriod": 57600, "limit": 0 },
            { "startPeriod": 75600, "limit": 100000 }
          ]
        },
        {
          "daysOfWeek": [6, 7],
          "chargingRateUnit": "W",
          "chargingSchedulePeriods": [
            { "startPeriod": 0, "limit": 100000 }
          ]
        }
      ]
    }
  }'

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.

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",
      chargingSchedulePeriods: {
        limit: number;
        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 }]
        }
      ]
    }
  ]
}

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).