Portal API Reference

The Customer Portal APIs are the customer-facing half of Flexprice. They authenticate with a portal session token rather than an API key, and every request is scoped to the one customer that token names. Use them if you build your own portal front end, or embed portal actions in your product. For how to obtain a token, see Customer Portal.

Authentication

Send the session token in the X-Session-Token header:

curl --request GET \
  --url https://api.cloud.flexprice.io/v1/customer/portal/info \
  --header 'X-Session-Token: <session_token>'

Property	Value
Base path	`/v1/customer/portal`
Header	`X-Session-Token`
Token lifetime	1 hour
Scope	One customer, in the tenant and environment the token was issued in

The session token is a credential. Do not log it, put it in a URL you send to a third party, or hand it to a payment provider as a return URL. See how the portal builds return URLs in Portal payments.

A suspended tenant’s portal endpoints stop serving requests, the same as the rest of the API.

Customer

Method	Path	Description
`GET`	`/info`	The authenticated customer’s profile
`PUT`	`/info`	Update the customer’s own profile fields
`GET`	`/usage`	Usage summary for the customer

Subscriptions

Method	Path	Description
`POST`	`/subscriptions`	List the customer’s subscriptions, paginated
`GET`	`/subscriptions/{id}`	One subscription

Invoices

Method	Path	Description
`POST`	`/invoices`	List the customer’s invoices, paginated
`GET`	`/invoices/{id}`	One invoice with its line items
`GET`	`/invoices/{id}/pdf`	Presigned URL for the invoice PDF. Pass `?url=true`
`POST`	`/invoices/{id}/pay`	Start payment for an invoice

Pay an invoice

curl --request POST \
  --url https://api.cloud.flexprice.io/v1/customer/portal/invoices/inv_01H.../pay \
  --header 'X-Session-Token: <session_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "idempotency_key": "portal-pay-inv_01H-1736180000",
    "success_url": "https://portal.yourapp.com?checkout_return=1"
  }'

{
  "payment_id": "pay_01H...",
  "invoice_id": "inv_01H...",
  "status": "pending",
  "amount": "149.00",
  "currency": "USD",
  "payment_action": { "type": "payment_link", "url": "https://provider.example.com/pay/xyz" }
}

There is no amount field. The charge comes from the invoice, so a customer cannot part-pay.

Wallets

Method	Path	Description
`POST`	`/wallets`	List the customer’s wallets
`GET`	`/wallets/{id}`	One wallet with its real-time balance
`GET`	`/wallets/{id}/transactions`	Transaction history. Accepts `limit` and `offset`
`POST`	`/wallets/{id}/top-up`	Top up a wallet
`PUT`	`/wallets/{id}/auto-topup`	Configure automatic top-ups

Top up a wallet

curl --request POST \
  --url https://api.cloud.flexprice.io/v1/customer/portal/wallets/wal_01H.../top-up \
  --header 'X-Session-Token: <session_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "credits_to_add": "100",
    "idempotency_key": "portal-topup-wal_01H-1736180000",
    "checkout": { "use_saved_method": false }
  }'

{
  "wallet_transaction": { "id": "wtx_01H...", "amount": "100.00", "credits": "100" },
  "checkout_session": {
    "id": "cs_01H...",
    "checkout_status": "initiated",
    "payment_provider": "chargebee",
    "payment_action": { "type": "checkout_url", "url": "https://provider.example.com/checkout/xyz" },
    "expires_at": "2026-01-06T18:00:00Z"
  }
}

idempotency_key is required. Omit checkout entirely to raise an invoice for the top-up instead of charging now. Credit reason, expiry and priority are pinned server-side and cannot be set from the portal.

Configure auto top-up

curl --request PUT \
  --url https://api.cloud.flexprice.io/v1/customer/portal/wallets/wal_01H.../auto-topup \
  --header 'X-Session-Token: <session_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "enabled": true,
    "threshold": "20",
    "amount": "100",
    "cooldown": { "value": 6, "unit": "hour" }
  }'

Send cooldown as { "value": 0, "unit": "hour" } to clear a stored cooldown. null leaves the existing one in place.

Checkout sessions

