Placements

A placement is a named slot in your app's user journey — for example onboarding, main, or settings — where a paywall is shown. Your app references the placement by its Placement ID; Apphud decides which paywall renders there based on the user's matching targeting. Placements live in Mission Control → Placements.

A placement does not hold audience logic or a list of paywalls. It is just the slot. Which paywall a user sees in that slot is resolved by targetings — see How targetings work.

Every placement carries one fallback paywall: the paywall shown to the All users (default) targeting. You set this when you create the placement. Audience-specific paywalls for the same slot are configured later in Targetings by overriding the fallback paywall if needed.

The Placements list

The Placements tab lists every placement in the app as a table with two columns.

Element	Behavior
Placement ID	The identifier used in your app code.
Default paywall	The paywall the Default targeting assigns to the placement; "-" if it assigns none.
Search	The search box at the top filters the list.
Sort order	Placements are listed by creation date, oldest first — a new placement is added at the bottom. The order is fixed and cannot be changed.
Pencil and trash icons	Pencil — opens the Default targeting, where you change the placement's default paywall; the Placement ID itself can't be edited. Trash — Delete the placement. Both are disabled if you don't have edit access to Mission Control.

📘
The Placement ID is fixed after creation
A placement has no rename: the pencil opens the Default targeting. The Placement ID your app uses is set once, at creation, and cannot be changed afterward.
To change which paywall the slot shows by default, edit the Default targeting in Targetings rather than the placement itself.

Create a placement

Click + New placement to open the Placements & paywalls form. A placement requires two things: a Placement ID and a fallback paywall.

Enter the Placement ID — the identifier your app uses to request this slot. Required.
Under Assign a fallback paywall, select an existing paywall or create a new one (required — see below).
Click Create placement.

Assign a fallback paywall

The fallback paywall is the paywall shown to the All users (default) targeting for this placement. Every placement must have one — it is the slot's baseline before any audience override. Two modes:

Use existing paywall — pick a paywall already created in Mission Control → Paywalls from the Paywall ID dropdown. The preview shows its screen, products, macros, and custom JSON.

After selecting one, a "Want to tweak this paywall?" panel appears with an Edit paywall button. Clicking it lets you edit the paywall inline, with two save options:

Apply changes — updates the existing paywall itself. The change propagates to every targeting and placement that uses this paywall, not just this one, and cannot be reverted.
Save as new — creates a copy with your edits and assigns the copy to this placement's fallback. The original paywall stays unchanged.

Create new paywall — build a brand-new paywall inline (screen, product bundles, macros, custom JSON). It is added to the global Paywalls list and is reusable like any other paywall.

❗️
Apply changes affects every targeting that uses the paywall
When you edit a fallback paywall with Apply changes, the change is global — every targeting and placement using that paywall is affected, and it cannot be reverted.
If you only want the change for this placement, use Save as new instead. This is the same inline-edit behavior used in the targeting flow — see Editing a paywall in context on the Paywalls page for full details.

The Create placement button stays disabled while you are mid-edit on a paywall — apply, save as new, or cancel the edit first.

Find a placement

Use the search box at the top of the tab to filter the list. The list cannot be re-sorted; it always shows placements oldest-first by creation date.

Delete a placement

In Mission Control → Placements, click the trash icon on the placement row.
Confirm.

Deleting is actually an archive (soft-delete). It's not blocked by active targetings or by app-code references — the only blocks are an integration filter that uses the placement, and a Running or Testing A/B test that tests it (you'll see "Cannot archive placement. A live A/B test uses it."). On archive, the placement is soft-deleted and all per-targeting paywall overrides for it are permanently removed across every targeting, including Default. There's no warning beyond these blocks, and removed overrides can't be recovered — be sure you want it gone.

Change a placement's paywall after creation

You set the fallback paywall once, at creation. To change it later, you do not edit the placement — you edit the Default targeting:

Open Mission Control → Targetings.
Open the Default (All users) targeting.
Find the placement row and Configure it with a different paywall.

To show a different paywall to a specific audience in this slot, override the placement inside a custom targeting instead. See Targetings → Placements & paywalls.

Where placements are used

Referenced by Placement ID in your app code to request a paywall for that slot.
Overridden per audience in Targetings — each (targeting, placement) pair resolves to exactly one paywall.
Targeted by A/B tests — a single test can vary paywalls across multiple placements at once.

📘
Defer placements
If you need to set user properties first (e.g. for audience segmentation), call Apphud.deferPlacements() right after Apphud.start() — this delays the fetch until you explicitly call Apphud.fetchPlacements(), ensuring targeting is evaluated with the correct user data already in place.

FAQ

❓Does a placement decide which paywall a user sees?

No. A placement is just the slot. The paywall is chosen by targetings: the highest-priority targeting whose audience matches the user supplies the paywall for that placement, falling back to the Default targeting's paywall. See How targetings work.

❓Why must I assign a fallback paywall when creating a placement?

The fallback paywall is the placement's paywall in the All users (default) targeting — the baseline shown to anyone who doesn't match a custom targeting. A placement with no paywall would have nothing to show, so it is required at creation.

❓Can I rename or change a Placement ID after creating it?

No. The Placement ID is fixed at creation; the pencil icon opens the Default targeting, not a rename. If you need a different ID, create a new placement and delete the old one.

❓Can I reorder the placements list?

No. Placements are always listed by creation date, oldest first, and new placements appear at the bottom. The order cannot be changed.

❓What's the difference between Apply changes and Save as new when editing the fallback paywall?

Apply changes edits the existing paywall globally — every targeting and placement using it is affected, and it can't be reverted.
Save as new makes a copy with your edits and assigns the copy here only; the original is untouched.

See Editing a paywall in context.

❓What happens to targetings when I delete a placement?

Every per-targeting paywall override for that placement is permanently removed across all targetings, including Default. Deletion isn't blocked by targetings or app code — only by integration filters that reference the placement, and by a Running or Testing A/B test that tests it.