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, one row per placement.

Element	Behavior
Placement ID	The identifier used in your app code. The only column shown.
Search	Use Search by placement ID at the top to filter the list by ID.
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.
⋯ menu	Opens a single action: Delete. There is no edit or rename action on a placement row.

📘
The Placement ID is fixed after creation
A placement's row offers only Delete — there is no rename. 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, choose how to supply the paywall for the All users (default) targeting (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 Search by placement ID 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 ⋯ menu on the placement row.
Click Delete (red).
Confirm.

Deleting is actually an archive (soft-delete). It's not blocked by active targetings or by app-code references — the only block is if the placement is used in an integration filter. On archive, the placement is soft-deleted and all per-targeting paywall overrides for it (App::Scheme::Item entries) are hard-deleted across every scheme, including the Default scheme. There's no warning beyond the integration-filter block, and these override mappings 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 row's only action is Delete. The Placement ID is fixed at creation. 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.

Can I create a placement without leaving the targeting flow?

Yes. The targeting Configure view has a + Add placement action that creates a placement app-wide. See Targetings → Add a new placement from the targeting flow.

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 (App::Scheme::Item) is removed across all targetings, including the Default scheme. Deletion isn't blocked by targetings or app code — only by integration filters that reference the placement.