How do Apple App Store Transactions work?

Every time a customer makes a purchase; a purchase is pending or fails; a subscription renews, upgrades, downgrades or expires; or a customer is refunded for an In-App Purchase or a Subscription on an app, a transaction will be created and will added to the customers purchase history.

These transactions let businesses know what In-App Purchases or Subscriptions a customer is entitled to as well as the history that a customer has with an app.

Each of these transactions includes a rich data set that allow businesses to send marketing material to customers depending on the transaction that took place.

To do this in real-time we recommend that businesses create a backend system that implement App Store Server Notifications.

In general, if a customer buys an In-App Purchase or Subscription, the App Store will generate a Purchased transaction.

If the customer asks for a refund, that same transaction will be updated to a Refunded transaction.

Each refunded transaction includes a revocation reason that lets businesses know why the customer requested a refund.

If the customer needs parental approval or bank approval to make a purchase, the transaction will be updated to be marked as Pending and will appear as failed on their purchase history.

As the pending transaction state for a purchase is only available to an app when it occurs (i.e. it does not persist) and cannot be traced in-app, in order to mark transactions as pending businesses must either:

• Create a backend system that implements Apple's App Store Server API (ASSA) or App Store Server Notifications (ASSNs). This backend must work with the app to let the app know what transactions are pending, whenever the app needs to know.
• Create a persistent algorithm in-app that tracks pending transactions.

In the event that a business do not use ASSA, ASSNs or a persistent algorithm to remove the ability for a customer to attempt the same purchase whilst a transaction is pending, a customer will be able to make repeated purchase attempts an unlimited number of times.

If the transaction is approved by the parent or bank, the customer will only receive one bill, as Apple will consolidate them into one.

Consumable In-App Purchases are limited to these scenarios.

However, Non-Consumable In-App Purchases, Non-Renewing Subscriptions and Auto-Renewable Subscriptions are more complicated.

Non-Consumable In-App Purchases and Auto-Renewable Subscriptions (i.e. the product) allow for Apple Family Sharing.

Customers (i.e Customer A) who have an Apple Family member who buys a product that includes Family Sharing will gain access to the product, as the Apple App Store will generate a transaction for the product and add it to Customer A's entitlements and purchase history. This should be used to grant Customer A access to the product.

In the event that the member of their Apple Family cancels the subscription or requests a refund, Customer A will lose their entitlement to the product and the transaction will be updated to include a revocation reason that points to a cancelled or refunded Family Sharing product.

Non-Renewing Subscriptions do not have an explicit expiration date and will require custom business logic to define how they work in-app.

In the event that a business wishes to use Non-Renewing Subscriptions (NRS) as "Seasons", the business will need to:

• Create an NRS on Apple's App Store Connect.
• Create logic in the app that enables features for a period of time based on being entitled to the NRS, after which the features are disabled.
• Make the NRS unavailable in the App Store when the business logic states that the NRS has expired.
• Repeat the process above every time the business wants to offer a new "Season."

In the case of Auto-Renewable Subscriptions, every time a customer buys a subscription they will generate a purchased transaction (i.e. Transaction A).

Then depending on their actions or intents, the following will occur:

• If they cancel the subscription, Transaction A will be updated to be marked as expiring and, at the end of the period, Transaction A will be updated to an expired transaction.
• If they renew, Transaction A will become expired and a new purchased transaction will be generated with a new expiration date. This cycle will continue indefinitely whilst they are subscribed, with a new purchased transaction being generated per period and the prior one becoming expired.
  • The Subscription Information Renewal State will let businesses know in-app if a customer has auto-renewal activated or deactivated.
  • The Subscription Information Status will let businesses know in-app if a customer's subscription is active, in a grace period, in billing retry, expired or revoked.

To get the information above outside of the app businesses will need to implement a backend system that uses the App Store Server API or App Store Server Notifications.

Although a transaction will be updated if a subscription expires, an app will not be notified through the StoreKit listener.

This means that apps need to refresh the StoreKit algorithm manually to remove the entitlement from the customer after an expiration.

In order to solve for this, we recommend that businesses:

• Refresh the customers entitlements every time an app is used (i.e. when the customer comes back to the app after using another app or when the app is opened).
• Implement a backend system that uses Apple's App Store Server Notifications to inform the app of the expired subscription in real-time.

If the customer upgrades or downgrades their level of service (i.e. upgrades to a higher subscription tier or downgrades to a lower tier within the same subscription group), the system will generate a new purchased transaction for the new subscription (Transaction B) and will maintain the old purchased transaction until it expires (Transaction A).

This means that the customer will have access to both subscriptions (Transaction A and B) until Transaction A expires. As a result, businesses will need to implement custom logic in their app to identify the highest level of service that a customer has access to.

Please note that this logic must also consider Family Sharing which is included with the transaction information pertaining to an Auto-Renewable Subscription.

If an Auto-Renewable Subscription transaction included an offer, information about the offer that was used will be available in the transaction data.

Read our business guide to get our latest market and customer research, perspective and recommendations on building Apple e-commerce apps that use In-App Purchases and Subscriptions.

Read our comprehensive development guide linked below to learn about all the secrets behind developing In-App Purchases and Subscriptions with StoreKit 2.