Skip to main content
Pricing, subscriptions, and availability Level: Intermediate 12 min read

Configuring Free Trials and Introductory Offers on iOS Subscriptions

How to configure free trials, pay-as-you-go, and pay-up-front introductory offers on auto-renewable subscriptions in App Store Connect, stage API changes via FlightDeck, and verify StoreKit 2 eligibility.

Published: 2026-11-03 • Last Updated: 2026-11-03 • Author: Kip Lawrence
Key MCP Tools: subscription_group_localizations_listflightdeck_api_catalogflightdeck_operation_stagerelease_readiness_check

Overview: The Role of Introductory Pricing in Subscription Growth

For iOS and macOS subscription businesses, offering an introductory discount or free trial is the single most effective lever for reducing customer acquisition friction. Whether you are launching an annual Pro plan with a 7-day free trial or introducing a monthly subscription at a temporary \$1.99 rate, Apple provides robust platform infrastructure to configure, market, and manage introductory pricing.

However, subscription offers in the Apple ecosystem are governed by strict architectural rules:

  1. Introductory Offers apply strictly to new subscribers within a subscription group.
  2. Only one active introductory offer is permitted per subscription per territory at any given moment.
  3. Apple evaluates customer eligibility automatically on the physical device via StoreKit 2, preventing customers from recycling free trials within the same subscription group.
TEXT
┌────────────────────────────────────────────────────────────────────────┐
│                   APPLE INTRODUCTORY OFFER MODES                       │
├───────────────────┬───────────────────────────────┬────────────────────┤
│ Offer Mode        │ Customer Experience           │ Typical Use Case   │
├───────────────────┼───────────────────────────────┼────────────────────┤
│ FREE_TRIAL        │ Access for 0.00 for N periods │ 3-Day, 7-Day, or   │
│                   │ Bills standard price at end   │ 14-Day evaluation  │
├───────────────────┼───────────────────────────────┼────────────────────┤
│ PAY_AS_YOU_GO     │ Discounted recurring price    │ $1.99/mo for first │
│                   │ for N billing periods         │ 3 months, then $9  │
├───────────────────┼───────────────────────────────┼────────────────────┤
│ PAY_UP_FRONT      │ One-time discounted lump sum  │ $19.99 for 6 mos,  │
│                   │ for an extended duration      │ then renews yearly │
└───────────────────┴───────────────────────────────┴────────────────────┘

You can configure introductory offers directly in the App Store Connect web interface or automate their scheduling via App Store Connect REST API operations staged through FlightDeck MCP.


The Primary Introductory Offer Staging Prompt

Use this prompt with your AI coding assistant (Cursor, Claude Code, Windsurf, or Roo Code) connected to FlightDeck to inspect your subscription groups and stage a new free trial offer:

TEXT
Inspect the auto-renewable subscription products for my app [Your App Name]. Find the annual subscription product, check whether it already has an active introductory offer, and stage a 7-day free trial introductory offer for all territories. Show me the before-and-after change set details and do not execute until I approve in the Desktop Approval Center.

The Three Introductory Offer Modes

Apple supports three distinct introductory pricing mechanics under the subscriptionIntroductoryOffers resource:

1. Free Trial (FREE_TRIAL)

The user signs up without paying upfront. They enjoy full access to the subscription tier for a specified duration (duration: THREE_DAYS, ONE_WEEK, TWO_WEEKS, ONE_MONTH, TWO_MONTHS, THREE_MONTHS, SIX_MONTHS, or ONE_YEAR). At the conclusion of the trial period, Apple automatically charges the customer the regular subscription price unless the customer cancels at least 24 hours before the trial ends.

2. Pay As You Go (PAY_AS_YOU_GO)

The customer pays a reduced price for a specific number of billing periods (numberOfPeriods). For example, a customer might pay \$1.99 per month for their first 3 months, after which the subscription renews at the standard \$9.99 per month rate.

  • Constraint: The introductory billing period must match or be shorter than the standard subscription duration.

3. Pay Up Front (PAY_UP_FRONT)

The customer pays a one-time discounted price that covers a multi-period duration. For instance, a customer might pay \$19.99 upfront for an initial 6-month period on a plan that subsequently renews at \$49.99 annually.


Eligibility & Device-Level Enforcement

