Troubleshooting
Use this page when a workflow does not behave as expected.
Start by identifying the object that owns the issue: product, customer, subscription, bill run, invoice, payment, usage event, or integration.
Billing and bill runs
| Problem | Check first |
|---|---|
| Subscription is missing from bill run preview | Subscription status, start date, next billing date, current period, and bill run end condition. |
| Preview includes too many invoices | Whether you selected an as-of date or multiple billing cycles. |
| Invoice amount is wrong | Product price, quantity, locked subscription price, coupon, tax, and usage records. |
| Duplicate invoice risk | Existing invoice for the same subscription period. |
| Usage not included | Usage event timestamp, subscription item ID, and whether usage arrived before execution. |
Invoices
| Problem | Check first |
|---|---|
| Invoice tax looks wrong | Customer address, product tax category, customer tax exemption, and tax rate setup. |
| Invoice balance does not match payment history | Payments, refunds, credit memos, and invoice transaction history. |
| Customer cannot open invoice PDF | Invoice status, document endpoint, customer access, and browser/download restrictions. |
| Invoice should be corrected | Use credit memo or adjustment instead of deleting posted financial history. |
Payments
| Problem | Check first |
|---|---|
| Payment failed | Gateway decline reason, customer payment method, retry rules, and dunning status. |
| Payment succeeded in gateway but not in Floatless | Webhook delivery, event logs, payment reference, and invoice transaction history. |
| Auto-pay did not run | Customer auto-pay setting, saved payment method, invoice status, and gateway configuration. |
| Refund not reflected | Refund record, credit memo, payment reference, and invoice status. |
Public API
| Problem | Check first |
|---|---|
| API request returns 401 | Missing or invalid Authorization: Bearer API key. |
| API request returns 404 | Resource does not exist or belongs to another tenant. |
| Usage event duplicated | Missing or unstable Idempotency-Key. |
| Webhook handler receives duplicate event | Webhooks are at-least-once; dedupe by event ID. |
Escalation checklist
When escalating internally, capture:
- Workspace or organization.
- Customer ID or name.
- Subscription ID.
- Invoice ID and invoice number.
- Bill run preview settings.
- Payment reference or webhook event ID.
- Timestamp and environment.
- Expected result and actual result.