Method	Path	Description
`GET`	`/checkout-sessions/{id}`	Read a session’s current status
`POST`	`/checkout-sessions/{id}/cancel`	Abandon a session

{
  "id": "cs_01H...",
  "checkout_status": "completed",
  "payment_provider": "chargebee",
  "checkout_invoice_id": "inv_01H...",
  "checkout_payment_id": "pay_01H...",
  "expires_at": "2026-01-06T18:00:00Z",
  "completed_at": "2026-01-06T17:31:04Z"
}

`checkout_status`	Meaning
`initiated`	Created, nothing attempted yet
`pending`	In flight at the provider
`completed`	The gateway is done. Credits and payment records follow from the webhook
`failed`	Declined. Read `failure_reason`
`expired`	Timed out before completion

completed means the gateway finished, not that the wallet transaction exists yet. It is written by the provider’s webhook, which can land a moment later. Recheck the wallet rather than assuming the balance from the status.

Payment methods

Method	Path	Description
`GET`	`/payment-methods`	Saved methods, grouped by provider. Accepts a `providers` filter
`POST`	`/payment-methods`	Start a hosted card-capture session
`POST`	`/payment-methods/delete`	Remove a saved method
`POST`	`/payment-methods/default`	Promote a method to default at its provider

Delete and default both take payment_provider and payment_method_id. Adding returns a SetupAction, not a payment method, because nothing is stored until the customer completes the provider’s form.

{
  "provider": "chargebee",
  "action": { "type": "redirect", "url": "https://provider.example.com/setup/xyz" }
}

action.url is an unconstrained API string. Refuse any scheme that is not http or https before opening it.

Integrations and configuration

Method	Path	Description
`GET`	`/integrations`	Payment providers available to this session, with their capabilities
`GET`	`/config`	The tenant’s portal configuration, merged with the defaults

/integrations is derived from the tenant’s published connections. Use it to decide which actions to render rather than hard-coding a provider. See the capability matrix.

Analytics

Method	Path	Description
`POST`	`/analytics/revenue`	Usage and revenue analytics for the customer
`POST`	`/analytics/cost`	Cost analytics for the customer

Cost analytics returns your cost to serve the customer and your margin on them. Do not render those figures in a customer-facing surface.

Errors

Portal errors carry a hint written for the customer. Common ones:

Message	Cause
`This invoice cannot be paid yet`	The invoice is still a draft
`This invoice is already settled`	The invoice payment status is already succeeded
`Contact support to activate this subscription`	The invoice’s subscription is not in a collectable state
`credits must be greater than zero`	A top-up of zero or a negative amount
`top-up amount is below the minimum`	Under the tenant’s per-currency floor. Details name the minimum
`requested payment provider is not connected`	`payment_provider` names a gateway with no published connection
`capability is required`	A provider resolution request without a named capability

Customer Portal

Sessions, sections and the security model

Portal payments

The flow behind each payment endpoint

Portal configuration

The schema returned by /config

API Reference

The full Flexprice API

Introduction

Getting Started

CLI

Connect

Event Ingestion

Product Catalogue

Scenarios

Customers

Checkout

Subscriptions

Wallet

Invoices

Webhooks

Settings

Collectors

Data Exports

RBAC

Cookbooks

AI Cost Tracking

Contributing Guide

Exportable UI

Portal API Reference

Authentication

Customer

Subscriptions

Invoices

Pay an invoice

Wallets

Top up a wallet

Configure auto top-up

Checkout sessions

Payment methods

Integrations and configuration

Analytics

Errors

Customer Portal

Portal payments

Portal configuration

API Reference

​Authentication

​Customer

​Subscriptions

​Invoices

​Pay an invoice

​Wallets

​Top up a wallet

​Configure auto top-up

​Checkout sessions

​Payment methods

​Integrations and configuration

​Analytics

​Errors

​Related resources

Customer Portal

Portal payments

Portal configuration

API Reference

Authentication

Customer

Subscriptions

Invoices

Pay an invoice

Wallets

Top up a wallet

Configure auto top-up

Checkout sessions

Payment methods

Integrations and configuration

Analytics

Errors

Related resources