Add subscriptions to your iOS app in 4 easy steps

Purchase a Product

Trigger a purchase flow for a subscription or one-time purchase. Payo handles the StoreKit transaction, verifies it, and updates access automatically.

When to use this

Call this when a user taps a "Subscribe" or "Buy" button on your paywall. Payo presents the system payment sheet, processes the result, and returns transaction details.

Returns

PurchaseInfo contains: productID, transactionID, purchaseDate, expirationDate (nil for lifetime), and originalTransactionID.

Button("Subscribe for \(product.displayPrice)") {
    Task {
        do {
            let info = try await Payo.purchase("pro_monthly")
            print("Purchased! Expires: \(info.expirationDate ?? .now)")
        } catch let error as PayoError {
            switch error {
            case .userCancelled:
                break // user tapped Cancel — do nothing
            case .purchasePending:
                showAlert("Purchase pending approval.")
            default:
                showAlert("Error: \(error.localizedDescription)")
            }
        }
    }
}

@IBAction func subscribeTapped(_ sender: Any) {
    Task {
        do {
            let info = try await Payo.purchase("pro_monthly")
            print("Purchased! Expires: \(info.expirationDate ?? .now)")
        } catch let error as PayoError {
            switch error {
            case .userCancelled:
                break // user tapped Cancel — do nothing
            case .purchasePending:
                showAlert("Purchase pending approval.")
            default:
                showAlert("Error: \(error.localizedDescription)")
            }
        } catch {
            showAlert("Error: \(error.localizedDescription)")
        }
    }
}

private func showAlert(_ message: String) {
    let alert = UIAlertController(title: nil, message: message, preferredStyle: .alert)
    alert.addAction(UIAlertAction(title: "OK", style: .default))
    present(alert, animated: true)
}

Check & Gate Access

Gate features behind a subscription. Use the one-liner view modifier for the simplest approach, or check access manually for full control.

One-liner gate (recommended)

Lock any view behind subscription access with a single modifier or method call. Content is blurred with a lock icon overlay until the user subscribes. Fully reactive — the overlay appears and disappears automatically as access changes from purchases, restores, renewals, expirations, and app foregrounding. No state observation code needed.

// Default — blur + lock overlay
GroupBox("Premium Analytics") {
    AnalyticsChart()
}
.requiresAccess()

// Custom message and icon
GroupBox("Pro Features") {
    ProDashboard()
}
.requiresAccess("Pro Feature", icon: "star.fill")

// Fully custom overlay
GroupBox("Premium") {
    AnalyticsChart()
}
.requiresAccess {
    VStack {
        Image(systemName: "crown.fill")
            .font(.title)
        Text("Upgrade to Pro")
            .font(.headline)
    }
}

// Full-screen paywall — overlay is fully interactive
TabView {
    HomeView()
    SettingsView()
}
.requiresAccess {
    MyPaywallView() // buttons, links, etc. all work
}

// Gate behind a specific group (for multi-tier apps)
GroupBox("Premium Features") {
    PremiumDashboard()
}
.requiresAccess(group: "premium")

override func viewDidLoad() {
    super.viewDidLoad()

    // Gate a view — adds blur + lock overlay automatically
    premiumView.setRequiresAccess()

    // Gate behind a specific group
    analyticsView.setRequiresAccess(group: "premium")
}

// To remove the gate later (e.g. on deinit)
premiumView.removeRequiresAccess()

Manual check (custom behavior)

If you need custom logic beyond the blur overlay — like showing a paywall, navigating to a different screen, or disabling specific controls — check access directly.

// Check access to any configured product
if Payo.hasAccess {
    // unlock pro features
} else {
    // show paywall
}

// Check access to a specific group (for multi-tier apps)
if Payo.hasAccess("premium") {
    // unlock premium-only features
}

Reactive UI (custom behavior)

For custom UI that should react to access changes in real time, observe Payo.state directly.

struct ContentView: View {
    @ObservedObject var billing = Payo.state

    var body: some View {
        if billing.hasAccess {
            ProFeatureView()
        } else {
            PaywallView()
        }
    }
}

import Combine

class ViewController: UIViewController {
    private var cancellable: AnyCancellable?

    override func viewDidLoad() {
        super.viewDidLoad()
        cancellable = Payo.state.$hasAccess
            .receive(on: DispatchQueue.main)
            .sink { [weak self] hasAccess in
                if hasAccess {
                    // show pro features
                } else {
                    // show upgrade prompt
                }
            }
    }
}

Display Product Info

Fetch localized product names, descriptions, and prices from the App Store to display on your paywall. Prices are already formatted for the user's locale and currency.

