Why StoreKit's Payment Queue Can't Match a Purchase to Its Transaction
StoreKit has been the way iOS apps sell in-app purchases since iPhone OS 3.0 in July 2009. It gave developers a route to revenue beyond paid downloads, and it has remained central to app monetization. The framework's payment-queue design, however, has a long-standing gap: the call that starts a purchase does not return anything the app can use to identify the transaction that follows.
How the observer model works
StoreKit's purchase flow is built around a queue and an observer. The app asks for a payment to be added to the queue, and the observer is notified whenever a queued request changes state. In practice, developers implement a callback similar to the one in the supplied code module, iterating over updated transactions and switching on transactionState to handle .purchasing, .purchased, .restored, .failed, and .deferred.
The supplied code module is the reference for the exact callback signature and state branches. The important design point is that the observer receives transactions, not the original payment request.
The missing link between request and transaction
The problem sits between the step where the app makes a payment request and the step where the observer is called. A good purchase experience depends on the app reacting correctly to a purchase it initiated, but the API does not give the app a reliable handle for that reaction.
SKPayment is delivered to the payment queue through addPayment(), and the return type is void. Nothing comes back that the app can use to track the payment. By the time a transaction appears in the observer method, it no longer carries a connection to the SKPayment that generated it. That makes it impossible to associate a specific payment with the transaction it produces.
Why callback wrappers don't solve the problem
Developers often reach for convenience wrappers such as SwiftyStoreKit, which turns addPayment into a block-based addPaymentWithCallback. The wrapper looks like a clean fix, but it is not a real correlation mechanism.
What these wrappers actually do is pick a transaction by product: the callback fires on the first queued transaction whose productIdentifier matches the one you asked for. That is a product-level guess, not a link to your specific request. The guess goes wrong when the queue still holds failed transactions that were never finished. Those leftovers can surface the moment the user enters App Store credentials, so the wrapper may hand your callback a failure while the purchase you actually care about is still pending as a success. The user sees a muddled outcome at the worst possible moment, and the developer inherits review friction and support load.
What this means for purchase UI
There is no fully correct way to correlate a request with its transaction using this API. If the app disables its UI while a purchase is in flight, the practical workaround is to listen for any failed transaction and assume it came from the request, then re-enable the UI. That assumption is fragile: a successful transaction that follows a failed one produces a confusing sequence for the user.
A useful checklist for this situation:
- Treat the observer callback as the only source of transaction state, not as proof of which request produced it.
- When re-enabling UI after a failure, expect that a later success may still arrive.
- Avoid presenting a single definitive outcome until the queue has settled.
- Keep the productIdentifier match in mind as a wrapper convenience, not a request identity.
The proposed API fix
The suggested fix is straightforward: have addPayment return the SKPaymentTransaction, or something related to it. That would let block-based wrappers be written correctly and make in-app purchase UI much simpler to implement. Better API ergonomics would pass through to users as higher satisfaction and fewer support tickets for Apple.
Whether that change arrives is a separate question. The framework saw almost no changes over the eight years referenced in the original discussion, so the practical takeaway for developers is to design around the current observer model rather than wait for a different one.
Frequently asked questions
Why can't an app match an SKPayment to the transaction it creates?
Because addPayment() returns void. The app gets no handle back, and the transaction that later appears in the observer method has no retained link to the payment request that started it.
Does SwiftyStoreKit fix the correlation problem?
No. It provides a block-based wrapper, but it matches callbacks by productIdentifier on the first matching transaction. Unfinished failed transactions on the queue can trigger the callback before a successful transaction is handled.
What is the practical workaround when purchase UI is disabled?
Listen for any failed transaction and treat it as the result of the request, then re-enable the UI. This is an assumption rather than a guarantee, and a success arriving after a failure can still create a confusing sequence.
What change would make the API easier to use?
Returning the SKPaymentTransaction, or a related value, from addPayment would let wrappers correlate requests and transactions correctly and simplify purchase UI implementation.