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

Oscar de la Hera Gomez
A flower that represents Apple with the text "App Store Server API Transaction Information" beneath it.

A guide that describes the e-commerce transaction information that is returned by an App Store Server API request.

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.

JWSDecodedHeader

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.

JWSTransactionDecodedPayload

A decoded payload containing the following transaction information:

appAccountToken

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.

bundleId

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

environment

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.

expiresDate

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.

inAppOwnershipType

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.

isUpgraded

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.

offerIdentifier

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.

offerType

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.

originalPurchaseDate

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

originalTransactionId

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

productId

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

purchaseDate

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.

quantity

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

revocationDate

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

revocationReason

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

signedDate

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.

subscriptionGroupIdentifier

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.

transactionId

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

type

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.

webOrderLineItemId

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

JWSRenewalInfoDecodedPayload

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

autoRenewProductId

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

autoRenewStatus

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

expirationIntent

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.

gracePeriodExpiresDate

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.

isInBillingRetryPeriod

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.

offerIdentifier

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.

offerType

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.

originalTransactionId

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

priceIncreaseStatus

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

productId

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

recentSubscriptionStartDate

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.

signedDate

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.

Looking for more information on building e-commerce Apple apps?

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.

Any Questions ?

We are actively looking for feedback on how to improve this resource. Please send us a note to inquiries@delasign.com with any thoughts or feedback you may have.
delasign logo

Book a Free Consultation.

An icon of an email.

Click here to email us.

Fill in the details below to book a free consultation or to let us know about something else. Whatever it is, we are here to help.

How can we help you ?

Contact Details