First canary on a quality issue or deploy regression.
At a glance
Share of revenue refunded in the period. Square exposes refunds as separate Refund objects via the Refunds API; this card sums refund amount and divides by total order revenue. The fastest canary on a product-quality, fulfilment, or pricing-error incident.
| What it counts | SUM(refund.amount_money) / SUM(order.total_money) across the window. Both numerator and denominator use the order’s display currency, no FX. |
| VAT / tax treatment | n/a, this is a ratio. The numerator (refund amount) and denominator (order total) both include any tax that was originally charged, so it cancels out. |
| Shipping | If the merchant refunded shipping (full refund), the shipping is in the numerator. If the merchant refunded only the item price (typical), shipping isn’t refunded. Either way the math is correct. |
| Discounts | n/a, both sides are post-discount. |
| Refunds | This card is refunds. The numerator is SUM(refund.amount_money) for refunds issued in the period (not refunds for orders placed in the period, an important distinction). |
| Cancelled / voided orders | CANCELED orders are excluded from the denominator, the same denominator basis as Total Revenue. |
| Currency | Single-location reliable, multi-location requires care. A US + Canadian Square merchant gets a refund-rate where the numerator and denominator both mix USD and CAD without FX. The ratio is approximately right per location but not chain-wide. |
| Channels / sources | POS, web, and Invoices all contribute. POS refunds are typically same-day register voids or next-day cash-backs; web refunds are typically RMA-driven 7-30 days after the order. The two patterns can mask each other. |
| Time window | 30D vsP (default 30D vs the prior 30D) |
| Alert trigger | >5%, threshold-based |
| Sentiment key | refund_rate |
| Roles | owner, operations, finance |
Calculation
Calculated automatically from your Square Online data. See the At a glance summary above for what the metric tracks and the worked example below for a typical reading.Worked example
A US food & beverage retailer on Square: two cafes, a Square Online site selling whole-bean coffee subscriptions, and Square Invoices for wholesale. The 30-day window covers 14 Mar 26 to 12 Apr 26.| Channel | Order revenue | Refunds issued | Refund Rate |
|---|---|---|---|
| Square POS, retail cafes | $115,000 | $1,400 | 1.2% (mostly same-day register voids) |
| Square Online, web | $42,000 | $2,940 | 7.0% (RMA-driven, mostly damaged-in-shipping) |
| Square Invoices, wholesale | $24,000 | $0 | 0% |
| Total (this card) | $181,000 | $4,340 | 2.4% |
- Web refund rate alone (7.0%) would breach the alert threshold. But the chain-wide rate (2.4%) sits well below
>5%because POS dominates revenue and POS refunds are negligible. This is the classic Square reporting pitfall: a problem in one channel gets diluted by good behaviour in another. Pin a per-channel panel for the web slice to surface the real signal. - The web 7.0% is concentrated in one product, the merchant rolled out a new whole-bean SKU on 18 Mar 26 with packaging that doesn’t survive UPS Ground. Of 2,100 traces to that SKU. Top Products by Revenue and Out-of-Stock Products won’t reveal this; a per-SKU refund report (Square Dashboard, Reports, Refunds by item) is the diagnostic.
- Refunds issued in the period vs refunds for orders in the period are different. A refund issued on 12 Apr 26 for an order placed on 5 Mar 26 (before the window started) shows up in the numerator anyway. This card answers “what’s leaking out of cash now?” not “what’s the eventual refund rate of orders placed this period?”.
- The 30-day prior Refund Rate was 1.8%. Refund Rate is up 33% vsP, which is the more important signal than the absolute number. A trend-up below threshold is still a trend; don’t wait for the alert to fire.
Sibling cards merchants should reference together
| Card | Why pair it with Refund Rate |
|---|---|
| Total Revenue | Refund Rate is the leakage layer underneath gross revenue. A 5% refund rate means 20 of headline revenue isn’t kept. |
| Total Orders | A spike in refund rate with flat orders suggests a quality issue; a spike with falling orders suggests a customer-trust crisis. |
| Top Products by Revenue | Most refund-rate spikes trace to one or two SKUs. Cross-reference top sellers against per-SKU refund counts. |
| Out-of-Stock Products | Refund spikes can correlate with inventory miscounts (oversells that shipped wrong items). |
| Conversion Rate | Once refunds become public (reviews, social), CR usually follows downward. Refund rate is the leading indicator for trust-driven CR drops. |
shopify.refund_rate | Same metric on Shopify, useful for agencies. |
bigcommerce.refund_rate | Same metric on BigCommerce. |
Reconciling against the vendor’s own dashboard
Where to look in the Square Dashboard: Square Dashboard, Reports, Refunds. Set the same date range you’ve selected here, leave Location on All locations. The total Refunds dollar figure should match this card’s numerator to within a few cents. To compute the rate manually in Square Dashboard: Reports, Sales summary gives you Gross sales for the same window; divide Refunds by Gross sales. Other Square Dashboard views that look like the same number but aren’t:- Reports, Refunds by item: refunds aggregated per SKU, useful for diagnosis (which product caused the spike).
- Disputes & chargebacks: chargebacks are a separate concept, customer-initiated through their bank. Square exposes them on a different report. This card does not include chargebacks (yet).
- Sales summary, Net sales: Net sales subtracts refunds from gross. A side calculation, not a refund rate.
| Reason | Direction of divergence |
|---|---|
| Refund issuance vs order date. We compute refunds issued in the window, divided by orders placed in the window. Square’s report does the same by default but offers an “issued vs original order date” toggle, the toggle setting can shift the number. | Either |
| Time zone. Square uses location-local time, Vortex IQ uses UTC. Boundary days off. | Material at day boundaries |
| Multi-currency. Multi-location merchants in different currencies see Square report per location currency; this card sums without FX. | Wrong shape for cross-currency merchants |
| Partial refunds. Square supports partial refunds via the Refunds API; both this card and Square’s report sum partial-refund amounts the same way. | No divergence |
| Sync lag. Most recent ~5 minutes of refund events may not be in our index. | Self-resolves quickly |
| Card | Expected relationship | Why |
|---|---|---|
stripe.refund_rate | Stripe is typically zero or near-zero for Square merchants | Square processes its own payments; Stripe doesn’t see the refunds either. |
| Chargeback rate (separate concept) | Chargebacks are NOT refunds | A chargeback is a customer-bank-initiated dispute, not a merchant-issued refund. They live on a different Square API and are surfaced on a different card. |
square_online.sq_refund_rate = SUM(refund.amount_money) / SUM(order.total_money), where the order denominator is the same total_money used in Total Revenue.
Known limitations / merchant FAQs
My refund rate is 7% but the alert didn’t fire. Why? The alert is set to>5% chain-wide. If POS volume dilutes a high web-only refund rate, the chain-wide number sits below threshold even though the web slice is in trouble. Always pin a per-channel refund-rate panel (filter by source.name = SQUARE_ONLINE_STORE) if web is a meaningful share of revenue. The chain-wide number alone is a leading-indicator only for retail-heavy operations.
Are chargebacks counted as refunds?
No. Chargebacks are bank-initiated disputes; refunds are merchant-issued. They live on different Square APIs and are tracked separately. A high chargeback rate is a more serious signal than a high refund rate (chargebacks come with fees and can affect Square’s risk scoring of the merchant). A separate Chargeback Rate card is on the connector roadmap.
Why does today’s refund rate look so volatile?
Today is incomplete data. Refunds tend to cluster (a customer service rep processes a backlog at the end of the day; a damaged-shipment batch arrives all at once on a delivery day). The within-day pattern is genuinely lumpy. Use 7-day or 30-day windows for stable comparisons.
Does this card include partial refunds?
Yes. Square’s Refunds API exposes refund.amount_money for both full and partial refunds; this card sums the dollar amount regardless. A 100 order contributes 100 stays in the denominator.
What about Square’s “exchanges”?
Square POS supports same-day exchanges (return one item, take another in the same transaction). These are typically structured as a void plus a new sale rather than a refund, so they don’t show up here. Exchanges via mail-back to a Square Online order do appear as a Refund event paired with a new order.
Why is my refund rate higher on Square Online than in my POS retail?
This is the universal e-commerce pattern: shipped goods arrive damaged, are wrong-sized, or don’t match expectations from photos. Returns are a built-in cost of running a web channel. Industry benchmarks: cafe / food retail POS sits at <2%, fashion web sits at 15-30% (size-driven returns), home goods web sits at 5-10%, food & beverage web (shelf-stable) sits at 3-8%.
What’s the action playbook when this card spikes?
Five-step diagnosis: (1) per-channel split, is it web, POS, or invoices? (2) per-product split (Square Dashboard, Reports, Refunds by item), one or two SKUs usually drive 70%+ of the spike, (3) per-reason categorisation (Square allows merchants to tag refunds with reasons; Square Dashboard exposes the breakdown), (4) timing, did the spike start the day after a deploy, a new SKU launch, or a marketing change? (5) Conversion Rate, if CR is also dropping, the refund issue is becoming public (reviews, social) and is feeding back into acquisition.
Are subscription cancellations the same as refunds?
No. Cancelling a Square subscription stops future billing but doesn’t refund prior charges. Subscription refunds require a manual refund of the past invoice and do show here. Pure cancellations (stop renewing) don’t.