Quickstart

This guide walks you through sending your first usage event, creating a pricing plan, and verifying your first invoice. Total time: under 30 minutes.

Prerequisites: A Flexprice account (free Developer tier). Sign up here — no credit card required.

1

Install the SDK

Install the Flexprice SDK for your language. All SDKs wrap the REST API and handle authentication, retry logic, and idempotency key generation.

npm install @flexprice/sdk
pip install flexprice
go get github.com/flexprice/flexprice-go
gem install flexprice

Retrieve your API key from the Settings > API Keys page in the Flexprice dashboard. Store it as an environment variable:

$ export FLEXPRICE_API_KEY="fp_live_..."
2

Send your first event

An event is a record of one unit of usage by one customer. Send events whenever something billable happens in your application.

import Flexprice from '@flexprice/sdk';

const client = new Flexprice({
  apiKey: process.env.FLEXPRICE_API_KEY,
});

await client.events.ingest({
  event_name: 'api.call',
  customer_id: 'cust_abc123',
  idempotency_key: 'evt_' + Date.now(),
  properties: { tokens: 1024, model: 'gpt-4o' },
});
import flexprice
import os, uuid

client = flexprice.Client(api_key=os.environ["FLEXPRICE_API_KEY"])

client.events.ingest(
  event_name="api.call",
  customer_id="cust_abc123",
  idempotency_key=str(uuid.uuid4()),
  properties={"tokens": 1024, "model": "gpt-4o"},
)
package main

import (
  "github.com/flexprice/flexprice-go"
)

client := flexprice.New(os.Getenv("FLEXPRICE_API_KEY"))
client.Events.Ingest(ctx, &flexprice.EventParams{
  EventName:      "api.call",
  CustomerID:     "cust_abc123",
  IdempotencyKey: uuid.New().String(),
  Properties:     map[string]any{"tokens": 1024},
})
$ curl -X POST https://api.flexprice.org/v1/events \
  -H "Authorization: Bearer $FLEXPRICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "api.call",
    "customer_id": "cust_abc123",
    "idempotency_key": "evt_001",
    "properties": {"tokens": 1024}
  }'

A successful response returns HTTP 201 with the event ID and ingestion latency in milliseconds. Check the Flexprice dashboard under Events > Live stream to confirm receipt.

Idempotency keys: Always set a unique idempotency_key per event. If your application retries a failed request, Flexprice deduplicates on this key so usage is never double-counted.

3

Create a pricing plan

A pricing plan defines how usage events map to charges. Create one in the dashboard (Billing > Pricing Plans > New Plan) or via the API:

$ curl -X POST https://api.flexprice.org/v1/pricing-plans \
  -H "Authorization: Bearer $FLEXPRICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Usage",
    "billing_period": "monthly",
    "currency": "USD",
    "charges": [{
      "event_name": "api.call",
      "pricing_model": "graduated",
      "tiers": [
        {"up_to": 100000, "unit_price": 0},
        {"up_to": 5000000, "unit_price": 0.000006},
        {"up_to": "infinity", "unit_price": 0.000004}
      ]
    }]
  }'

# Response
{
  "id": "plan_01HZX...",
  "name": "API Usage",
  "status": "active"
}

Assign the plan to a customer via POST /v1/subscriptions. At the end of the billing period, Flexprice automatically calculates the invoice from metered events and the pricing plan rules.

Next steps