Skip to main content
The Customer Portal is configured per tenant and environment. The configuration lists the portal’s sections, the widgets inside each section, and three brand colours. It is stored under the customer_portal_config setting key, and the portal fetches it on load. Anything you leave unset falls back to a default, so a tenant that has never touched the configuration still gets a complete portal.

Dashboard settings

Open the account menu at the bottom of the left navigation, select Settings, then go to Customer experience → Portal. The panel edits the same customer_portal_config setting that the API writes: The top of the panel lists the Tabs customers see. Click Save changes to apply. Changes apply to every portal session opened in that environment from the next page load. The panel exposes the controls the hosted portal applies. Each tab keeps its own layout: you can hide its parts, but cannot rearrange those parts. See What the portal applies. Cost and margin show what it costs your business to serve the customer and the margin on that usage. They are off by default. Enable them only when you intend to share those figures with customers. Under Usage properties, turn on Customers can group their usage by event property to enable the hosted portal’s grouping and filtering controls. This block is hidden while the Usage section is off. See Usage by Properties. Reset to defaults turns usage properties off.
Saving the configuration requires Super AdminThe portal configuration is stored through the settings API, whose writes are restricted to Super Admin regardless of the portal:write permission. A user without it sees the panel but cannot save. Through the API, use a Super Admin user’s API key. A service account key is refused.

Configuration schema

For anything the panel doesn’t cover, write the configuration through the settings API with PUT /v1/settings/customer_portal_config, sending the configuration as value. GET /v1/settings/customer_portal_config returns the current configuration, with defaults for anything you haven’t stored.
The example shows one section. A write replaces each top-level key it contains (theme, sections, analytics_config) and keeps the keys it leaves out. Nothing below the top level is merged:
  • Keep sections you want to configure. sections replaces the stored array. A section you leave out loses its stored settings, but its portal tab remains visible by default. To hide it, keep it with "enabled": false. An empty array shows every tab.
  • Send all three colours. theme replaces the stored theme, so a colour you leave out is cleared.
  • Fields outside the schema are dropped. The server keeps only the fields on this page and discards anything else without an error, such as a logo_url in the theme or a label on a tab.
Start from the value GET returns, change it, and send the whole key back. Reset to defaults in the dashboard, or DELETE /v1/settings/customer_portal_config, deletes the stored setting, including analytics_config.

Section fields

Widget fields

Widget types

Usage graph configuration

Valid presets are today, last_7_days, last_30_days, current_month and last_month.

Metric cards configuration

Cost metrics are your numbers, not the customer’sshow_cost_metrics exposes your cost to serve this customer and your margin on them. It is off by default. Turn it on only for a portal your own team uses.

What the portal applies

The hosted portal applies tab visibility, names and order, supported part controls, Usage date settings, and the primary color.
  • Tabs can be renamed, reordered and hidden. The standard tabs are Overview, Usage, Credits and Invoices. A missing section stays visible. If all sections are disabled, Overview remains as a fallback. Unknown section IDs, including the retired payment_methods section, do not create extra tabs.
  • Parts can be hidden, not rearranged. Overview supports the credit balance, payment methods and subscriptions. Usage supports the metric cards, usage graph, current usage and usage breakdown. Credits supports the wallet balance, auto top-up and transaction history. A supported part is visible by default when its configuration is missing; explicitly disable it to hide it.
  • Metric card settings apply. show_revenue_metric controls the spend summary, show_custom_metrics controls custom metrics, and show_cost_metrics exposes cost and margin metrics. Custom metric cards appear when the API returns custom metrics for the selected period. Keep cost metrics off for customer-facing portals unless you intend to share those numbers.
  • Usage graph settings apply. The first usage_graph configuration sets the available date presets, the default preset and custom-date access. With no recognized presets, every preset is offered. feature_filter_mode does not change the hosted portal.
  • Usage properties control grouping and filtering. The server applies the enabled flag and key lists in analytics_config.usage_properties.
  • primary_color is the brand color. See Theming.
The portal config endpoint also returns stored fields the hosted portal does not apply, such as secondary and tertiary colors, for a portal front end you build yourself.

Theming

The theme holds three colours, each a hex code such as #15547c, or empty: With no primary colour, or a value that isn’t a valid colour, the portal uses its own. The portal follows the customer’s light or dark system setting, and has no logo or font setting.
Text on the primary colour is white, so pick a colour dark enough to read white text on.

Reading the configuration from the portal

A portal session reads its own resolved configuration, already merged with the defaults:
Use this if you build your own portal front end against the Flexprice APIs and want to honour the same tenant configuration.

Customer Portal

Sessions, sections and the security model

Portal payments

Invoice payment, top-ups, auto top-up and saved cards

Settings

All tenant and environment setting keys

Exportable UI

Embed the same widgets directly in your own product