A common source of confusion among new developers is how introductory offer eligibility is evaluated and enforced:

  1. Subscription Group Scope: Eligibility is calculated at the Subscription Group level, not the individual product level. A customer can receive only one introductory offer per subscription group. If a customer redeems a 7-day free trial on your Monthly plan, they are permanently ineligible for any other introductory offer across all products in that same subscription group. Existing active subscribers within the group are also ineligible for introductory offers on other group products.
  2. On-Device StoreKit 2 Verification: In StoreKit 2, product metadata (product.subscription?.introductoryOffer) reflects whether an offer is configured in App Store Connect—it does not filter out ineligible users. Developers must explicitly query await product.subscription?.isEligibleForIntroOffer to check the signed-in Apple Account's transaction history. If isEligibleForIntroOffer is false, your paywall must render standard recurring pricing rather than the trial offer.
  3. Territory Cardinality: In the App Store Connect API, a subscription maintains a to-many relationship to subscriptionIntroductoryOffers. While you can define distinct introductory offers across different territories or schedule sequential offers across non-overlapping date ranges, Apple strictly restricts each subscription to one active introductory offer per territory at a time.
  4. Cryptographic Validation: StoreKit 2 transactions are delivered as signed JSON Web Signatures (JWS). Developers do not need custom server databases to prevent trial recycling; Apple's cryptographically signed transaction history on the device enforces eligibility authoritatively.

What FlightDeck Can and Cannot Do

To orchestrate subscription configuration safely, note the division of capabilities:

What FlightDeck MCP Can Do

  1. Discover Subscription Groups & Localizations: Call subscription_group_localizations_list to list localized names and verify group structure.
  2. Catalog Inspection: Use flightdeck_api_catalog to inspect parameters for subscriptionIntroductoryOffers_createInstance and related pricing operations.
  3. Stage Introductory Offers: Stage new introductory offers via flightdeck_operation_stage with complete JSON:API relationship payloads.
  4. Desktop Governance: All staged introductory offer additions appear in the FlightDeck Desktop Approval Center with human-readable diffs, preventing accidental price promotions or incorrect durations.
  5. Review Screenshot Verification: Query and upload required App Review subscription screenshots via subscription_review_screenshot_get and monetization_review_screenshot_upload.

What Requires the Developer's Application (Client-Side)

  1. Rendering Paywall UI: FlightDeck configures the metadata on Apple's servers, but your native iOS application (Swift / SwiftUI / Flutter) must present the offer terms to the user using StoreKit 2 (SubscriptionStoreView or custom paywalls).
  2. Displaying Mandatory Terms: Apple App Store Review Guideline 3.1.2 mandates that paywalls clearly state the trial length, renewal price, and cancellation instructions.

Step-by-Step Workflow: Staging a 7-Day Free Trial via API

Here is the complete operational pipeline to configure a 7-day free trial on an annual subscription using FlightDeck:

TEXT
┌────────────────────────────────────────────────────────────────────────┐
│                   INTRODUCTORY OFFER CONFIGURATION PIPELINE            │
│                                                                        │
│   1. QUERY SUBSCRIPTION PRODUCTS & GROUPS                              │
│   [Identify target subscription ID and confirm zero active offers]     │
│                            │                                           │
│                            ▼                                           │
│   2. CONSTRUCT INTRODUCTORY OFFER PAYLOAD                              │
│   [Set duration: ONE_WEEK, offerMode: FREE_TRIAL, periods: 1]          │
│                            │                                           │
│                            ▼                                           │
│   3. STAGE OPERATION VIA FLIGHTDECK MCP                                │
│   [Invoke flightdeck_operation_stage(operationId: ...createInstance)] │
│                            │                                           │
│                            ▼                                           │
│   4. REVIEW IN DESKTOP APPROVAL CENTER                                 │
│   [Inspect human-readable parameters; click 'Approve Mutation']        │
│                            │                                           │
│                            ▼                                           │
│   5. DISPATCH & READ-BACK VERIFICATION                                 │
│   [FlightDeck dispatches POST; verifies active status on Apple API]    │
└────────────────────────────────────────────────────────────────────────┘

Step 1: Discover the Subscription Product ID

First, list your application's subscription groups and products:

TEXT
Inspect my app's subscription groups. Find the annual subscription product identifier and return its internal Apple resource ID.

Step 2: Stage the Introductory Offer

Next, have the assistant stage the creation of the introductory offer. Behind the scenes, FlightDeck targets subscriptionIntroductoryOffers_createInstance (POST /v1/subscriptionIntroductoryOffers):

