API reference

The REST API is the source of truth for everything in Flexprice. The API Reference tab is generated from the same OpenAPI document that produces the SDKs, the CLI, and the MCP server, so an endpoint documented there behaves identically in every client.

API conventions at a glance

Topic	Summary	Full page
Base URLs	`https://us.api.flexprice.io/v1` (US) or `https://api.cloud.flexprice.io/v1` (India). Pick the region your tenant was created in.	Introduction
Authentication	Send your key in the `x-api-key` header on every request. A key is bound to one environment, so there is no environment parameter.	Manage API keys
Request format	JSON bodies with `snake_case` fields. List endpoints are `POST /<resource>/search` with a filter body.	Introduction
Pagination	Offset based. Send `limit` and `offset`, read `pagination.offset` back for the next page, up to 1000 items per page.	Pagination
Errors	`{"success": false, "error": { "message": "..." }}` with a standard HTTP status. `409` is safe to retry.	Error responses
Idempotency	Events dedupe on `event_id`. Invoices, credit notes, wallet top-ups, and portal payments accept an `idempotency_key` field.	Idempotency and deduplication
Async ingestion	`POST /events` and `POST /events/bulk` return `202 Accepted`. Bulk accepts up to 1000 events per call.	Event Ingestion API
Rate limits	`429 Too Many Requests` when you exceed the limit. Back off and retry; the CLI exits with code `5`.	Error responses

API endpoints by billing lifecycle

The reference groups endpoints by resource. Read them in the order a billing lifecycle runs:

Catalog

Features, Plans, Prices, Entitlements, Addons, Coupons, Credit Grants

Customers and subscriptions

Customers, Subscriptions, Wallets, Checkout

Usage

Events, Usage analytics, Customer entitlements

Billing

Invoices, Payments, Credit Notes, Refunds

Platform

API keys, Users, Tenants, Environments, Integrations

Webhook payload reference

The reference also documents every webhook payload under Webhook Events. Those pages describe the JSON Flexprice sends to you, not endpoints you call. Start from the event catalog to find the event you want.

Customer portal API endpoints

Endpoints under /v1/customer/portal authenticate with a short-lived session token instead of an API key and are scoped to one customer. They are documented separately in the Portal API reference.

Trying an endpoint in the playground

Every endpoint page in the reference has a playground. Choose your region in the server selector, paste an API key, and send a request from the browser. For a terminal, flexprice get /customers sends the same request through the CLI.

Developers

API conventions at a glance

API endpoints by billing lifecycle

Webhook payload reference

Customer portal API endpoints

Trying an endpoint in the playground

Open the API Reference

Download the OpenAPI spec

Use an SDK instead

​API conventions at a glance

​API endpoints by billing lifecycle

​Webhook payload reference

​Customer portal API endpoints

​Trying an endpoint in the playground

Open the API Reference

Download the OpenAPI spec

Use an SDK instead

API conventions at a glance

API endpoints by billing lifecycle

Webhook payload reference

Customer portal API endpoints

Trying an endpoint in the playground