Refunds & Notifications ยท Article 6.7
Refresh status โ pull-based sync when the Stripe webhook didn't land
Webhooks aren't perfect. When a credit note appears stuck in `requested` despite Stripe having processed the refund, click `Refresh status` to pull the current state from Stripe directly. Same transition logic as the webhook; no risk of double-firing side-effects.
Refresh status is the "kick the tyres" button. When everything is working, the webhook delivers Stripe's verdict in seconds and you don't need this button. When the webhook is delayed or lost (network hiccup on your endpoint, Stripe's webhook queue backlogged, your endpoint returned a 5xx response that exhausted Stripe's 3-day retry window), Refresh lets you bypass the push channel and pull the answer directly. The result is the same as if the webhook had landed cleanly.
Step by step
Notice a stuck
requestedstatus.Banner reads "Refund in progress, expected in 3โ5 business days" and stays static for >24 hours.
Click
Refresh status.From the Refund banner or the Credit Notes page row.
Wait ~2 seconds.
Server calls Stripe API on the connected account; resolves the canonical state.
UI updates in place.
If Stripe says succeeded โ banner flips to "Refund completed on [date]"; "refund completed" email fires; proposal closes if applicable. If failed โ banner offers Retry / Mark refunded options. If still pending on Stripe's side โ banner copy refreshes to reflect Stripe's reported state.
No further action needed if state moved.
All downstream hooks fire automatically.
Refund banner with Refresh status button. After clicking, a brief spinner, then either no change (Stripe still pending) or banner update to terminal state.
Why this works this way
Why a manual button rather than a daily cron sync? Cost and latency. A cron job that polls Stripe daily for every requested credit note adds steady API load to Stripe's rate limits AND introduces up to 24h latency before a UI update. The manual button puts the cost where it's actually needed (the freelancer is wondering why the banner is stuck) and gives near-instant resolution. We may add an automated sync down the line if support tickets show it'd be valuable, but the manual path covers ~95% of cases.
Troubleshooting
Keep reading
Refunds & Notifications
Stripe automatic refund (Direct Charges via Connect)
When the original deposit was paid via Stripe, the refund is automatic. Clozo issues a Refund on the freelancer's connected account, watches for the `refund.updated` webhook, and flips the credit note to `succeeded` once Stripe confirms โ typically within 3โ5 business days for the cash to reach the client.
Refunds & Notifications
Refund stages: issued โ requested โ succeeded (or manual)
The credit note moves through up to four states from creation to settled. Each state corresponds to a specific point in the refund lifecycle, with predictable UI badges and email triggers.
Refunds & Notifications
Failed refunds & recovery โ common Stripe failure reasons
A `failed` credit note has a `refund_failure_reason` string from Stripe. Most reasons fall into a small set; here's what each means and the recommended recovery.
Refunds & Notifications
The Credit Notes page
A first-class section in the freelancer dashboard that lists every credit note across all your proposals, with status, refund amount, linked proposal, and action buttons. Use this when you want to manage refunds without drilling into each proposal individually.