Offerings

Offerings are the SDK surface for your purchase catalog. They are created in the AppActor dashboard, returned by the SDK, and used by your app to render its own paywall UI.

The AppActor SDK purchase path is offering-first: fetch offerings, pick an offering, render packages, purchase a package.

Fetch the current offering

Use current for the default paywall. The dashboard decides which offering is current for the project, so your app does not need a release to change the default package set.

let offerings = try await AppActor.shared.offerings()

guard let offering = offerings.current else {
    // Show an empty-state paywall or hide the upgrade CTA.
    return
}

let packages = offering.packages

lifecycleScope.launch {
    val offerings = AppActor.shared.offerings()
    val offering = offerings.current

    if (offering == null) {
        // Show an empty-state paywall or hide the upgrade CTA.
        return@launch
    }

    val packages = offering.packages
}

final offerings = await AppActor.instance.getOfferings();
final offering = offerings.current;

if (offering == null) {
  // Show an empty-state paywall or hide the upgrade CTA.
  return;
}

final packages = offering.packages;

const offerings = await AppActor.instance.getOfferings();
const offering = offerings.current;

if (!offering) {
  // Show an empty-state paywall or hide the upgrade CTA.
  return;
}

const packages = offering.packages;

Dashboard creation checklist

For the first offering, create a small, obvious setup:

Offering ID or lookup key: default.
Current offering: enabled.
Package slots: monthly and annual.
Package order: monthly first or annual first, matching your paywall design.
Product mapping: each package maps to the correct iOS and Android product.
Metadata: optional labels such as badge: "Best value" or placement-specific copy.

If your app fetches offerings.current.monthly, both the current offering and the monthly package slot must exist for the running platform.

Use package helpers

Package helpers are convenient, but they only exist when the dashboard package slot exists.

let monthly = offering.monthly
let annual = offering.annual
let lifetime = offering.lifetime
let custom = offering.packages.first {
    $0.customTypeIdentifier == "starter_pack" || $0.id == "starter_pack"
}

val monthly = offering.monthly
val annual = offering.annual
val lifetime = offering.lifetime
val custom = offering.packages.firstOrNull {
    it.customTypeIdentifier == "starter_pack" || it.id == "starter_pack"
}

final monthly = offering.monthly;
final annual = offering.annual;
final lifetime = offering.lifetime;
final custom = offering.package('starter_pack');

const monthly = offering.monthly;
const annual = offering.annual;
const lifetime = offering.lifetime;
const custom = offering.package('starter_pack');

If monthly is null, the SDK is usually telling you the dashboard offering does not contain a monthly package for that app/platform.

Fetch by offering id or lookup key

Use current for most paywalls. Use explicit IDs or lookup keys only when the product design needs a specific surface, such as onboarding versus settings.

let offerings = try await AppActor.shared.offerings()
let onboarding = offerings.offering(lookupKey: "onboarding")
let settings = offerings.offering(id: "settings_paywall")

val offerings = AppActor.shared.offerings()
val onboarding = offerings.offeringByLookupKey("onboarding")
val settings = offerings.offering("settings_paywall")

final offerings = await AppActor.instance.getOfferings();
final onboarding = offerings.offeringByLookupKey('onboarding');
final settings = offerings.offering('settings_paywall');

const offerings = await AppActor.instance.getOfferings();
const onboarding = offerings.offeringByLookupKey('onboarding');
const settings = offerings.offering('settings_paywall');

Use cached and fallback offerings deliberately

Wrappers expose cached offerings for fast UI and fallback offerings for offline resilience:

final cached = await AppActor.instance.getCachedOfferings();
final cachedCurrent = cached?.current;

if (cachedCurrent != null) {
  renderPaywall(cachedCurrent.packages);
}

final fresh = await AppActor.instance.getOfferings();
renderPaywall(fresh.current?.packages ?? const []);

const cached = await AppActor.instance.getCachedOfferings();
if (cached?.current) {
  renderPaywall(cached.current.packages);
}

const fresh = await AppActor.instance.getOfferings();
renderPaywall(fresh.current?.packages ?? []);

Use cached data to paint quickly. Use fresh data before release testing, support debugging, and purchase recovery.

Troubleshooting empty offerings

Empty offerings are almost always a configuration issue, not a rendering issue. Check:

the app uses the right public app SDK key
the project has a current offering
the offering has at least one package
package products exist for the running platform
products are available in App Store Connect or Google Play for the tester account
the package’s products are attached to the entitlement you check after purchase

Once offerings load, continue with Displaying Products.

Overview

Configure Products

Notifications & Webhooks

Fetch the current offering

Dashboard creation checklist

Use package helpers

Fetch by offering id or lookup key

Use cached and fallback offerings deliberately

Troubleshooting empty offerings

​Fetch the current offering

​Dashboard creation checklist

​Use package helpers

​Fetch by offering id or lookup key

​Use cached and fallback offerings deliberately

​Troubleshooting empty offerings

Fetch the current offering

Dashboard creation checklist

Use package helpers

Fetch by offering id or lookup key

Use cached and fallback offerings deliberately

Troubleshooting empty offerings