> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# Placements

Plan: Stencil Developer

Lesson 19 of 23 · 30 min

Placements determine the Region where the widget is placed and in what order.

Currently, placements can exist on the following pages:

```text showLineNumbers={false}
pages/account/add-address
pages/account/add-return
pages/account/add-wishlist
pages/account/addresses
pages/account/download-item
pages/account/edit
pages/account/inbox
pages/account/orders/all
pages/account/orders/completed
pages/account/orders/details
pages/account/orders/invoice
pages/account/recent-items
pages/account/return-saved
pages/account/returns
pages/account/wishlist-details
pages/account/wishlists
pages/auth/account-created
pages/auth/create-account
pages/auth/forgot-password
pages/auth/login
pages/auth/new-password
pages/blog
pages/blog-post
pages/brand
pages/brands
pages/cart
pages/category
pages/compare
pages/contact-us
pages/errors/403
pages/errors/404
pages/errors/generic
pages/gift-certificate/balance
pages/gift-certificate/purchase
pages/gift-certificate/redeem
pages/home
pages/order-confirmation
pages/page
pages/product
pages/search
pages/sitemap
pages/subscribed
pages/unavailable/hibernation
pages/unavailable/maintenance
pages/unsubscribe
```

It is also possible to place widgets on the following custom templates, where \<filename> is the name of the custom template file:

```text showLineNumbers={false}
pages/custom/product/<filename>
pages/custom/brand/<filename>
pages/custom/category/<filename>
pages/custom/page/<filename>
```

> **Info**
>
> * To display a widget on the storefront, you must create a placement.
> * A region can contain multiple placements with widgets.

## Placements sort_order

When creating a placement with a widget, the widget content takes the full region width. The placement's `sort_order` property controls the display order of the widget. You would stack any additional widgets in the same region above or below based on each placement's `sort_order` property.

> **Info**
>
> If you are creating marketplace applications that create placements directly, you do not need to use the `sort_order` property.

## entity_id

When creating a placement, there is an option to provide an `entity_id`. The `entity_id` is the identifier for a specific product, brand, category, or page. For example, if a widget needs to be on all product pages, leave `entity_id` blank. If the widget should only appear on a certain product page, assign the product ID to `entity_id`.

You can use entity_id with the following page types:

* pages/brand
* pages/category
* pages/page
* pages/product

## Create a Widget Placement with Region

Placements tell the Widgets API which page and region a widget should be assigned to. A placement can also define a sort order, which determines the order to display multiple widgets within a single region.

Below, the region and sort order have a value, so the widget will appear on the home page.

```json showLineNumbers={false}
{
    "widget_uuid": "2dfeb50e-5f8c-4df2-8525-a338091eed32",
    "entity_id": "14",
    "sort_order": 1,
    "region": "home_header_image",
    "template_file": "pages/home",
    "status": "active"
}
```

## Create a Widget Placement without a Region

You may wish to determine a widget's positioning not just by region, but also in relation to other widgets. In that case, you can create a widget placement without specifying a region and then include the widget placement within a layout.

Leaving the region and sort order off of the request will return just the placement_id in the response, allowing for the widget to be rendered using Layouts.

```json showLineNumbers={false}
{
    "widget_uuid": "2dfeb50e-5f8c-4df2-8525-a338091eed32",
    "entity_id": "14",
    "template_file": "pages/home",
    "status": "active"
}
```

## Widgets on the Storefront

Regions are output on the storefront with a data attribute, like this:

```html showLineNumbers={false}
<div data-content-region="home_below_carousel">
    ...
</div>
```

When widget placements are rendered within a region, the template contents are wrapped in a container with data attributes containing the widget's ID and placement's ID, like this:

```jsx showLineNumbers={false}
<div data-widget-id="{widget ID}" data-placement-id="{placement ID}" data-placement-status="ACTIVE">
    ...
</div>
```

A region can contain multiple widget placements.

> **Info**
>
> Placements determine the region where you place widgets and in what order. There is a limit of 75 placements per template file and 10,000 total placements per store.

For the endpoints used to create, retrieve, update, and delete placements, see the [Widgets API reference](/developer/api-reference/rest/admin/content/widgets).