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.
Related docs