Enable purchases with Flow Builder in iOS SDK

To enable in-app purchases, you need to understand three key concepts:

Products – anything users can buy (subscriptions, consumables, lifetime access)
Flows – screen sequences that present products to users, built in the no-code Flow Builder. The SDK retrieves them via getFlow. If you’d rather build the UI in your own code, use a paywall instead — see Implement paywalls manually.
Placements – where and when you show flows in your app (like main, onboarding, settings). You attach flows to placements in the dashboard, then request them by placement ID in your code. This makes it easy to run A/B tests and show different flows to different users.

Adapty offers you three ways to enable purchases in your app. Select one of them depending on your app requirements:

Implementation	Complexity	When to use
Adapty Flow Builder	✅ Easy	You create a complete, purchase-ready flow in the no-code builder. Adapty automatically renders it and handles all the complex purchase flow, receipt validation, and subscription management behind the scenes.
Manually created paywalls	🟡 Medium	You implement your paywall UI in your app code, but still get the flow object from Adapty to maintain flexibility in product offerings. See the guide.
Observer mode	🔴 Hard	You already have your own purchase handling infrastructure and want to keep using it. Note that the observer mode has its limitations in Adapty. See the article.

The steps below show how to implement a flow created in the Adapty Flow Builder.

If you’d rather build the paywall UI yourself, see Implement paywalls manually.

To display a flow created in the Adapty Flow Builder, in your app code, you only need to:

Get the flow: Get it from Adapty.
Display it and Adapty will handle purchases for you: Show the view in your app.
Handle button actions: Associate user interactions with your app’s response to them. For example, open links or close the flow when users click buttons.

Before you start

Before you start, complete these steps:

Connect your app to the App Store in the Adapty Dashboard.
Create your products in Adapty.
Create a flow and add products to it.
Create a placement and add your flow to it.
Install and activate the Adapty SDK in your app code. This guide uses Adapty iOS SDK v4 (beta) APIs.

1. Get the flow

Your flows are associated with placements configured in the dashboard. Placements allow you to run different flows for different audiences or to run A/B tests.

To get a flow created in the Adapty Flow Builder, you need to:

Get the flow object by the placement ID using the getFlow method and check whether it has a view configuration.
Get the view configuration using the getFlowConfiguration method. It contains the UI elements and styling needed to display the flow.

import Adapty
import AdaptyUI

func loadFlow() async {
    let flow = try await Adapty.getFlow(placementId: "YOUR_PLACEMENT_ID")

    guard flow.hasViewConfiguration else {
        print("Flow doesn't have a view configuration")
        return
    }

    flowConfiguration = try await AdaptyUI.getFlowConfiguration(forFlow: flow)
}

2. Display the flow

Now, when you have the flow configuration, it’s enough to add a few lines to display your flow.

In SwiftUI, when displaying the flow, you also need to handle events. didFailPurchase, didFinishRestore, didFailRestore, and didReceiveError are required. When testing, you can just copy the code from the snippet below to log these events.

Handling didFinishPurchase isn’t required, but is useful when you want to perform actions after a successful purchase. If you don’t implement that callback, the flow will dismiss automatically.

.flow(
    isPresented: $flowPresented,
    flowConfiguration: flowConfiguration,
    didFailPurchase: { product, error in
        print("Purchase failed: \(error)")
    },
    didFinishRestore: { profile in
        print("Restore finished successfully")
    },
    didFailRestore: { error in
        print("Restore failed: \(error)")
    },
    didReceiveError: { error in
        flowPresented = false
        print("Flow error: \(error)")
    }
)

import UIKit
import AdaptyUI

func presentFlow(with config: AdaptyUI.FlowConfiguration) {
    let flowController = try AdaptyUI.flowController(
        with: config,
        delegate: self
    )
    present(flowController, animated: true)
}

Implement AdaptyFlowControllerDelegate to handle events. At minimum, implement the required error handlers (the three methods that have no default implementation):

extension YourViewController: AdaptyFlowControllerDelegate {
    func flowController(_ controller: AdaptyFlowController,
                        didFailPurchase product: AdaptyPaywallProduct,
                        error: AdaptyError) {
        print("Purchase failed: \(error)")
    }

    func flowController(_ controller: AdaptyFlowController,
                        didFinishRestoreWith profile: AdaptyProfile) {
        print("Restore finished successfully")
    }

    func flowController(_ controller: AdaptyFlowController,
                        didFailRestoreWith error: AdaptyError) {
        print("Restore failed: \(error)")
    }
}

For more details on how to display a flow, see our guide.

3. Handle button actions

When users click buttons, the iOS SDK automatically handles purchases, restoration, closing the flow, and opening links.

However, other buttons have custom or pre-defined IDs and require handling actions in your code. Or, you may want to override their default behavior.

For example, here is how to handle the close button. In UIKit, the SDK dismisses the controller automatically when .close fires — override only if you want custom behavior. In SwiftUI, you must set your isPresented binding to false yourself.

Read our guides on how to handle button actions and events.

