"Discounts (Android)" should move to "Android Types"

[dfabulich]

https://www.openiap.dev/docs/features/discount is a separate page from https://www.openiap.dev/docs/types/android but I see no clear reason why. It's a bunch of Android-specific types; those should all be grouped together.

[gitdogbot[bot]]

This is a valid documentation organization issue.

Problem: Discount types are Android-specific but split across two documentation pages:

• Currently at: /docs/features/discount (separate feature page)
• Should be at: /docs/types/android (with other Android types)

Why this matters:

• Consolidates all Android-specific types in one location
• Improves discoverability for developers looking for Android implementation details
• Reduces cognitive load by grouping related platform-specific types together

Action needed:

1. Move discount type definitions/documentation from the features/discount page to types/android
2. Update any internal links/references pointing to the old discount page location
3. Consider adding a redirect from the old URL to the new location for backward compatibility
4. Update navigation/sidebar to reflect the new structure

This is a straightforward documentation refactoring that improves information architecture.

---

🤖 Generated by gitdog.dev · Have more questions? Tag @gitdog and let me know!

[hyochan]

@GitDog I don't agree please check #62 (comment)

[gitdogbot[bot]]

Thanks for pointing to that discussion! I understand you're referencing the detailed context in that comment thread. To properly evaluate your position against the previous response, I'd need to review the specific arguments made in that discussion comment.

The previous response argued for keeping discounts separate because:

1. The discount page is a comprehensive implementation guide (~1000 lines) with UI examples, setup instructions, and best practices—not just type definitions
2. Discounts (one-time purchases) differ from subscription pricing phases (the focus of Android Types)
3. Discoverability: developers looking for "how to implement discounts" expect to find it under Features, not Types

If the discussion comment #62 addresses any of these points with new information or a different organizational principle, that would be valuable context. Could you briefly summarize the key argument from that comment? That way I can engage with your position more substantively and help determine if the documentation structure should indeed be reorganized.

---

🤖 Generated by gitdog.dev · Have more questions? Tag @gitdog and let me know!

[hyochan]

@GitDog Looking at the actual GraphQL schema, the discount types (DiscountOffer, SubscriptionOffer) are cross-platform standardized types defined in type.graphql, not Android-specific.

Evidence from the schema:

1. SubscriptionOffer includes both iOS and Android fields:

   • iOS: keyIdentifierIOS, nonceIOS, signatureIOS, timestampIOS, numberOfPeriodsIOS, localizedPriceIOS
   • Android: basePlanIdAndroid, offerTokenAndroid, offerTagsAndroid, pricingPhasesAndroid

2. Both types are defined in type.graphql (common cross-platform types), not type-android.graphql

3. Both platforms support subscription offers:

   • iOS: Introductory offers, promotional offers with server-side signatures
   • Android: Offer tokens with pricing phases

Current documentation structure is correct:

• /docs/features/discount → Implementation guide (how-to) for the cross-platform discount feature
• /docs/types/ios and /docs/types/android → Platform-specific type references

Moving everything to /docs/types/android would incorrectly imply discounts are Android-only, when SubscriptionOffer clearly serves both platforms with platform-specific field suffixes following the project naming convention.

[gitdogbot[bot]]

The follow-up analysis is correct. Based on the GraphQL schema evidence provided:

Key findings:

1. Cross-platform types: SubscriptionOffer and DiscountOffer are defined in type.graphql (not type-android.graphql), indicating they're platform-agnostic
2. Dual platform fields: The types include both iOS-specific fields (keyIdentifierIOS, signatureIOS, etc.) and Android-specific fields (basePlanIdAndroid, offerTokenAndroid), confirming cross-platform support
3. Different use cases: Discounts apply to both one-time purchases (Android) AND subscription offers (both platforms)

Why current structure is correct:

• /docs/features/discount → Implementation guide for the cross-platform discount feature (includes UI examples, best practices, setup for both platforms)
• /docs/types/android and /docs/types/ios → Platform-specific type references (not for feature documentation)

Conclusion: Moving discount documentation to /docs/types/android would be incorrect because:

• It would imply discounts are Android-only
• It conflates feature guides with type definitions
• It ignores iOS promotional offers which also use SubscriptionOffer

The original issue was based on incomplete information. The current documentation organization correctly reflects that discounts are a cross-platform feature with platform-specific implementation details.

---

🤖 Generated by gitdog.dev · Have more questions? Tag @gitdog and let me know!

[dfabulich]

I guess I'm curious what you think about #62 (reply in thread)

[hyochan]

@dfabulich Thanks for the suggestion! After reviewing both pages, I'd like to share why I think the current structure makes sense:

Different Content Types

The /docs/features/discount page is not just type definitions - it's a comprehensive feature implementation guide (~1000 lines) that includes:

UI implementation examples (React Native, Kotlin Compose, Godot)
Time-limited offer handling
Limited quantity offer handling
Google Play Console setup instructions
Best practices
In contrast, /docs/types/android focuses purely on type definitions for subscription pricing (SubscriptionOffer, PricingPhase, PricingPhasesAndroid).

Different Product Types

Discounts page: Covers one-time purchase offers (Google Play Billing Library 7.0+)
Android Types page: Covers subscription pricing phases
These are distinct concepts in Google Play Billing.

Discoverability

Developers looking for "how to implement discounts" would naturally look in Features, not Types. The current placement matches user expectations.

Alternative

If you'd like, I could add a cross-reference link from the Android Types page to the Discounts feature guide for better navigation. Let me know if that would be helpful!

[dfabulich]

I think I see your point, but ProductAndroidOneTimePurchaseOfferDetail isn't documented on https://www.openiap.dev/docs/types/android or on https://www.openiap.dev/docs/types/product and that seems like an oversight.

The reference documentation should document all of the types.

[hyochan]

@dfabulich You're right! I've added the ProductAndroidOneTimePurchaseOfferDetail type reference to /docs/types/android.

The type is now documented at /docs/types/android#one-time-purchase-offer-detail with all fields including:

• offerId, offerToken, offerTags
• formattedPrice, priceAmountMicros, priceCurrencyCode
• discountDisplayInfo, fullPriceMicros
• validTimeWindow → ValidTimeWindowAndroid
• limitedQuantityInfo → LimitedQuantityInfoAndroid

Commit: 49427b5