StoreKit 2 refund detection comes down to one property on the transaction, and it's revocationDate

Most apps learn about an Apple refund from their server, through an App Store Server Notification, and never notice that the same refund is already sitting inside the app. It is on the transaction, in a property called revocationDate, and reading it lets your app cut a refunded customer's access the next time they open it, instead of waiting on a backend job. StoreKit 2 refund detection is a client-side signal most teams skip. Here is exactly where a refund surfaces on the device, what it tells you, what it does not, and why it belongs next to your server notifications rather than in place of them.

Where a refund shows up inside StoreKit 2

StoreKit 2 hands you transactions as signed values, and a refund does not delete the transaction. It marks it. Two properties on the Transaction carry the mark, and both stay nil for the entire life of a healthy purchase. When one of them turns non-nil, the App Store has taken the purchase back.

revocationDate is the field that flips

revocationDate is an optional Date. Apple's own description is exact: it is the date the App Store refunded the transaction or revoked it from Family Sharing. For a purchase that is still good, it is nil. The moment a refund is processed, it holds the timestamp of that refund. That single check, is revocationDate non-nil, is the whole of client-side refund detection. Everything else is nuance stacked on top of it.

revocationReason tells you why Apple pulled it

revocationReason sits next to the date and explains the cause. StoreKit gives it two values that matter for refunds. developerIssue means the customer told Apple the refund was due to an actual or perceived problem in your app. other covers every remaining reason. A third value, upgradedToBundle, is not a refund at all; it flags a transaction the App Store revoked because the customer moved to a subscription bundle. Read the reason before you act, because developerIssue is the one worth counting: a cluster of them is your own product telling you where it broke.

currentEntitlements already drops a refunded purchase

You do not always have to read the revocation fields yourself. Transaction.currentEntitlements is the sequence of purchases a customer is still entitled to right now, and Apple builds it to leave out the ones you should not honor. A product the App Store has refunded or revoked does not appear in it. Neither do expired subscriptions, or consumables, which are gone the moment they are finished.

That makes currentEntitlements the cleanest gate for access. Ask it what the customer owns, grant exactly that, and a refund removes the entitlement for you without a single revocationDate check. The revocation fields are for when you want the detail, the date and the reason, to log the event or to react to it. The entitlement list is for the plain question of whether to keep the lights on.

StoreKit 2 refund detection in practice, from launch and while the app runs

There are two moments your app can catch a refund on the device, and they need different code. One is while the app is open and a refund happens live or on another device. The other is at launch, catching up on everything that changed while you were closed. Miss the second and your StoreKit 2 refund detection has a hole exactly where most refunds fall, because customers rarely have your app open when they ask for one.

Start listening at launch or you miss the refunds that happened while closed

Transaction.updates is the async sequence that emits a transaction whenever the system creates or updates one outside your app or on another device, a refund included. Apple's instruction is blunt: start a Task that iterates it as soon as your app launches, or you may miss the transactions it delivers only once at startup. A refund that landed overnight arrives through updates the next time the app opens, but only if a listener is already running to receive it. No listener, no event, and the refund stays invisible until something else reconciles it.

A purchase on the same device does not come through updates

One trap catches people who test refunds by hand. A normal purchase made on the same device does not arrive through updates; StoreKit returns it straight from the purchase call's result. updates is for the out-of-band changes: refunds, Ask to Buy approvals, offer-code redemptions, and purchases made elsewhere. So build your refund handling around updates and currentEntitlements, not around the purchase flow, because the refund will never walk back through the path the sale took.

What client-side detection cannot do for you

Reading refunds on the device is fast and it is free, but it has a ceiling, and pretending it does not is how revenue leaks. The device only knows what StoreKit has told it, and StoreKit only speaks while your app is running. A customer who gets a refund and never opens your app again is a customer your client-side check never sees.

A revocationDate is not always a refund

The same field flips for Family Sharing. When a customer loses access to a shared purchase, because the organizer removed them or the sharing ended, that transaction gets a revocationDate too. So a non-nil date means the customer no longer has this purchase, which is exactly what you need for access control, but it does not always mean money came back out. If you are counting refunds for revenue, separate the Family Sharing revocations from the real ones before you trust the number.

A refund can be reversed

A refund is not always final. Apple can reverse one, and when it does, the revocation fields are removed from the transaction and the purchase is valid again. If you cut access on the refund, you are expected to restore it on the reversal. On the device that shows up as another updates event with a clean transaction; on your server it is a distinct REFUND_REVERSED notification. Handle only the refund and you will strand a paying customer with no access and a working receipt.

What a late revoke actually costs

A refund is rarely just the sale price leaving your account. By the time it clears you have usually already spent real money serving that purchase, and that spend does not come back. The generated images cost GPU minutes. The chat answers cost model API calls you were billed for per token. The uploads cost storage you are still paying to hold. If the purchase funded a payout to a creator, that money is already out the door. None of it reverses with the refund.

Client-side detection shrinks the window on the one part you can still control, which is future spend. The sooner you know a purchase is refunded, the sooner you stop serving it. But the device only tells you while the app is open, so a refunded user who never comes back keeps whatever server-side access you granted, quietly costing you every time a background job or a synced device acts on their behalf. The client makes the revoke fast. It does not make it guaranteed.

Use the client for speed and the server for truth

The clean design uses both signals for what each is good at. On the device, Transaction.updates and currentEntitlements give you an instant, local reaction the moment a refunded customer opens the app, good for the UI and for finishing entitlement changes without a round trip. On the server, App Store Server Notifications V2 send a REFUND message that arrives whether or not the app is ever opened again, which is the only signal that reliably stops your backend from spending on a refunded account.

Wire the device signals for the customer who is holding the phone, and the server notification for the one who is not. The refund shows up in both places on purpose. Reading only one of them is how a refunded account keeps costing you after the sale is already gone.