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.

This recipe covers the MVP subscription flow: save a card with a SetupIntent, attach it to a customer, and create a subscription that auto-pays each cycle.

​
Prerequisites

  • A Fluveo API key for a verified merchant (see Onboarding docs).
  • A Stripe-backed PSP connection on the merchant (defaults to the platform payfac in MVP, so no per-merchant Connect setup is required).

​
1. Create the customer

POST /v1/customers
Content-Type: application/json

{ "email": "alice@example.com", "name": "Alice" }
Stash id as cus_xxx.

​
2. Create and confirm a SetupIntent

POST /v1/setup_intents
Content-Type: application/json

{ "customer": "cus_xxx", "usage": "off_session" }
The response includes a client_secret. Pass it to your frontend; on confirmation the PM is attached to the customer. 
POST /v1/setup_intents/{si_id}/confirm
Content-Type: application/json

{ "payment_method": "pm_xxx" }
The response body returns payment_method=pm_xxx, now attached.

​
3. Create a recurring price

POST /v1/products { "name": "Pro Plan" }
POST /v1/prices {
  "product": "prod_xxx",
  "currency": "usd",
  "unit_amount": 2500,
  "recurring": { "interval": "month" }
}

​
4. Create the subscription

POST /v1/subscriptions
Content-Type: application/json

{
  "customer": "cus_xxx",
  "currency": "usd",
  "default_payment_method": "pm_xxx",
  "items": [{ "price": "price_xxx", "quantity": 1 }]
}
If the initial invoice pays successfully, the response includes "status": "active" and latest_invoice references the paid invoice. If the card declines, the subscription stays incomplete and Fluveo’s Temporal billing workflow retries at the configured dunning cadence (days 1, 3, 5, 7).

​
5. Handle renewals

You don’t have to do anything. Fluveo runs the billing workflow at current_period_end:
  1. Create a new invoice for the next period.
  2. Finalize → pay using default_payment_method.
  3. On success, move current_period_{start,end} forward.
  4. On failure, transition past_due and start dunning.
Your webhook subscription should listen for:
  • invoice.paid — renewal succeeded
  • invoice.payment_failed — dunning started
  • subscription.updated — status changed (past_due, unpaid)

​
Common errors

CodeStatusMeaning
parameter_missing400default_payment_method required for charge_automatically + no trial
unsupported_psp_capability422The resolved PSP can’t do recurring for (currency, paymentMethodTypes)
invalid_price422Price has unit_amount=null (metered pricing isn’t MVP)
payment_failed402payment_behavior=error_if_incomplete and the card declined