Billing

Subscriptions

Recurring billing on a price.

Status: contracted_test. In the machine-checked test-mode contract (openapi.subset.json) and the API Reference: create, retrieve, list. Served by the fluveo-billing sidecar (ADR 0019); promoted 2026-07-13. Update/cancel are not in the contract yet. The Stripe-Version header is optional; send an Idempotency-Key on POST writes. See API coverage.

A Subscription bills a customer on a recurring price, generating an invoice each cycle. It tracks the billing period, status (incomplete, active, past_due, canceled, …), and its items — each subscription item expands its price inline on reads. A new subscription starts incomplete and activates through its first hosted invoice payment.

Served operations: create, retrieve, and list. Create items are form-encoded with indexed brackets (items[0][price], items[0][quantity]) — the service reads those literally. Automatic recurring collection is not served yet (400 subscription_automatic_collection_unavailable); renewal is a later gate. Dashboard-created subscriptions use the same API and persist in merchant-scoped durable Billing storage.