Flip Energy API
    Flip Energy API
    • Overview
    • Important concepts
    • Authentication
    • Enrollment process
    • End-user app design
    • Monitoring / Telemetry
    • Control
    • Change log
    • Mobile App API
      • Devices
        • Create Device
        • Read Devices
        • Read Device
        • Update Device
        • Delete Device
      • Enrollments
        • Create Enrollment
        • Read Enrollments
        • Read Enrollment
        • Delete Enrollment
      • Events
        • Read Events
        • Read Event
        • Update Event Participation
      • Programs
        • Read Programs
        • Read Program
      • Sites
        • Read Site
        • Update Site
    • Cloud API
      • Sites
        • Get Site Token
        • Get Sites
      • Commissioning
        • Commission Site And Devices
      • Sessions
        • Sessions
      • Commands
        • Command Created
        • Update Command Status
      • Programs
        • Read Programs
      • Telemetry
        • Report Battery Telemetry
      • Webhooks
        • Overview
        • List of events
        • Webhook headers
        • Schemas
          • Command
          • Enrollment
          • Event

    Control

    The control flow happens in the background, from your cloud to Flip's cloud.

    Control flow#

    Commands are sent to devices whenever utilities desire, within the bounds of the programs. On average, commands should be sent to a specific device no more than once per day.

    Push mode / webhooks (recommended)#

    The preferred method for command delivery is Webhooks. Flip's cloud will deliver commands to an endpoint of your choice. See the Command Created for more details.

    Message queue mode#

    Depending on your system's capabilities, we may also send commands to your servers via HTTP webhooks, or we may open up a Kafka or MQTT messaging queue. The message payload will generally be equivalent to the Command Created payload.

    Polling mode (not recommended)#

    In order to receive commands in polling mode, poll our GET /v1/commands once every minute. Commands are shared in batches whenever we receive them from utilities. They may be sent 24 hours in advance or 10 minutes ahead. They will generally span 1 to 4 hours for batteries.
    We recommend scheduling commands directly into the BMS if supported, as it increases reliability and reduces latency. Alternatively, setting them in your cloud scheduler is acceptable as well. If you have no scheduling feature, please let us know, and we will instead send you commands "just in time".

    Anatomy of a command#

    Command
    id
    string <uuid>
    read-onlyrequired
    event_id
    string <uuid> | null 
    read-onlyrequired
    device_id
    string 
    required
    Example:
    xyz-123
    starts_at
    string <date-time>
    read-onlyrequired
    Time at which the action should start. Note that this may be before the event itself has started. For instance, in order to pre-charge a battery prior to a discharge event.
    Example:
    2025-04-30 12:00:00.000Z
    ends_at
    string <date-time> | null 
    read-onlyrequired
    Time at which the action should stop. If null, the action should continue until replaced by another one.
    Example:
    2025-04-30 14:00:00.000Z
    duration_s
    number  | null 
    read-onlyrequired
    Duration of the action, in seconds. If null, the action should continue until replaced by another one.
    Example:
    7200
    is_preparatory_action
    boolean 
    read-onlyrequired
    Whether the command is not part of the event itself but in preparation for the event. For instance, charging a battery before a discharging event.
    battery_commands
    object (BatteryCommand) 
    read-onlyrequired
    mode
    enum<string> 
    required
    The mode the battery should go into during this period.
    Allowed values:
    BACKUPCHARGEDISCHARGESAVINGSSELF_CONSUMPTIONSTANDBY
    power_mode
    enum<string>  | enum<null> 
    read-onlyoptional
    Specifies details for the action. Present if the state is CHARGE or DISCHARGE only
    Allowed values:
    FOLLOW_LOADSETPOINT
    setpoint_w
    integer  | null 
    read-onlyoptional
    Defines specific wattage level, only used if power_mode is SETPOINT. In Watts, always a non-zero positive integer.
    Example:
    5000
    enable_grid_import
    boolean  | null 
    read-onlyoptional
    Allow importing from the grid if charging.
    enable_grid_export
    boolean  | null 
    deprecated
    Allow exporting to the grid if discharging (battery only).
    backup_reserve_percentage
    integer  | null 
    optional
    The minimum state of charge the battery will keep when discharging.
    >= 0<= 100
    Example:
    20
    maximum_charge_percentage
    integer  | null 
    deprecated
    The maximum state of charge the battery will charge to, only when charging from the grid.
    >= 0<= 100
    Example:
    90
    status
    enum<string> 
    read-onlyrequired
    The status of the command itself. Only OK means that the command is happening.
    Allowed values:
    CANCELEDOKOPT_OUT
    Example:
    OK
    device_status
    enum<string> 
    required
    The acknowledgment of the command by the device. Only OK means that the device is ready to perform the command.
    Allowed values:
    FAILED_OFFLINEFAILED_FAULTOKPENDING
    Example:
    OK
    device_status_reason
    string  | null 
    optional
    It helps to share more human-readable information when setting the device_status. We will use it when we set device_status to PENDING, and feel free to use it as well when setting to OK or FAILED.
    Example:
    Command scheduled
    created_at
    string <date-time>
    read-onlyrequired
    updated_at
    string <date-time>
    read-onlyrequired
    A command is always specific to a device, and always related to an event. It will contain a single action and have a default device_state of PENDING.
    A command will always have a start and an end time. Its battery_commands.mode will be one of CHARGE, DISCHARGE, STANDBY, BACKUP, SAVINGS or SELF_CONSUMPTION. Depending on mode, it may also have a power_mode or a setpoint_w attribute.

    Confirming (for all modes)#

    When a command is sent to your servers, device_status is marked as PENDING in ours. We expect each command to be acknowledged once it has been scheduled by setting device_status to OK via PATCH /v1/commands/{id}. Alternatively, if you were not able to schedule it, set device_status to FAILED and describe a reason in device_status_reason. If we do not receive confirmation within 15 minutes we will consider the command to have failed and will send a new one.

    Overriding commands#

    We may update the status of a command, for instance if an event was canceled by a utility (CANCELED), or if a homeowner updated their participation (OPT_OUT). In this case, the device_status will be reset to PENDING and we will request again that you acknowledge the cancelation of the command on your end.
    Modified at 2024-07-08 20:33:32
    Previous
    Monitoring / Telemetry
    Next
    Change log
    Built with