API Reference
The Flexprice REST API uses standard HTTP verbs, JSON request bodies, and Bearer token authentication. All endpoints are served over HTTPS.
Authentication
All requests must include an Authorization header with your API key:
Authorization: Bearer fp_live_...Retrieve API keys from Settings > API Keys in the Flexprice dashboard. Use separate keys for test and production environments.
Base URL
https://api.flexprice.org/v1
Errors
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | Missing or malformed request body |
| 401 | unauthorized | Invalid or missing API key |
| 404 | not_found | Resource does not exist |
| 409 | conflict | Idempotent request with conflicting body |
| 429 | rate_limited | Too many requests (retry after header present) |
| 500 | internal_error | Server-side error; contact support |
Events
Events represent individual units of usage. They are the raw material from which Flexprice calculates invoices.
/v1/events
Ingest a single event
| Parameter | Type | Required |
|---|---|---|
| event_name | string | required |
| customer_id | string | required |
| idempotency_key | string | required |
| timestamp | ISO 8601 | optional — defaults to now |
| properties | object | optional |
/v1/events/batch
Ingest up to 1,000 events in a single request
Request body: { "events": [ ...event objects ] }. Each event carries its own idempotency key.
/v1/events
List events (paginated, max 200/page)
Query params: customer_id, event_name, from (ISO 8601), to (ISO 8601), cursor, limit.
Customers
A customer maps to a paying entity in your product. Customer IDs must match the customer_id field in your events.
/v1/customers
Create a customer
| Parameter | Type | Required |
|---|---|---|
| external_id | string | required |
| name | string | optional |
| string | optional | |
| currency | ISO 4217 | optional — defaults to account currency |
| metadata | object | optional |
Pricing Plans
Pricing plans define the mapping from usage events to line items on an invoice. A plan has one or more charges, each tied to an event name.
/v1/pricing-plans
Create a pricing plan
Supported pricing_model values: flat, per_unit, graduated, volume, package, credit. See the quickstart for a graduated tier example.
/v1/pricing-plans/{id}
Retrieve a pricing plan
Returns full plan object including tier configuration.
Subscriptions
A subscription assigns a pricing plan to a customer and starts the billing cycle.
/v1/subscriptions
Create a subscription
| Parameter | Type | Required |
|---|---|---|
| customer_id | string | required |
| plan_id | string | required |
| start_date | ISO 8601 | optional — defaults to now |
| trial_end_date | ISO 8601 | optional |
Invoices
Invoices are generated automatically at the end of each billing period. Use the Invoices API to retrieve, void, or manually trigger generation.
/v1/invoices
List invoices
Query: customer_id, status (draft/open/paid/void), from, to.
/v1/invoices/{id}
Retrieve an invoice
Returns line items, amounts, tax, and payment status.
Credit Grants
Grant prepaid credit balances to customers. Credits are consumed before usage-based charges on each invoice.
/v1/credit-grants
Issue a credit grant
| Parameter | Type | Required |
|---|---|---|
| customer_id | string | required |
| amount | number (events) | required |
| expires_in_days | integer | optional |
| rollover | boolean | optional — default false |