Skip to main content
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 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

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:

Create a session

Create a Connect session for every launch, even for the same user. A session launches Connect once and expires after 48 hours. Banner requests do not use it up. 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.

Launch

For the web app, open <connect_url>?connect_session=<session_id>&flow=TARIFF. Use a modal or bottom sheet, so notches and cutouts do not clip it. For a native build, start the session 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. Test with your own supplier account, or in test mode with the test supplier Antarctic Energy.

Handle completion

Subscribe to connect_session.complete in Console > Webhooks, with the Live or Test selector matching your secret key. The event carries the device_id. Retrieve the session 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 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.
  • 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.

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. Flatpeak deletes the upload when the session moves on. See Bill upload.

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 > Compliance before you go live. Connect shows them on the consent screen, as data protection law requires. Flatpeak is a data processor: it handles user data only on your instruction. See the Privacy Policy and the Data Processing Agreement.
Inaccurate or incomplete details can lead to account suspension.