When to use this

Call this when building your paywall or pricing screen. Never hard-code prices — the App Store provides localized pricing that varies by country.

All products

Single product

ProductInfo fields

// ProductInfo properties:
product.id            // "pro_monthly"
product.displayName   // "Pro Monthly"
product.description   // "Unlock all pro features"
product.displayPrice  // "$4.99" (localized)
product.price         // 4.99 (Decimal)
product.introOffer    // IntroOffer? (free trial info)

struct PaywallView: View {
    @State private var products: [ProductInfo] = []

    var body: some View {
        VStack(spacing: 16) {
            ForEach(products, id: \.id) { product in
                Button {
                    Task { try? await Payo.purchase(product.id) }
                } label: {
                    HStack {
                        VStack(alignment: .leading) {
                            Text(product.displayName).font(.headline)
                            Text(product.description).font(.caption)
                        }
                        Spacer()
                        Text(product.displayPrice)
                            .font(.headline)
                    }
                    .padding()
                    .background(.ultraThinMaterial)
                    .cornerRadius(12)
                }
            }
        }
        .task {
            products = await Payo.allProductInfo()
        }
    }
}

class PaywallViewController: UITableViewController {
    private var products: [ProductInfo] = []

    override func viewDidLoad() {
        super.viewDidLoad()
        Task {
            products = await Payo.allProductInfo()
            tableView.reloadData()
        }
    }

    override func tableView(_ tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
        products.count
    }

    override func tableView(_ tableView: UITableView, cellForRowAt indexPath: IndexPath) -> UITableViewCell {
        let cell = tableView.dequeueReusableCell(withIdentifier: "cell", for: indexPath)
        let product = products[indexPath.row]
        cell.textLabel?.text = product.displayName
        cell.detailTextLabel?.text = product.displayPrice
        return cell
    }

    override func tableView(_ tableView: UITableView, didSelectRowAt indexPath: IndexPath) {
        let product = products[indexPath.row]
        Task { try? await Payo.purchase(product.id) }
    }
}

Intro Offer Eligibility

Check if the user qualifies for an introductory offer (free trial, discounted first period, or pay-up-front) and display it on your paywall.

When to use this

Call this when loading your paywall to decide whether to show a "Free Trial" or "Special Offer" badge. Apple only allows intro offers for first-time subscribers within a subscription group.

IntroOffer fields

// IntroOffer properties (from ProductInfo.introOffer):
offer.displayPrice  // "Free" or "$0.99"
offer.periodCount   // 1
offer.periodUnit    // .week, .month, .year
offer.periodValue   // 7 (days)
offer.paymentMode   // .freeTrial, .payAsYouGo, .payUpFront

struct PaywallView: View {
    @State private var products: [ProductInfo] = []
    @State private var introEligible = false

    var body: some View {
        VStack {
            if introEligible, let offer = products.first?.introOffer {
                Text("Start your free \(offer.periodValue)-day trial!")
                    .font(.headline)
                    .foregroundStyle(.green)
            }

            ForEach(products, id: \.id) { product in
                Button(product.displayName) {
                    Task { try? await Payo.purchase(product.id) }
                }
            }
        }
        .task {
            products = await Payo.allProductInfo()
            introEligible = await Payo.isEligibleForIntroOffer()
        }
    }
}

class PaywallViewController: UIViewController {
    @IBOutlet weak var trialBadge: UILabel!

    override func viewDidLoad() {
        super.viewDidLoad()
        Task {
            let products = await Payo.allProductInfo()
            let eligible = await Payo.isEligibleForIntroOffer()

            if eligible, let offer = products.first?.introOffer {
                trialBadge.text = "Start your free \(offer.periodValue)-day trial!"
                trialBadge.isHidden = false
            } else {
                trialBadge.isHidden = true
            }
        }
    }
}

Restore Purchases

Sync the user's previous purchases with the App Store. This re-activates access if they've already paid — essential when switching devices or reinstalling.

When to use this

Add a "Restore Purchases" button to your paywall or settings screen. Apple requires this for App Store review — your app will be rejected without it.

Button("Restore Purchases") {
    Task {
        do {
            try await Payo.restorePurchases()
            // Access is automatically updated
        } catch {
            showAlert("Restore failed: \(error.localizedDescription)")
        }
    }
}

@IBAction func restoreTapped(_ sender: Any) {
    Task {
        do {
            try await Payo.restorePurchases()
            // Access is automatically updated
        } catch {
            let alert = UIAlertController(
                title: "Error",
                message: "Restore failed: \(error.localizedDescription)",
                preferredStyle: .alert
            )
            alert.addAction(UIAlertAction(title: "OK", style: .default))
            present(alert, animated: true)
        }
    }
}

