What information comes with an Apple App Store Server API Transaction?

App Store Server API Transactions are returned in a JSON Web Signature (JWS) format and carry objects for the following items:

• JWSDecodedHeader
• JWSTransactionDecodedPayload
• JWSRenewalInformationDecodedPayload

This post will break these down and give you insight into how they can help businesses.

This object holds encryption information that is required to validate the Transaction and Renewal information. This has no use to a business other than guaranteeing that the information that the business receives is true.

A decoded payload containing the following transaction information:

The App Account Token is a unique identifier ties a customers to a transaction.

This identifier should be considered a customer id and should be the same across all of the purchases of a customer.

If an app doesn’t provide an App Account Token at the time of purchase, this property is empty.

We recommend that businesses include an App Account Token in the purchase of each In-App Purchase or Subscription with the purpose of identifying their most loyal customers and knowing how valuable each customer is.

The bundleId property informs a business of the bundle identifier of the app where the transaction was made.

The environment property informs a business of whether the transaction occurred in a testing environment or on an app released on the Apple App Store.

This is valuable to help businesses separate test data from true data.

The expires date property is only available for Auto-Renewable Subscription transactions and is a UNIX millisecond string that lets businesses know when a subscription expires or renews.

To be able to understand if the subscription is expiring or renewing, businesses must setup App Store Server Notifications or must make an App Store Server API request for the transaction and use the autoRenewStatus property from JWSRenewalInfoDecodedPayload described later on.

The in app ownership type is only available for Non-Consumable In-App Purchases and Auto-Renewable Subscriptions and describes whether the transaction was purchased by the customer, or is available to them through Family Sharing.

For more information about what Apple Family Sharing is please consult our guide using the link below.

The isUpgraded property is only available for Auto-Renewable Subscription transactions and informs businesses if the transaction pertains to an Auto-Renewable Subscription in which a customer has upgraded to a higher level of service, or downgraded to a lower level of service within the same subscription group.

This is useful for businesses as it lets businesses measure how well subscriptions are performing and the value that customers feel that they get from different levels of service.

The offer identifier property is only available for Auto-Renewable Subscription transactions and contains the promo code or the promotional offer identifier.

It is useful as it lets businesses know how many customers used promotional offers or custom offer codes.

If the value is empty, no offer was used in the transaction.

The offer type property is only available for transactions of Auto-Renewable Subscription and lets businesses know if the transaction involved an introductory offer, a promotional offer or a custom offer code.

If the value is empty, no offer was used in the transaction.

The original purchase date property lets businesses know when the In-App Purchase or Subscription was purchased.

The original transaction id property lets businesses know the transaction identifier of the original purchase of an In-App Purchase or Subscription.

The product Id property is the unique identifier associated with the In-App Purchase or Subscription.

The purchase date property informs businesses of when the App Store charged the customers account for a purchase, restored product, subscription, or subscription renewal after a lapse.

The quantity property is only available for transactions for consumables and lets businesses know how many Consumable In-App Purchases a customer bought.

The revocation date property informs businesses of the date that the Apple App Store refunded the transaction.

The revocation reason property informs businesses of why the Apple App Store refunded the transaction or revoked it from family sharing.

The signed date property is the date that the Apple App Store signed the JWS data for this transaction and may have no value to a business.

The subscription group identifier property is only available for transactions pertaining to Auto-Renewable Subscriptions and informs businesses of the subscription group that the transaction relates to.

The transaction id property is the unique identifier for the transaction.

The type property informs businesses if the transaction relates to a Consumable In-App Purchase, Non-Consumable In-App Purchase, Non-Renewing Subscription or Auto-Renewable Subscription.

The web order line item id is a property that is a unique ID that identifies subscription purchase events across devices, including subscription renewals.

A decoded payload that only exists for Auto-Renewable Subscriptions and which contains the following information:

The auto renew product id is the identifier of the product that renews at the next billing period.

The auto renew status property lets businesses know if a customers subscription is renewing or if it will expire as they have cancelled.

The expiration intent property informs businesses of why the subscription is expiring. It can be one of the following:

• The customer cancelled their subscription.
• A billing error (i.e. the customer’s payment information is no longer valid).
• The customer didn’t consent to an auto-renewable subscription price increase that requires customer consent. This caused the subscription to expire.
• The product wasn’t available for purchase at the time of renewal.
• The subscription expired for some other reason.

The grace period expires date property informs businesses that a subscriber has failed to make a payment and are now in a grace period that will expire on the date shown.

This property only exists in these conditions if a business has setup a grace period to reduce involuntary churn. If there is no grace period and the customer fails to pay, they will move into a billing retry period.

The is in billing retry period property lets businesses know if a customer has failed to pay for a subscription and, if a business has enabled a grace period, that the customer failed to pay within the grace period.

The offer identifier property is only available for Auto-Renewable Subscription transactions and contains the promo code or the promotional offer identifier.

It is useful as it lets businesses know how many customers used promotional offers or custom offer codes.

If the value is empty, no offer was used in the transaction.

The offer type property is only available for Auto-Renewable Subscription transactions and lets businesses know if the transaction used an introductory offer, a promotional offer or a custom offer code.

If the value is empty, no offer was used in the transaction.

The original transaction id property lets businesses know the transaction identifier of the original purchase of an In-App Purchase or Subscription.

The price increase status property lets businesses know whether the Auto-Renewable Subscription associated with the transaction is subject to a price increase.

The product id property is the unique identifier of the product.

The recent subscription start date property is the earliest start date of an auto-renewable subscription in a series of subscription purchases that ignores all lapses of paid service that are 60 days or less.

The signed date property is the date that the Apple App Store signed the JWS data for this transaction and may have no value to a business.

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.