Florentin

API Reference

The Florentin API is organized around REST. All requests and responses use JSON. Authentication is via API key in the Authorization header.

Base URL

Bash — Production
https://api.florentin.io/v1

Authentication

All API requests require a valid API key passed in the Authorization header:

Bash
Authorization: Bearer sk_live_...

Customers

Create and manage customer records for billing.

Create a Customer

POST /v1/customers

customer = client.customers.create( email="user@example.com",
name="Acme Inc.", metadata={"plan": "pro"} ) print(f"Created: {customer.id}")
const customer = await client.customers.create({ email: "user@example.com", name:
"Acme Inc.", metadata: { plan: "pro" } }); console.log(`Created: ${customer.id}`);
customer, err := client.Customers.Create(ctx, &florentin.CustomerParams{ Email:
"user@example.com", Name: "Acme Inc.", Metadata: map[string]string{ "plan": "pro", }, })
fmt.Printf("Created: %s
", customer.ID)

List Customers

GET /v1/customers

customers = client.customers.list(limit=10) for customer in
customers: print(f"{customer.id}: {customer.name}")
const customers = await
client.customers.list({ limit: 10 }); for (const customer of customers.data) {
console.log(`${customer.id}: ${customer.name}`); }
customers, err :=
client.Customers.List(ctx, &florentin.ListParams{ Limit: 10, }) for _, customer := range
customers.Data { fmt.Printf("%s: %s
", customer.ID, customer.Name) }

Usage Tracking

Record and query usage data for metered billing.

Record Usage

POST /v1/usage

usage = client.usage.record( customer_id="cust_123",
product_id="prod_api", quantity=1500, unit="tokens" )
const usage = await
client.usage.record({ customerId: "cust_123", productId: "prod_api", quantity: 1500, unit: "tokens"
});
usage, err := client.Usage.Record(ctx, &florentin.UsageParams{ CustomerID:
"cust_123", ProductID: "prod_api", Quantity: 1500, Unit: "tokens", })

Query Usage

GET /v1/usage?customer_id=cust_123

summary = client.usage.summary( customer_id="cust_123",
start_date="2026-01-01", end_date="2026-01-31" ) print(f"Total: {summary.total_quantity}
{summary.unit}")
const summary = await client.usage.summary({ customerId:
"cust_123", startDate: "2026-01-01", endDate: "2026-01-31" }); console.log(`Total:
${summary.totalQuantity} ${summary.unit}`);
summary, err := client.Usage.Summary(ctx,
&florentin.UsageSummaryParams{ CustomerID: "cust_123", StartDate: "2026-01-01", EndDate:
"2026-01-31", }) fmt.Printf("Total: %d %s
", summary.TotalQuantity, summary.Unit)

Error Handling

The API uses standard HTTP status codes. Errors return a JSON body with error and message fields:

JSON — Error Response
{ "error": "invalid_request", "message": "customer_id is required" }