Use this page with AI

Copy this into your coding assistant and add your request.

Read https://openiap.dev/docs/types/subscription-offer and https://openiap.dev/llms.txt. Follow the reading instructions, detailed reference, and linked guides relevant to my task before making changes.
Inspect my existing project and reuse its framework and conventions. Ask me for missing product decisions. Implement the requested behavior and run the applicable checks.
Show the working result, the commands and actual test results, and any remaining limitations. Keep your explanation brief.

My request: [describe what customers should be able to do]

SubscriptionOffer

SubscriptionOffer#

Standardized type for subscription promotional offers. Supported on both iOS (introductory and promotional offers) and Android (offer tokens with pricing phases).

Cross-platform subscription-offer envelope. iOS: maps to Product.SubscriptionOffer (Apple docs). Android: maps to SubscriptionOfferDetails (Google docs).

Native references: Apple · Product.SubscriptionOffer · Google · ProductDetails.SubscriptionOfferDetails

Common Fields#

Field	Type	Description
`id`	`ID!`	Unique identifier for the offer
`displayPrice`	`String!`	Formatted display price (e.g., "$9.99/month")
`price`	`Float!`	Numeric price value
`currency`	`String`	Currency code (ISO 4217)
`type`	`DiscountOfferType!`	`introductory` or `promotional`
`period`	`SubscriptionPeriod`	Subscription period (unit + value)
`periodCount`	`Int`	Number of periods the offer applies
`paymentMode`	`PaymentMode`	FreeTrial, PayAsYouGo, or PayUpFront

iOS-Specific Fields#

Field	Type	Description
`keyIdentifierIOS`	`String`	Key ID for server-side signature validation
`nonceIOS`	`String`	Cryptographic nonce (UUID) for signature
`signatureIOS`	`String`	Server-generated signature for validation
`timestampIOS`	`Float`	Timestamp when signature was generated
`numberOfPeriodsIOS`	`Int`	Number of billing periods for this discount
`localizedPriceIOS`	`String`	Localized price string

Android-Specific Fields#

Field	Type	Description
`basePlanIdAndroid`	`String`	Base plan identifier
`offerTokenAndroid`	`String`	Required for purchase. Pass to requestPurchase()
`offerTagsAndroid`	`[String!]`	Tags associated with this offer
`pricingPhasesAndroid`	`PricingPhasesAndroid`	Pricing phases (trial, intro, regular)
`installmentPlanDetailsAndroid`	`InstallmentPlanDetailsAndroid`	Installment plan details for subscription commitments (7.0+)

Type Definition#

swift

struct SubscriptionOffer: Codable {
    // Common fields
    let id: String
    let displayPrice: String
    let price: Double
    let currency: String?
    let type: DiscountOfferType
    let period: SubscriptionPeriod?
    let periodCount: Int?
    let paymentMode: PaymentMode?

    // iOS-specific fields
    let keyIdentifierIOS: String?
    let nonceIOS: String?
    let signatureIOS: String?
    let timestampIOS: Double?
    let numberOfPeriodsIOS: Int?
    let localizedPriceIOS: String?

    // Android-specific fields
    let basePlanIdAndroid: String?
    let offerTokenAndroid: String?
    let offerTagsAndroid: [String]?
    let pricingPhasesAndroid: PricingPhasesAndroid?
    let installmentPlanDetailsAndroid: InstallmentPlanDetailsAndroid?
}

struct InstallmentPlanDetailsAndroid: Codable {
    let commitmentPaymentsCount: Int
    let subsequentCommitmentPaymentsCount: Int
}

struct SubscriptionPeriod: Codable {
    let unit: SubscriptionPeriodUnit
    let value: Int
}

enum SubscriptionPeriodUnit: String, Codable {
    case day = "day"
    case week = "week"
    case month = "month"
    case year = "year"
    case unknown = "unknown"
}

enum PaymentMode: String, Codable {
    case freeTrial = "free-trial"
    case payAsYouGo = "pay-as-you-go"
    case payUpFront = "pay-up-front"
    case unknown = "unknown"
}

Kotlin example

