Knowledge Center

Run billing with Floatless.

Product guides, billing concepts, operational playbooks, developer references, and security notes for teams running subscription revenue.

Integration Guide

Use this guide before wiring Floatless into a CRM, product backend, customer portal, data warehouse, or finance system.

Common integration patterns

Pattern Typical APIs
Sync customer records from CRM Customers API
Display products or prices in another system Products API
Show subscription state in your app Subscriptions API
Display invoices in a customer portal Invoices API, invoice HTML, invoice PDF
Report metered usage from your product Usage events API
Trigger downstream workflows Webhooks

Authentication

Public API requests use API keys:

Authorization: Bearer sk_live_...

Create API keys in the Floatless console and store them in a secrets manager. Do not embed live keys in frontend code, mobile apps, logs, or source control.

Idempotency

Use idempotency keys whenever retrying write requests from an external system. Usage events require an Idempotency-Key header so network retries do not double-count usage.

curl https://api.floatless.com/api/public/v1/usage/events \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: usage_2026_07_07_customer_123" \
  -H "Content-Type: application/json" \
  -d '{"subscription_item_id": 456, "quantity": 25}'

Webhooks

Use webhooks when your system needs to react to billing lifecycle changes.

Webhook handlers should:

  • Verify the endpoint secret when signature verification is available.
  • Store processed event IDs.
  • Treat delivery as at-least-once.
  • Return a 2xx response only after processing or durable enqueue.
  • Retry safely when downstream systems are unavailable.

Invoice documents

Customer portals and finance systems often need invoice documents rather than invoice JSON.

Use:

  • GET /invoices/{invoice_id}/html for browser rendering.
  • GET /invoices/{invoice_id}/pdf for downloadable documents.
  • GET /invoices/{invoice_id}/transactions to explain invoice balance.

Production checklist

  • Use separate keys for development, staging, and production systems.
  • Keep request logs free of API keys and webhook secrets.
  • Back off and retry on transient network failures.
  • Treat 404 from tenant-scoped endpoints as either not found or not accessible.
  • Subscribe only to webhook events your system actually handles.
  • Update website documentation whenever a public endpoint, field, event, or behavior changes.

Related docs

PreviousWebhooksNextCompliance & Security