Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.fluveo.com/llms.txt

Use this file to discover all available pages before exploring further.

A Subscription represents a recurring billing arrangement between a merchant and a customer. Fluveo handles the billing cycle, invoice generation, payment collection, and dunning retries on your behalf.

​
MVP scope

  • Card recurring only, routed to Stripe. PIX and other push-to-pay methods don’t support recurring billing (the PSP layer rejects them with 422 unsupported_psp_capability at create time).
  • default_payment_method is required for charge_automatically subscriptions without a trial. Missing it returns 400 parameter_missing with param=default_payment_method.
  • Trials and send_invoice subscriptions can omit default_payment_method — they are charged (or invoiced) at trial end.

​
Create a subscription

POST /v1/subscriptions

{
  "customer": "cus_123",
  "currency": "usd",
  "default_payment_method": "pm_card_visa",
  "items": [
    { "price": "price_monthly_29", "quantity": 1 }
  ]
}

{
  "id": "sub_abc",
  "object": "subscription",
  "status": "active",
  "customer": "cus_123",
  "currency": "usd",
  "collection_method": "charge_automatically",
  "default_payment_method": "pm_card_visa",
  "latest_invoice": "in_xyz",
  "current_period_start": 1730419200,
  "current_period_end": 1733097600,
  "livemode": false,
  "merchant_id": "mer_acme"
}

​
How it works

  1. Fluveo validates the request: items must be non-empty, prices must resolve, the default payment method must exist on the customer.
  2. The subscription and its items are written to the database atomically.
  3. A draft invoice is created for the first billing period.
  4. The invoice is finalized (gets an invoice number, moves to open).
  5. Payment is collected through the PSP using the default payment method.
  6. On success, the subscription transitions to active and latest_invoice is populated. On failure, the subscription stays incomplete (unless payment_behavior=error_if_incomplete, which returns 402).

​
Payment behavior matrix

payment_behaviorInitial pay fails → subscription status
default_incompleteincomplete (default; Temporal retries)
allow_incompleteincomplete (same as default)
error_if_incompleteRequest returns 402, nothing is written

​
Renewal

Fluveo’s Temporal billing workflow creates a fresh invoice at current_period_end, collects payment, and moves the period window forward. You see a invoice.created → invoice.finalized → invoice.paid chain in your events stream. Failures transition the subscription to past_due and start dunning retries on days 1, 3, 5, and 7.

​
Cancel

DELETE /v1/subscriptions/{id}

{ "cancel_at_period_end": true }
Immediate cancellation omits the body.

​
Events emitted

  • subscription.created
  • subscription.updated
  • subscription.deleted
  • subscription.resumed
  • invoice.created / invoice.finalized / invoice.paid / invoice.payment_failed