data class SubscriptionOffer(
    // Common fields
    val id: String,
    val displayPrice: String,
    val price: Double,
    val currency: String? = null,
    val type: DiscountOfferType,
    val period: SubscriptionPeriod? = null,
    val periodCount: Int? = null,
    val paymentMode: PaymentMode? = null,

    // iOS-specific fields
    val keyIdentifierIOS: String? = null,
    val nonceIOS: String? = null,
    val signatureIOS: String? = null,
    val timestampIOS: Double? = null,
    val numberOfPeriodsIOS: Int? = null,
    val localizedPriceIOS: String? = null,

    // Android-specific fields
    val basePlanIdAndroid: String? = null,
    val offerTokenAndroid: String? = null,
    val offerTagsAndroid: List<String>? = null,
    val pricingPhasesAndroid: PricingPhasesAndroid? = null,
    val installmentPlanDetailsAndroid: InstallmentPlanDetailsAndroid? = null
)

data class InstallmentPlanDetailsAndroid(
    val commitmentPaymentsCount: Int,
    val subsequentCommitmentPaymentsCount: Int
)

data class SubscriptionPeriod(
    val unit: SubscriptionPeriodUnit,
    val value: Int
)

enum class SubscriptionPeriodUnit(val rawValue: String) {
    Day("day"),
    Week("week"),
    Month("month"),
    Year("year"),
    Unknown("unknown")
}

enum class PaymentMode(val rawValue: String) {
    FreeTrial("free-trial"),
    PayAsYouGo("pay-as-you-go"),
    PayUpFront("pay-up-front"),
    Unknown("unknown")
}

TypeScript example

interface SubscriptionOffer {
  // Common fields
  id: string;
  displayPrice: string;
  price: number;
  currency?: string;
  type: DiscountOfferType;
  period?: SubscriptionPeriod;
  periodCount?: number;
  paymentMode?: PaymentMode;

  // iOS-specific fields
  keyIdentifierIOS?: string;
  nonceIOS?: string;
  signatureIOS?: string;
  timestampIOS?: number;
  numberOfPeriodsIOS?: number;
  localizedPriceIOS?: string;

  // Android-specific fields
  basePlanIdAndroid?: string;
  offerTokenAndroid?: string;
  offerTagsAndroid?: string[];
  pricingPhasesAndroid?: PricingPhasesAndroid;
  installmentPlanDetailsAndroid?: InstallmentPlanDetailsAndroid;
}

interface InstallmentPlanDetailsAndroid {
  commitmentPaymentsCount: number;
  subsequentCommitmentPaymentsCount: number;
}

interface SubscriptionPeriod {
  unit: SubscriptionPeriodUnit;
  value: number;
}

type SubscriptionPeriodUnit = 'day' | 'week' | 'month' | 'year' | 'unknown';

type PaymentMode =
  | 'free-trial'
  | 'pay-as-you-go'
  | 'pay-up-front'
  | 'unknown';

Dart example

dart

class SubscriptionOffer {
  // Common fields
  final String id;
  final String displayPrice;
  final double price;
  final String? currency;
  final DiscountOfferType type;
  final SubscriptionPeriod? period;
  final int? periodCount;
  final PaymentMode? paymentMode;

  // iOS-specific fields
  final String? keyIdentifierIOS;
  final String? nonceIOS;
  final String? signatureIOS;
  final double? timestampIOS;
  final int? numberOfPeriodsIOS;
  final String? localizedPriceIOS;

  // Android-specific fields
  final String? basePlanIdAndroid;
  final String? offerTokenAndroid;
  final List<String>? offerTagsAndroid;
  final PricingPhasesAndroid? pricingPhasesAndroid;
  final InstallmentPlanDetailsAndroid? installmentPlanDetailsAndroid;

  SubscriptionOffer({
    required this.id,
    required this.displayPrice,
    required this.price,
    this.currency,
    required this.type,
    this.period,
    this.periodCount,
    this.paymentMode,
    this.keyIdentifierIOS,
    this.nonceIOS,
    this.signatureIOS,
    this.timestampIOS,
    this.numberOfPeriodsIOS,
    this.localizedPriceIOS,
    this.basePlanIdAndroid,
    this.offerTokenAndroid,
    this.offerTagsAndroid,
    this.pricingPhasesAndroid,
    this.installmentPlanDetailsAndroid,
  });
}