.flow(
    isPresented: $flowPresented,
    flowConfiguration: flowConfiguration,
    didPerformAction: { action in
        switch action {
            case .close:
                flowPresented = false // dismiss the flow when the user taps close
            default:
                break
        }
    },
    didFailPurchase: { product, error in /* handle the error */ },
    didFinishRestore: { profile in /* check access level and dismiss */ },
    didFailRestore: { error in /* handle the error */ },
    didReceiveError: { error in flowPresented = false }
)

extension YourViewController: AdaptyFlowControllerDelegate {
    func flowController(_ controller: AdaptyFlowController,
                        didPerform action: AdaptyUI.Action) {
        switch action {
            case .close:
                controller.dismiss(animated: true) // default behavior — override only if needed
            default:
                break
        }
    }
}

Next steps

Have questions or running into issues? Check out our support forum where you can find answers to common questions or ask your own. Our team and community are here to help!

Your flow is ready to be displayed in the app. Test your purchases in sandbox mode to make sure you can complete a test purchase.

Now, you need to check the users’ access level to ensure you display a flow or give access to paid features to the right users.

Full example

Here is how all the steps from this guide can be integrated in your app together.

import SwiftUI
import Adapty
import AdaptyUI

struct ContentView: View {
    @State private var flowPresented = false
    @State private var flowConfiguration: AdaptyUI.FlowConfiguration?
    @State private var isLoading = false
    @State private var hasInitialized = false

    var body: some View {
        VStack {
            if isLoading {
                ProgressView("Loading...")
            } else {
                Text("Your App Content")
            }
        }
        .task {
            guard !hasInitialized else { return }
            await initializeFlow()
            hasInitialized = true
        }
        .flow(
            isPresented: $flowPresented,
            flowConfiguration: flowConfiguration,
            didPerformAction: { action in
                switch action {
                case .close:
                    flowPresented = false
                default:
                    break
                }
            },
            didFailPurchase: { product, error in
                print("Purchase failed: \(error)")
            },
            didFinishRestore: { profile in
                print("Restore finished successfully")
            },
            didFailRestore: { error in
                print("Restore failed: \(error)")
            },
            didReceiveError: { error in
                print("Flow error: \(error)")
                flowPresented = false
            }
        )
    }

    private func initializeFlow() async {
        isLoading = true
        defer { isLoading = false }

        await loadFlow()
        flowPresented = true
    }

    private func loadFlow() async {
        do {
            let flow = try await Adapty.getFlow(placementId: "YOUR_PLACEMENT_ID")
            guard flow.hasViewConfiguration else {
                print("Flow doesn't have a view configuration")
                return
            }
            flowConfiguration = try await AdaptyUI.getFlowConfiguration(forFlow: flow)
        } catch {
            print("Failed to load: \(error)")
        }
    }
}

import UIKit
import Adapty
import AdaptyUI

class ViewController: UIViewController {
    private var flowConfiguration: AdaptyUI.FlowConfiguration?

    override func viewDidLoad() {
        super.viewDidLoad()

        Task {
            await initializeFlow()
        }
    }

    private func initializeFlow() async {
        do {
            flowConfiguration = try await loadFlow()

            if let flowConfiguration {
                await MainActor.run {
                    presentFlow(with: flowConfiguration)
                }
            }
        } catch {
            print("Error initializing: \(error)")
        }
    }

    private func loadFlow() async throws -> AdaptyUI.FlowConfiguration? {
        let flow = try await Adapty.getFlow(placementId: "YOUR_PLACEMENT_ID")

        guard flow.hasViewConfiguration else {
            print("Flow doesn't have a view configuration")
            return nil
        }

        return try await AdaptyUI.getFlowConfiguration(forFlow: flow)
    }

    private func presentFlow(with config: AdaptyUI.FlowConfiguration) {
        guard let flowController = try? AdaptyUI.flowController(
            with: config,
            delegate: self
        ) else { return }

        present(flowController, animated: true)
    }
}

extension ViewController: AdaptyFlowControllerDelegate {
    func flowController(_ controller: AdaptyFlowController,
                        didFailPurchase product: AdaptyPaywallProduct,
                        error: AdaptyError) {
        print("Purchase failed for \(product.vendorProductId): \(error)")

        guard error.adaptyErrorCode != .paymentCancelled else { return }

        let message = switch error.adaptyErrorCode {
        case .paymentNotAllowed:
            "Purchases are not allowed on this device."
        default:
            "Purchase failed. Please try again."
        }

        let alert = UIAlertController(title: "Purchase Error", message: message, preferredStyle: .alert)
        alert.addAction(UIAlertAction(title: "OK", style: .default))
        present(alert, animated: true)
    }

    func flowController(_ controller: AdaptyFlowController,
                        didFinishRestoreWith profile: AdaptyProfile) {
        print("Restore finished successfully")
        controller.dismiss(animated: true)
    }

    func flowController(_ controller: AdaptyFlowController,
                        didFailRestoreWith error: AdaptyError) {
        print("Restore failed: \(error)")
    }

    func flowController(_ controller: AdaptyFlowController,
                        didReceiveError error: AdaptyUIError) {
        print("Flow error: \(error)")
        controller.dismiss(animated: true)
    }
}