Use this guide integrate Flatpeak’s Connect flow into your app using your existing framework.
We recommend reviewing the WebView integraiton guide before starting this guide. It provides helpful context on how the Connect flow works and what to expect during integration.
Connect uses a JSON-based conversation flow, not a traditional REST pattern.
1

Start the Connect Session

  1. Present a “Connect My Tariff” button (or similar UI control).
  2. Call the create-connect-token endpoint to generate a temporary connect_token.
  3. Use the token to launch the session via the session_restore endpoint.
Your app is now ready to interact with Connect.
2

Implement Connect pages

After calling session_restore, Connect replies with a JSON-based sequence of Page Objects, beginning with Postal Address. Each object represents a step in the flow and has its own reference page.Your app must:
  • Render the UI as required by the current Page Object,
  • Capture user input,
  • Send it back to the Connect API,
  • Receive the next Page Object in sequence.
This loop continues until the session completes.
3

Handle Completion

Once the flow completes:
  • You receive a session_complete page.
  • The customer is redirected to the callback_uri set in create-connect-token step. Use this to notify your backend.
  • Call the exchange-connect-token endpoint to exchange the connect_token for a permanent location_id, and store it with the customer’s address record in your backend.
4

Subscribe to Lifecycle Webhooks

Flatpeak keeps tariff data up to date post-connection. If customer action is needed (e.g. expired password), Flatpeak will generate an events and send it to you via webhook. Subscribe to them to inform users and guide them to re-connect when necessary.
5

Allow Configuration Changes

To let your customers review or update their tariffs post-connection, refer to the Tariff Settings Page guide to provide UI controls for customers to view, reconnect, or adjust their tariff flows—including commodity, export, or grid-fee options.

​
Next steps

After connecting the tariff, you can access:

​
Summary workflow

StepAction
1UI triggers Connect flow using create-connect-token and session_restore
2App loops through Page Objects: render, collect input, send response
3On session_complete, exchange token for location_id
4Subscribe to lifecycle webhooks (tariff.expiring, tariff.expired, tariff.fetch.failed)
5Offer tariff settings UI for reconnecting or adjusting flows
6Use scheduling, cost reporting, or raw rate endpoints as needed