class InstallmentPlanDetailsAndroid {
  final int commitmentPaymentsCount;
  final int subsequentCommitmentPaymentsCount;

  InstallmentPlanDetailsAndroid({
    required this.commitmentPaymentsCount,
    required this.subsequentCommitmentPaymentsCount,
  });
}

class SubscriptionPeriod {
  final SubscriptionPeriodUnit unit;
  final int value;

  SubscriptionPeriod({required this.unit, required this.value});
}

enum SubscriptionPeriodUnit {
  Day('day'),
  Week('week'),
  Month('month'),
  Year('year'),
  Unknown('unknown');

  const SubscriptionPeriodUnit(this.value);
  final String value;
}

enum PaymentMode {
  FreeTrial('free-trial'),
  PayAsYouGo('pay-as-you-go'),
  PayUpFront('pay-up-front'),
  Unknown('unknown');

  const PaymentMode(this.value);
  final String value;
}

C# (MAUI) example

using OpenIap;
using OpenIap.Maui;
using System.Collections.Generic;

public sealed record SubscriptionOffer
{
    // Common fields
    public required string Id { get; init; }
    public required string DisplayPrice { get; init; }
    public required double Price { get; init; }
    public string? Currency { get; init; }
    public required DiscountOfferType Type { get; init; }
    public SubscriptionPeriod? Period { get; init; }
    public int? PeriodCount { get; init; }
    public PaymentMode? PaymentMode { get; init; }

    // iOS-specific fields
    public string? KeyIdentifierIOS { get; init; }
    public string? NonceIOS { get; init; }
    public string? SignatureIOS { get; init; }
    public double? TimestampIOS { get; init; }
    public int? NumberOfPeriodsIOS { get; init; }
    public string? LocalizedPriceIOS { get; init; }

    // Android-specific fields
    public string? BasePlanIdAndroid { get; init; }
    public string? OfferTokenAndroid { get; init; }
    public IReadOnlyList<string>? OfferTagsAndroid { get; init; }
    public PricingPhasesAndroid? PricingPhasesAndroid { get; init; }
    public InstallmentPlanDetailsAndroid? InstallmentPlanDetailsAndroid { get; init; }
}

public sealed record InstallmentPlanDetailsAndroid
{
    public required int CommitmentPaymentsCount { get; init; }
    public required int SubsequentCommitmentPaymentsCount { get; init; }
}

public sealed record SubscriptionPeriod
{
    public required SubscriptionPeriodUnit Unit { get; init; }
    public required int Value { get; init; }
}

public enum SubscriptionPeriodUnit
{
    Day, Week, Month, Year, Unknown
}

public enum PaymentMode
{
    FreeTrial, PayAsYouGo, PayUpFront, Unknown
}

GDScript example

class_name SubscriptionOffer

# Common fields
var id: String
var display_price: String
var price: float
var currency: String
var type: DiscountOfferType
var period: SubscriptionPeriod
var period_count: int
var payment_mode: PaymentMode

# iOS-specific fields
var key_identifier_ios: String
var nonce_ios: String
var signature_ios: String
var timestamp_ios: float
var number_of_periods_ios: int
var localized_price_ios: String

# Android-specific fields
var base_plan_id_android: String
var offer_token_android: String
var offer_tags_android: Array[String]
var pricing_phases_android: PricingPhasesAndroid
var installment_plan_details_android: InstallmentPlanDetailsAndroid

class InstallmentPlanDetailsAndroid:
    var commitment_payments_count: int
    var subsequent_commitment_payments_count: int

class SubscriptionPeriod:
    var unit: SubscriptionPeriodUnit
    var value: int

enum SubscriptionPeriodUnit { DAY, WEEK, MONTH, YEAR, UNKNOWN }
enum PaymentMode { FREE_TRIAL, PAY_AS_YOU_GO, PAY_UP_FRONT, UNKNOWN }