> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Banner

> The banner route: fetch the banner for a placeholder in your app, and dismiss it.

A banner is a short text message Flatpeak places in your app. Your app asks for it from any screen, with the Connect session it holds. See the [Banners guide](/docs/energy-api/guides/platform/banners.md).

Hosted Connect shows banners on its own pages, and you build nothing for those.

A banner request does not start the session or use it up. One session serves banner requests until it expires or the user taps a banner.

> [tab] Preview
>
> ![A banner: a bolt icon, one line of text and a chevron](https://mintcdn.com/flatpeak-d495c19e/2B6nWUU4-c2pSD3E/images/busbar/connect/banner.png?fit=max\&auto=format\&n=2B6nWUU4-c2pSD3E\&q=85\&s=8efd1a4116a4c865a9f882169d3d1a73)

> [tab] Code
>
> ```bash Your request theme={"system"}
> curl --request POST \
>   --url https://connect.flatpeak.com \
>   --header 'Content-Type: application/json' \
>   --data '{
>   "connect_session": "cos_6587fa4362341be5b524de3b",
>   "route": "banner",
>   "placement": "HOME"
> }'
> ```
>
> ```json Connect response theme={"system"}
> {
>   "connect_session": "cos_6587fa4362341be5b524de3b",
>   "route": "banner",
>   "live_mode": true,
>   "actions": [
>     "CLICK",
>     "DISMISS"
>   ],
>   "data": {
>     "banner": {
>       "id": "bnr_68b7d3f2a1c4e5d6b7f8a901",
>       "text": "Switch to Smart Trading to earn up to €120 per kW of battery, every year.",
>       "icon": "bolt",
>       "background_color": "#0D9373",
>       "text_color": "#FFFFFF",
>       "end_time": "2026-06-30T23:59:59Z"
>     }
>   }
> }
> ```
>
> ```bash Your POST to Connect (click) theme={"system"}
> curl --request POST \
>   --url https://connect.flatpeak.com \
>   --header 'Content-Type: application/json' \
>   --data '{
>   "connect_session": "cos_6587fa4362341be5b524de3b",
>   "route": "banner",
>   "action": "CLICK",
>   "action_context": { "banner_id": "bnr_68b7d3f2a1c4e5d6b7f8a901", "placement": "HOME" }
> }'
> ```
>
> ```bash Your POST to Connect (dismiss) theme={"system"}
> curl --request POST \
>   --url https://connect.flatpeak.com \
>   --header 'Content-Type: application/json' \
>   --data '{
>   "connect_session": "cos_6587fa4362341be5b524de3b",
>   "route": "banner",
>   "action": "DISMISS",
>   "action_context": { "banner_id": "bnr_68b7d3f2a1c4e5d6b7f8a901" }
> }'
> ```
>
> #### Request fields
>
> | Field | Description |
> | :- | :- |
> | `placement` | Required. The kind of screen the placeholder is on. See [Placements](#placements). |
>
> #### Placements
>
> Flatpeak reads `placement` with the session's `device_type` to decide what to show. Use one placeholder per placement.
>
> | `placement` | The screen is about |
> | :- | :- |
> | `HOME` | The app's main screen |
> | `DEVICE` | One device: its status and controls |
> | `SCHEDULE` | When the device runs: a charging schedule, a heating programme, a delayed start, automations |
> | `INSIGHTS` | History, usage, costs or savings |
> | `SETTINGS` | Account or device settings |
> | `OTHER` | Anything else |
>
> #### Response fields
>
> `data.banner` is `null` when there is nothing to show.
>
> | Field | Description |
> | :- | :- |
> | `id` | Flatpeak ID of the banner. |
> | `text` | The message, in plain text, ready to display. Up to 120 characters. |
> | `icon` | [Font Awesome](https://fontawesome.com/icons) icon name, such as `bolt`. Map it to your own icon set, or leave it out. `null` when the banner has none. |
> | `background_color` | Background color, as `#RRGGBB`. `null`: use your own banner style. |
> | `text_color` | Text and icon color, as `#RRGGBB`. Its contrast with `background_color` is at least 4.5 to 1. `null`: use your own banner style. |
> | `end_time` | When the banner ends, in UTC. Stop showing a cached copy at this time. `null` when it has no set end. |
>
> #### Actions
>
> | Action | Result |
> | :- | :- |
> | `CLICK` | The user tapped the banner. Send `action_context.banner_id` and `action_context.placement`, the placement it was tapped in. Connect answers with the next route. Offered only when the banner opens something. |
> | `DISMISS` | The user closed the banner. Send `action_context.banner_id`, and Flatpeak stops returning it for the device. |
>
> #### After a tap
>
> `CLICK` starts the session. Handle the response like any other Connect response:
>
> | Connect returns | Do |
> | :- | :- |
> | [`session_redirect`](/docs/energy-api/reference/connect/tariff/redirects) | Send the user to `redirect_url`, as on any redirect |
> | Any other route | Render that page, because the banner opened a Connect flow |
>
> Create a new session for the next banner request.
>
> #### Errors
>
> | Error code | Description |
> | :- | :- |
> | `data_json_invalid` | Data does not conform to the JSON schema. Includes a missing or unknown `placement`. |
> | `action_invalid` | Action is not available on this route, or is not permitted in the current state. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.