Read the refund reason code your server already gets, and it tells you whether to fix your app or fight the customer

When Apple or Google refunds one of your customers, the money is usually gone before you get a vote. What lands on your server afterward looks like a receipt, and most teams treat it like one. It is more than that. Every refund carries a refund reason code, and it is the single part of a refund you still get to read once the decision is made. Google Play tells you the refund was a chargeback, or a remorse request, or a purchase your own app never acknowledged. Apple tells you whether the refund blamed something inside your app. Read that code and a refund stops being a line in a report and becomes an instruction: fix this, fight this, or let this one go. Here is what every code means, how to triage them, and what each one costs.

What a refund reason code actually is

A refund reason code is the store's own label for why a purchase was reversed. You do not set it and you cannot argue with it. It arrives attached to the refund after the fact, and the two stores expose it in different shapes and with very different resolution.

Google Play stamps a reason and a source on every void

Google Play's Voided Purchases API returns one record per reversed purchase, and each record carries two integers that matter. The voidedReason says why the purchase was voided. The voidedSource says who set it in motion. Together they turn a bare refund into a sentence: this order was voided because of a chargeback, initiated by Google, or voided as remorse, initiated by the user. You read these by polling the API or by subscribing to the real-time developer notification that fires when a void lands. Either way, the two numbers are the payload worth keeping.

Apple gives you a narrower signal, but a sharp one

Apple does not hand you a nine-way reason. On a refunded transaction, Apple sets revocationReason to one of two values. A 1 means the App Store refunded the transaction because of an actual or perceived issue within your app. A 0 means it refunded for another reason, for example an accidental purchase. The field appears only on transactions that were refunded or revoked, alongside a revocationDate, inside the signed transaction info of the REFUND App Store Server Notification. Two values is not much, but the one that matters, a 1, is Apple telling you the refund was about your product, not the customer's second thoughts.

The nine reasons Google Play gives you

Google's voidedReason is the richer of the two, and every value is worth knowing on sight because each one points somewhere different. Here is the full set, straight from the VoidedPurchase resource, with what each code is actually telling you to do.

voidedSource tells you who pulled the trigger

Next to the reason sits voidedSource, and it answers a different question: who reversed this. A 0 means the user did it, through self-service or a bank. A 1 means the developer did it, which is you or your own tooling issuing a refund. A 2 means Google did it, on its own judgment, including the auto-refund for an unacknowledged purchase. When you see a spike of voids, source is the first cut. A wall of source 2 is Google acting on your account, and that is usually a signal pointing back at your integration rather than at your customers.

Sort every refund into fix, fight, or accept

The reason a code is useful is that it tells you which of three responses a refund deserves. Most teams treat all refunds the same and burn effort on the ones they can never win. The codes split cleanly.

Fix: the refunds your product caused

Some codes are bug reports wearing a refund's clothes. Defective (3) and not received (2) on Google, and a revocationReason of 1 on Apple, all say the same thing: the customer paid and your app did not deliver. Unacknowledged purchase (8) is the sharpest of these because the fault is entirely in your billing code. These are the cheapest refunds to eliminate, because you eliminate them by fixing something you own, not by persuading anyone. A rising count in this pile is a product defect with a dollar figure attached.

Fight: the refunds someone is working

Fraud (5), friendly fraud (6), and chargeback (7) are the disputes. Pure fraud (5) is not your customer and not revenue you were ever going to keep. Friendly fraud (6), where the buyer got exactly what they paid for and then disputed it, is the one dispute your evidence can still move, and chargeback (7) is where that evidence gets submitted. When one of these lands you revoke access if you have not already, and where a review window is open you answer it with what you know about the account.

Accept: the refunds that were never yours to stop

Remorse (1) and accidental purchase (4) are the customer's own change of heart. Apple's revocationReason of 0 sits here too. No feature failed and no fraud occurred. You can soften the accidental bucket with a clearer purchase confirmation, but you cannot argue a remorse refund away, and time spent trying is time taken from the fix pile where the money actually is.

The 30-day catch that makes reason codes easy to lose

There is a hard limit on Google's side that turns this from a reporting feature into a deadline. If you are not capturing the codes continuously, you are losing them.

The Voided Purchases API only looks back 30 days

Google is explicit that the API can only show voided purchases from the past 30 days. Older voids are not returned no matter what startTime you pass, and the startTime value itself cannot be set earlier than 30 days ago. Worse for a naive integration, the 30-day window is measured by when Google's systems see a purchase as voided, not by when the purchase was made or even by the voidedTimeMillis in the record. So a refund reason code you do not pull inside that window is gone, and a monthly export job with any gap will silently drop voids it was too slow to catch.

What the reason codes are worth in money

Two codes carry a specific price, and reading them is how you put a number on problems that otherwise hide inside an aggregate refund rate.

One code is a bill you wrote yourself

voidedReason 8, unacknowledged purchase, is the cleanest example of a refund you caused. Google Play requires your app to acknowledge a purchase within three days of granting entitlement, and if you do not, Google automatically refunds the order and revokes the item. Every void stamped 8 is a real sale, from a customer who wanted the product, handed back because a call to acknowledge the purchase never fired. The lost amount is the full sale price plus the compute, API calls, and storage you already spent delivering it. This is not a refund you negotiate. It is a bug you close, and the code is how you find it.

The chargeback code now carries a fee

voidedReason 7, chargeback, changed cost on August 3, 2026. For Google Play orders placed on or after that date, a lost chargeback costs the developer the purchase price less Play's service fee, plus the bank's chargeback fee, while Google covers only its own service fee. Because chargeback fees are flat and product prices are not, on a cheap in-app purchase the fee alone can exceed what the customer paid. Counting your code 7 voids is now counting a line item, not just a lost sale, which is exactly why the chargeback bucket deserves its own row in any refund report you build.

How Apple and Google line up

The two stores answer the same question at different resolutions, so a cross-store refund report has to normalize them rather than expect them to match.

The stores will never give you the same code for the same refund, and that is fine. What matters is that both hand you a machine-readable reason, and both reward a team that reads it. Apple's single bit tells you when a refund is your product's fault. Google's nine reasons and its source flag tell you which product bug, which dispute, and which self-inflicted billing gap you are looking at. Neither code stops a refund. Both tell you what to do so the next one does not happen.

RefundHalt captures the reason code on every refund the moment it arrives, on both stores, and holds it well inside Google's 30-day window so nothing slips away. It sorts each void into fix, fight, or accept, so a spike in code 3 defective reaches you as a product alert and a spike in code 8 unacknowledged reaches you as an integration bug, not as a vague dip in revenue. It answers Apple's CONSUMPTION_REQUEST inside 12 hours and Google Play's chargeback review inside 24, and it revokes access the moment a refund or chargeback lands. You cannot change the code a store stamps on a refund. You can make sure you read every one, and act on the ones that are actually yours to fix.