Everything that you need to know about Apple Purchase Receipts

The other day, I was trying to figure out the cause behind some unexpected responses that I’d received from customers on a survey that I’d conducted. One aha moment led to another and I soon found myself digging through Apple’s purchase receipt documentation. To my surprise, I discovered that Apple shares many bits of information in subscription receipts — the JSON has about 20 fields, and combining fields together gives you as a product owner all sorts of information about a customer’s subscription status, based off of which one can build lifecycle emails and revival tactics.

If you’re interested, the detailed documentation of all the fields can be found here. Note that the receipt can be queried at any time for a user, so this gives us the most up-to-date information about any subscription. Here are some details that can be deciphered from one or a combination of these fields:

I. Subscription renewal status — “auto_renew_status”
This flag tells us if the subscription will automatically renew at the end of the billing cycle, or if the user has turned off automatic renewal. It can be used to display alternate plan options to the user that might be more suitable for them (e.g. a cheaper monthly option), or even show warning messages proactively before expiry that the user will lose access to the subscriion’s features lest they renew.

II. Subscription Expiration Intent — “expiration_intent”
For all subscriptions that have expired, this field gives the reason for expiration. Specifically, it tells us if the user has actively cancelled their subscription, or if there was a billing error, or if the customer refused a recent price increase, or if the product itself was unavailable, or something unknown. This flag is really useful as it can be used to send appropriate revival messages to the user encouraging them to resubscribe. For example, if we know that the customer refused a recent price increase, we can offer them an alternate plan at a lower cost.

III. Subscription Retry Flag — “is_in_billing_retry_period
This is another handy flag that goes in tandem with subscriptions that have expired due to a billing error. If Apple is unable to charge a user for subscription renewal, it retries the charge for up to 60 days. This flag indicates if the expired subscription charge is still being retried by Apple. So, for any subscription, if the expiration intent is a billing error and if it’s still in the retry period, we can trigger emails or send in-app messages to the user, urging them to update their payment information.

IV. Subscription Auto Renew Preference — “auto_renew_product_id
According to the documentation, “the value for this key corresponds to the productIdentifier property of the product that the customer’s subscription renews.” Simply put, looking at this product ID will tell if you if the subscription is going to renew for the same plan that the user had purchased, or if they have switched to a different plan. For example, this can be helpful in cases where you introduce a monthly tier, and you want to keep an eye on the number of people who switch from annual to monthly billing cycle.

V. Subscription Price Consent Status — “price_consent_status
This flag indicates if the user has accepted a recent price change for their next renewal. As a refresher — when you increase the price of an auto-renewing subscription, you get the option to ‘preserve price’ for existing users so that they continue to renew at the lower price, while new users are served the new price of the subscription. However, if you choose not to preserve the price for existing users, Apple turns off automatic renewal and asks users if they accept the price change. If they give consent, users renew at the new price, otherwise, their subscription expires at the end of the billing cycle (with “expiration_intent” set to 3). I was surprised to find that Apple provides this information, as it can be really helpful when you’re running price experiments. You can use this flag to measure how users are reacting to the price change, and tweak the pricing accordingly.

VI. Cancellation Date — “cancellation_date
Not to be confused with subscription renewal cancellation, this field carries the most unexpected bit of information. If this key is set, it tells you the time and date the original purchase itself was cancelled and refunded by Apple support. You might remember, if a user wishes to cancel a subscription and get a refund, in true Apple fashion it’s not that easy. They have to reach out to Apple support and request a refund by stating a reason, and it’s completely up to Apple’s discretion to issue it. However, if Apple does issue it, this is the flag that tells you that.

VII. Cancellation Reason — “cancellation_reason
If a purchase has been cancelled by a user by reaching out to Apple support, i.e. cancellation_date is set, you look into this flag next to learn why did the user request a refund. It’s not very detailed but it can at least tell you if the user stated that they had an issue with your product, or if they claimed it to be an accidental purchase. In any case, if you do notice a lot of refunds all of a sudden, this flag can help you determine if users are not happy with the product.

These are some additional details that I could think of. Please leave a comment if you can think of anything else that I may have missed!