JSON
{
  "data": {
    "type": "subscriptionIntroductoryOffers",
    "attributes": {
      "duration": "ONE_WEEK",
      "offerMode": "FREE_TRIAL",
      "numberOfPeriods": 1
    },
    "relationships": {
      "subscription": {
        "data": {
          "type": "subscriptions",
          "id": "6471234567"
        }
      }
    }
  }
}
Note

For FREE_TRIAL offers, subscriptionPricePoint relationship is omitted because the customer price is 0.00. For PAY_AS_YOU_GO or PAY_UP_FRONT, you must also link the target discounted subscriptionPricePoint.

Step 3: Approve and Execute in FlightDeck Desktop

  1. Open FlightDeck Desktop.
  2. In the Desktop Approval Center, inspect the staged operation: - Operation: subscriptionIntroductoryOffers_createInstance - Target: Subscription 6471234567 - Offer Mode: FREE_TRIAL - Duration: ONE_WEEK
  3. Click Approve Mutation.
  4. FlightDeck transmits the cryptographically confirmed payload to Apple's REST API and performs an immediate read-back query to confirm that the introductory offer is active.

In-App StoreKit 2 Presentation Example

Once configured in App Store Connect, display the offer in your SwiftUI app, ensuring you check eligibility asynchronously before rendering trial pricing:

SWIFT
import SwiftUI
import StoreKit

struct ProSubscriptionView: View {
    @State private var subscriptionProduct: Product?
    @State private var isEligibleForTrial = false

    var body: some View {
        VStack(spacing: 16) {
            Text("Unlock FlightDeck Pro")
                .font(.title.bold())
            
            if let product = subscriptionProduct {
                if isEligibleForTrial,
                   let offer = product.subscription?.introductoryOffer,
                   offer.paymentMode == .freeTrial {
                    Text("Start with \(offer.period.value) \(offer.period.unit) free!")
                        .font(.headline)
                        .foregroundColor(.green)
                    Text("Then \(product.displayPrice) / year. Cancel anytime.")
                        .font(.subheadline)
                        .foregroundColor(.secondary)
                } else {
                    Text("\(product.displayPrice) / year")
                        .font(.headline)
                }
                
                Button(isEligibleForTrial ? "Try Free & Subscribe" : "Subscribe Now") {
                    Task { await purchase(product) }
                }
                .buttonStyle(.borderedProminent)
            }
        }
        .task {
            let products = try? await Product.products(for: ["com.example.pro.annual"])
            if let product = products?.first {
                subscriptionProduct = product
                if let subscription = product.subscription {
                    isEligibleForTrial = await subscription.isEligibleForIntroOffer
                }
            }
        }
    }
}

Common Errors & Troubleshooting

1. 409 CONFLICT: An active introductory offer already exists

  • Cause: You attempted to create an introductory offer for a subscription that already has an active offer in the same territory.
  • Fix: Terminate or delete the existing introductory offer first (DELETE /v1/subscriptionIntroductoryOffers/{id}) or specify an end date before staging a replacement.

2. StoreKit: Customer Charged Full Price Instead of Trial

  • Cause: The client UI displayed free trial messaging without checking await product.subscription?.isEligibleForIntroOffer. If the user previously used a trial in that subscription group, StoreKit executes the transaction at regular price.
  • Fix: Guard all paywall trial messaging with isEligibleForIntroOffer. In Sandbox testing, clear purchase history under Settings > App Store > Sandbox Account or create a fresh tester in App Store Connect.

3. App Review Rejection: Guideline 3.1.2 Subscriptions

  • Cause: The paywall displays "Start Free Trial" in large type, but hides or obscures the subsequent recurring charge, billing frequency, or cancellation terms.
  • Fix: Ensure the paywall clearly displays: (1) Trial duration, (2) Price after trial concludes, (3) Duration of regular billing, and (4) Instructions indicating that subscriptions can be managed or canceled in Apple Account settings.


Official References


Evidence Limitations & Verifications

  • API Endpoint Verification: Verified against Apple's openapi.oas.json schema for subscriptionIntroductoryOffers (duration, offerMode, numberOfPeriods).
  • Codebase Staging Inspection: Verified against FlightDeck's asc_mcp_server.dart and operation_registry.g.dart universal operation dispatch framework.
  • Client-Side Dependency: Setting introductory offers via API configures Apple's server records; rendering and user acceptance require native client StoreKit code on the target device.

Connect Your AI Agent to App Store Connect

FlightDeck runs locally on your Mac, keeping private keys secure in your macOS Keychain and executing mutations only after your explicit approval.

Download FlightDeck on Mac App Store