Placements

Author and manage named slots — like hero_banner, sidebar_widget, checkout_upsell — that creatives target inside each channel.

See also: Placements REST API reference for request/response shapes, status codes, and error semantics.

A Placement is a named slot inside a Channel where a recommendation can appear — for example hero_banner on a web channel, checkout_upsell on an in-app channel, or welcome_email_top on an email channel. Creatives target a specific placement, and the decision engine allocates one creative per requested placement at decision time.

Placements give you fine-grained control over where content lands on a surface without needing to invent a separate channel for each slot.

---

The Placements page

Path: /studio/placements

The studio page is a standard two-panel layout:

• Left: list of all placements in the tenant with name, channel, key, status, and last-update timestamp.
• Right: detail form for the selected row, or a blank create form when + New Placement is clicked.

Fields

Field	Required	Description
Channel	Yes	The parent channel this placement belongs to. A placement is scoped to exactly one channel.
Name	Yes	Human-readable label shown in the studio (e.g. “Hero Banner”).
Key	Yes	Machine-readable identifier used in the Recommend API (e.g. hero_banner). Lowercase + underscores recommended; must be unique within the parent channel.
Description	No	Free-text note describing where the placement appears and what it’s for.
Status	No	active (default) or inactive. Inactive placements are excluded from candidate matching.

Creating a placement

1. Open /studio/placements.
2. Click + New Placement.
3. Pick a channel, give it a name + key, and click Save.
4. Linked creatives can now target this placement via their placementKey field.

Editing a placement

Click any row in the list. The right pane switches to edit mode with the current values pre-filled. Click Save to apply, or Delete to soft-delete the placement (associated creatives are not deleted but will no longer match decisions for the removed placement key).

---

How placements are used at decision time

When the Recommend API request specifies a placement (via the placements array), the decision engine narrows the candidate set to creatives whose placementKey matches. If no placement is specified, every active placement within the requested channel is eligible.

See Channels — How channels work for the full delivery pipeline.

---

API

All operations are available via the REST API as well — see api-reference/placements for request/response details and role requirements.