Manage Subscriptions

Open Apple's built-in subscription management sheet where users can upgrade, downgrade, or cancel their subscription.

When to use this

Add a "Manage Subscription" button in your settings or account screen. Apple requires this for App Store review — users must be able to manage their subscription from within your app.

Button("Manage Subscription") {
    Task {
        try? await Payo.showManageSubscriptions()
    }
}

@IBAction func manageTapped(_ sender: Any) {
    Task {
        try? await Payo.showManageSubscriptions()
    }
}

Request a refund

Let users request a refund directly in your app. Apple shows their native refund sheet — no custom UI needed. If Apple approves the refund, Payo automatically revokes access.

Button("Request Refund") {
    Task {
        let status = try? await Payo.beginRefundRequest("pro_monthly")
        if status == .success {
            // Apple is reviewing the request
        }
    }
}

@IBAction func refundTapped(_ sender: Any) {
    Task {
        let status = try? await Payo.beginRefundRequest("pro_monthly")
        if status == .success {
            // Apple is reviewing the request
        }
    }
}

Multi-Tier Access

Support multiple subscription tiers (e.g. "Pro" and "Premium") by configuring with named groups and checking access per group.

When to use this

If your app has different feature levels — for example, a "Pro" plan that unlocks basic features and a "Premium" plan that unlocks everything — use named groups so you can gate each set of features independently.

Check access per group

struct FeatureView: View {
    var body: some View {
        VStack {
            if Payo.hasAccess("pro") {
                ProFeaturesView()
            }

            if Payo.hasAccess("premium") {
                PremiumFeaturesView()
            }

            if !Payo.hasAccess {
                PaywallView()
            }
        }
    }
}

class FeatureViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()

        if Payo.hasAccess("pro") {
            setupProFeatures()
        }

        if Payo.hasAccess("premium") {
            setupPremiumFeatures()
        }

        if !Payo.hasAccess {
            showPaywall()
        }
    }
}

Refresh & Reset

Manually re-check the user's entitlements or clear all billing state.

Refresh entitlements

Forces Payo to re-query StoreKit for the user's current purchases. You rarely need this — the SDK automatically refreshes on foreground return, transaction updates, and subscription expiration. Mainly useful during development or sandbox testing.

// Re-check purchases (e.g., after testing in Xcode Sandbox)
await Payo.refreshEntitlements()

Reset all state

Clears all billing state, stops the transaction observer, and re-initializes from Payo.plist. Useful when a user logs out of your app.

Button("Log Out") {
    Task {
        await Payo.reset()
        // Automatically re-initializes from Payo.plist
    }
}

@IBAction func logOutTapped(_ sender: Any) {
    Task {
        await Payo.reset()
        // Automatically re-initializes from Payo.plist
    }
}

PayoPurchaseButton

A drop-in SwiftUI button that auto-fetches product info, displays a smart label (with intro offer awareness), handles the purchase flow, and reports the result — all in one line of code.

Default smart label

The button automatically fetches the product's price and intro offer eligibility, then renders the right label: a free trial CTA, an intro price, or the standard subscription price.

// Smart label — auto-fetches price + intro offer
// Renders: "Start 7-Day Free Trial" or "Subscribe — $4.99"
PayoPurchaseButton("pro_monthly")
    .buttonStyle(.borderedProminent)

With callbacks

Handle success and error events with optional closures. The button silently ignores user cancellation.

PayoPurchaseButton("pro_monthly", onPurchase: { info in
    print("Purchased! Expires: \(info.expirationDate ?? .now)")
}, onError: { error in
    print("Failed: \(error.localizedDescription)")
})
.buttonStyle(.borderedProminent)

Custom label

Use a ViewBuilder closure to build any label you want. Your closure receives the loaded ProductInfo and a Bool indicating intro offer eligibility.

PayoPurchaseButton("pro_monthly") { product, isEligibleForTrial in
    HStack {
        VStack(alignment: .leading) {
            Text(product.displayName)
                .font(.headline)
            if isEligibleForTrial {
                Text("Free trial available")
                    .font(.caption)
                    .foregroundStyle(.green)
            }
        }
        Spacer()
        Text(product.displayPrice)
            .fontWeight(.semibold)
    }
}
.buttonStyle(.bordered)

Behavior

Under the hood, the button handles the full lifecycle:

Set Up App Store Connect

When you're ready for production, create matching subscription products in App Store Connect. Your product IDs in App Store Connect must match the ones in your Payo.plist exactly.