> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # Connect > Put Connect in your app so users connect their tariff: hosted, self-hosted or native on the Connect API. Connect is the flow where your user connects their tariff. Run it in a WebView, or build your own UI on the Connect API. The [Quickstart](/docs/energy-api/guides/quickstart.md) runs it end to end. ## How it works 1. Your backend creates the user, location and device, then a Connect session for the device. 2. Your app launches Connect with the session ID and `flow=TARIFF`. 3. The user connects their tariff. 4. Flatpeak sends `connect_session.complete`. 5. Your backend retrieves the session. If `price_available` is `true`, read prices. ## Three ways to run it | Option | `connect_url` | What you do | | :- | :- | :- | | Hosted by Flatpeak | `https://busbar.connect-web.flatpeak.com` | Open it in a WebView. This is the fastest option | | Hosted by you | Your domain | Fork [flatpeak-connect-web](https://github.com/flat-peak/flatpeak-connect-web) and serve it under your branding | | Native | A deep link into your app, such as `yourapp://flatpeak/connect` | Build every screen on the [Connect API](/docs/energy-api/reference/connect/tariff/start-session.md). This is the recommended option | The supplier login always runs in a WebView. The supplier controls it, and you cannot restyle the login or consent pages. To run the web app yourself: ```bash theme={"system"} git clone https://github.com/flat-peak/flatpeak-connect-web.git cd flatpeak-connect-web npm install export FLATPEAK_CONNECT_URL=https://connect.flatpeak.com npm run dev # http://localhost:7070 ``` ## Create a session [Create a Connect session](/docs/energy-api/reference/connect-sessions/create.md) for every launch, even for the same user. A session launches Connect once and expires after 48 hours. [Banner](/docs/energy-api/guides/platform/banners.md) requests do not use it up. | Field | Value | | :- | :- | | `device_id` | The device the user is connecting | | `connect_url` | Where Connect runs. Connect returns the user here after the supplier login | | `callback_url` | Where the user lands after completing or leaving Connect | | `supplier_id` | Optional. Preselects the supplier, so the user skips supplier selection | Pass `postal_address` when you create the location, because Flatpeak uses it to find the supplier and tariff. Without it, Connect asks the user on [Address](/docs/energy-api/reference/connect/tariff/address.md). ## Launch For the web app, open `?connect_session=&flow=TARIFF`. Use a modal or bottom sheet, so notches and cutouts do not clip it. For a native build, [start the session](/docs/energy-api/reference/connect/tariff/start-session.md) with `route` `session_start` and `flow` `TARIFF`. Each response is a page. Routes run in this order: `session_start`, `address_input`, `supplier_select`, then the supplier login, `library_select` or `price_input`, then `tariffs_summary`. Implement every [tariff page](/docs/energy-api/reference/connect/tariff/supplier.md). Test with your own supplier account, or in test mode with the test supplier [Antarctic Energy](/docs/energy-api/guides/platform/test-supplier.md). ## Handle completion Subscribe to `connect_session.complete` in [Console](https://console.flatpeak.com/) > **Webhooks**, with the Live or Test selector matching your secret key. The event carries the `device_id`. [Retrieve the session](/docs/energy-api/reference/connect-sessions/retrieve.md) and, if `price_available` is `true`, read prices. ## Manage a connection Create a session and launch with `flow=TARIFF`. A user with a connected tariff lands on [Tariff summary](/docs/energy-api/reference/connect/tariff/summary.md) to review it, report an error or disconnect. A user without one enters the connection flow. ## How Connect finds the tariff Connect tries the most accurate method first and falls back when one fails, such as when the user cancels the login. | Order | `connection_type` | How | | :- | :- | :- | | 1 | `DIRECT` | The user logs in to their supplier. Flatpeak fetches the billed tariff and keeps it current | | 2 | `LIBRARY` | The user picks their tariff from the Flatpeak library | | 3 | `MARKET` | Price input for a dynamic tariff. Flatpeak picks the market index and adds taxes and grid fees | | 3 | `MANUAL` | Price input for a fixed or time-of-use tariff. The user types the prices, or a bill supplies them | * The address narrows every choice: suppliers by country and state, library tariffs by region, the market index by bidding zone. * If one library tariff matches the address, Connect selects it. If none matches, Connect lists all of the supplier's tariffs. * Connect adds grid fees where it knows them; otherwise the user can enter them. * A tariff that applies to one device only becomes a [device tariff](/docs/energy-api/guides/key-concepts.md#device-tariffs). ## Uploading a bill Connect offers a bill upload where the user would otherwise type: manual tariff setup and price input. Flatpeak reads the supplier, unit rates, standing charges, taxes and bill date from photos or a PDF. | The bill shows | Result | | :- | :- | | A supplier with a `DIRECT` integration | The supplier login | | Unit rates only | Price input, prefilled and editable. The tariff is `MANUAL` | | Neither | Bill not recognized. The user tries again or enters prices | Flatpeak deletes the upload when the session moves on. See [Bill upload](/docs/energy-api/reference/connect/tariff/bill-upload.md). ## Asset vocabulary If you build Connect natively, name the asset by its `device_type`: "your battery", "your vehicle", "your charger". `OTHER` falls back to "device". At identity moments, use `hardware.model_name` where the device has one: "Your Nova Home Battery is now connected". Select whole translated strings per type and do not substitute the noun into a template. Hosted Connect does this for you. The location's `country_code` selects market terms the same way: a US user sees "utility" and "rate plan" where a UK user sees "supplier" and "tariff". Routes and field names never change. ## Company details Enter your company details in [Console](https://console.flatpeak.com) > **Compliance** before you go live. Connect shows them on the consent screen, as data protection law requires. | Field | Value | | :- | :- | | Company trading name | The name the user sees on the consent screen | | Company legal name | Your registered legal entity | | Terms of Service URL | Must name Flatpeak as a sub-processor and link to your help page | Flatpeak is a data processor: it handles user data only on your instruction. See the [Privacy Policy](https://flatpeak.com/legal/privacy) and the [Data Processing Agreement](https://flatpeak.com/legal/data-processing-agreement). > [!WARNING] > > Inaccurate or incomplete details can lead to account suspension. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.