Skip to content
AppDues
Log in
Contact salesSign up

Custom Paywalls Next to Managed Paywalls: A Wiring Guide

A hand-built paywall can coexist with a paywall you manage in the subscription dashboard. The split is deliberate: your app owns the visual layer, while the subscription platform remains the single source for products, purchases and entitlements. This guide shows where each responsibility sits, how to route users to the right UI, and what to do when metadata is absent or a purchase fails.

When two paywall types make sense

Keeping a custom paywall alive next to a dashboard-managed one is useful in a few concrete situations. You may be migrating gradually from an older hard-coded paywall. You may want to test a newly built dashboard-managed paywall against the existing one. You may need a heavily customised presentation for a specific segment or promotional price. Or you may have onboarding flows and feature gates whose logic does not fit a single template.

The important boundary is that the app decides which UI appears, but every purchase still goes through the subscription SDK. That avoids duplicated purchase logic, price mismatches and entitlement drift. Presentation stays flexible; the subscription system stays centralised.

The end-to-end flow

A user reaches a paywall decision point — end of onboarding, a gated feature, or a promotional entry point. The app requests Offerings for a specific Placement. The platform returns the Offering appropriate to that user and Placement, which may vary because of targeting rules. The app inspects the Offering metadata to decide which paywall to show: the dashboard-managed paywall UI or a fully custom UI. Product and pricing data always come from the subscription platform. The user selects a product, the purchase is initiated through the subscription SDK, and the flow is identical regardless of which UI was shown. The platform then updates entitlements, and the app unlocks or restricts content based on CustomerInfo.

If you use the platform's Experiment feature, the same setup lets you compare how different placements and paywalls convert.

What the dashboard-managed paywall handles

Dashboard-managed paywalls are built to simplify showing products to users. You create, manage and test designs in the subscription dashboard, and the paywall handles fetching product information and presenting it. Changes to the paywall do not require a new app release. For most new apps this is the sensible default, because you can iterate without shipping to the stores.

A custom paywall is the exception, not the rule. Reach for it when a design element from your app must appear in the paywall — for example, a gamified app might show a broken streak and explain that subscribing restores it. In that case you take control of the UI/UX but still rely on the subscription SDK for fetching products and making purchases.

Step 1 — Fetch product information

Fetching products first is what lets you show correct subscription options, prices and introductory offers. In Swift the usual call is Purchases.shared.getOfferings(); on Kotlin it is Purchases.sharedInstance.getOfferingsWith(). Both return an Offering object containing the product details you need. The Swift and Kotlin snippets below show the expected call shape for each platform.

Step 2 — Make the purchase

When the user picks a product on your custom paywall, initiate the purchase through the subscription SDK. On iOS that is Purchases.shared.purchase(package:); on Android it is Purchases.sharedInstance.purchaseWith(). Handle both the completion and any errors. The snippets below show the expected callback shape, including the entitlement check that unlocks content.

Step 3 — Read entitlements

Entitlement management is the same whether the paywall was custom or dashboard-managed. After a successful purchase the platform updates the user's CustomerInfo, and you use that to grant or restrict premium access. In Swift you can read it with Purchases.shared.getCustomerInfo; in Kotlin with Purchases.sharedInstance.getCustomerInfoWith(). The snippets below show the exact calls.

Choosing which paywall to display

Two levers control the choice. Placement defines where in the journey an offering appears, and Offering metadata attaches extra information you can read in the app to distinguish a custom paywall from a dashboard-managed paywall.

Placements map to real moments: onboarding_end at the end of onboarding, feature_gate when a customer tries a paywalled feature, and sale_offer when a promotion is running. Decide placements by how they fit your ideal customer journey — during a sale you likely want different copy for onboarded customers than for first-time users. When the app fetches Offerings by Placement, the platform returns the Offering for that customer at that Placement. The Swift and Kotlin snippets below show the placement lookup calls.

Offering metadata is the key to customising what a custom paywall shows. In the dashboard, open an Offering and use Edit or Configure metadata to add valid JSON. A simple example is a custom_paywall boolean. That metadata travels with the Offering data when the SDK fetches Offerings, so the app can branch on it dynamically.

Reading metadata safely

Metadata is optional by nature. Every read should be written so the app and its paywalls still work when a value is missing from the dashboard. In practice that means defaulting to the dashboard-managed paywall when the flag is absent, rather than crashing or showing a blank screen.

A useful decision checklist before shipping:

  • Does the app request Offerings by Placement at each paywall decision point?
  • Does every metadata read have a default value?
  • Does a missing custom_paywall flag fall back to the dashboard-managed paywall?
  • Does the purchase path go through the subscription SDK in both UI branches?
  • Does the entitlement check read CustomerInfo rather than local state?
  • Are the Swift and Kotlin calls reproduced exactly as shown?

A worked example: a gamified app shows a broken-streak visual at onboarding_end. The Offering for that placement carries custom_paywall set to true, so the app renders its own paywall with the streak graphic. If the flag is removed, the same placement falls back to the dashboard-managed paywall with no code change.

Two different failures to keep apart

A missing metadata value is not a purchase failure. It only means the app cannot tell which UI to show, so it should fall back to the dashboard-managed paywall. A failed or cancelled purchase is different: the user may have cancelled, or the store may have returned an error, and no entitlement should be unlocked. Treat the two paths separately in logging and in user messaging so you can tell a configuration gap from a checkout problem.

Keep the front end flexible, the back end central

Running a custom paywall alongside a dashboard-managed paywall gives you room for experiments and targeted offers. The subscription platform handles product fetching and purchase management; your team handles the custom UI. The result is a hybrid where presentation stays under your control and the subscription infrastructure stays consistent across iOS and Android.

Frequently asked questions

Can I show a custom paywall and a dashboard-managed paywall in the same app?

Yes. The app decides which UI to show, while all purchases still flow through the subscription SDK. That keeps product data, purchases and entitlements in one place.

What happens if Offering metadata is missing?

Metadata is optional, so every read should have a default. If the custom_paywall flag is absent, fall back to the dashboard-managed paywall rather than failing.

Do I need a new app release to change the dashboard-managed paywall?

No. Dashboard-managed paywalls are created, managed and tested in the dashboard, so changes do not require a new store release.

How do I target different paywalls to different moments in the journey?

Use Placements such as onboarding_end, feature_gate or sale_offer, and fetch Offerings by Placement so the platform returns the right Offering for that customer at that point.

{
  "custom_paywall": true,
}