Undocumented fields for ProductSubscriptionIOS

[farynaio]

There are some undocumented fields on ProductSubscriptionIOS, that seams like may be used to simplify introductory offer workflow. These fields are: introductoryPriceAsAmountIOS, introductoryPriceIOS, introductoryPriceNumberOfPeriodsIOS, introductoryPricePaymentModeIOS, introductoryPriceSubscriptionPeriodIOS.

How they are populated, and can be used for introductory offer workflow on iOS?

[hyochan]

Thanks for asking about these fields! Let me explain what they are and how they relate to the introductory offer workflow.

What These Fields Represent

These fields in ProductSubscriptionIOS provide direct access to introductory pricing information:

• introductoryPriceAsAmountIOS - The introductory price as a decimal number
• introductoryPriceIOS - The formatted introductory price string
• introductoryPriceNumberOfPeriodsIOS - How many periods the intro price lasts
• introductoryPricePaymentModeIOS - Payment mode (free-trial, pay-as-you-go, pay-up-front)
• introductoryPriceSubscriptionPeriodIOS - The subscription period for the intro price

How They Are Populated

These fields are populated by the OpenIAP Apple library from StoreKit's Product.subscription.introductoryOffer when available. They're automatically filled when you call fetchProducts().

Relationship to subscriptionInfoIOS

These fields are legacy/convenience fields that provide the same information as:

product.subscriptionInfoIOS?.introductoryOffer

The subscriptionInfoIOS.introductoryOffer object is the recommended and more complete way to access introductory offer information, as it includes additional fields like displayPrice, id, type, etc.

Usage Example

Recommended approach (using subscriptionInfoIOS):

const subscription = subscriptions.find((s) => s.id === 'premium_monthly');

if (subscription?.subscriptionInfoIOS?.introductoryOffer) {
  const offer = subscription.subscriptionInfoIOS.introductoryOffer;
  
  switch (offer.paymentMode) {
    case 'free-trial':
      console.log(`${offer.periodCount} ${offer.period.unit.toLowerCase()}(s) free trial`);
      break;
    case 'pay-as-you-go':
      console.log(`${offer.displayPrice} for ${offer.periodCount} period(s)`);
      break;
    case 'pay-up-front':
      console.log(`${offer.displayPrice} upfront for ${offer.periodCount} period(s)`);
      break;
  }
}

Legacy approach (using the direct fields you mentioned):

const subscription = subscriptions.find((s) => s.id === 'premium_monthly');

if (subscription?.introductoryPriceIOS) {
  console.log('Intro price:', subscription.introductoryPriceIOS);
  console.log('Payment mode:', subscription.introductoryPricePaymentModeIOS);
  console.log('Number of periods:', subscription.introductoryPriceNumberOfPeriodsIOS);
}

Important Notes

1. No code needed for purchase: iOS automatically applies introductory offers when eligible users purchase. You don't need to pass these fields to requestPurchase().

2. Display purposes only: Use these fields to show introductory pricing to users before purchase.

3. Eligibility: StoreKit automatically determines if the user is eligible. If they've already used the intro offer, it won't appear.

4. Documentation: We'll add proper documentation for these fields. They're generated from the OpenIAP specification at https://openiap.dev/docs/types

For a complete guide on working with subscription offers, see: https://docs.expo-iap.dev/docs/guides/subscription-offers

Let me know if you have any other questions!

[hyochan]

These fields are automatically populated from StoreKit when you call fetchProducts(). However, we recommend using subscriptionInfoIOS.introductoryOffer instead, which provides more complete information.

Recommended approach:

const offer = subscription?.subscriptionInfoIOS?.introductoryOffer;
if (offer) {
  console.log(offer.displayPrice, offer.paymentMode, offer.periodCount);
}

Using the direct fields:

if (subscription?.introductoryPriceIOS) {
  console.log(subscription.introductoryPriceIOS);
  console.log(subscription.introductoryPricePaymentModeIOS);
}

Note: iOS automatically applies introductory offers for eligible users - no extra code needed for purchase. These fields are for display purposes only.

See: https://hyochan.github.io/expo-iap/guides/subscription-offers#introductory-offers