Widgets

Create, target, and deliver storefront widgets with predictable lifecycle controls.

Audience: Merchants and integration teams managing on-site UI modules through Selwise.

Critical: Widget delivery to storefront visitors uses the public endpoint /api/v1/public/sites/:siteKey/widgets and returns only active widgets.

Campaigns Experiments Widget Types

Who This Page Is For

Use this page when you need to manage widget inventory for a site, control activation/test mode, apply segment targeting, and validate what is exposed to storefront runtime.

Quick Start (2-5 Minutes)

Create widget

Create a widget with type, site, content, and placement settings.

POST /api/v1/widgets

Configure targeting

Set segment targeting mode and segment IDs when using include/exclude behavior.

{ "segmentTargetingMode": "include", "segmentIds": ["SEGMENT_ID"] }

Activate or pause

Toggle widget state without full update payload.

POST /api/v1/widgets/:id/toggle-status

Duplicate for variants

Duplicate an existing widget for campaign variants or localization.

POST /api/v1/widgets/:id/duplicate

Verify public delivery

Inspect active runtime payload served to client script.

GET /api/v1/public/sites/:siteKey/widgets

Core endpoints

POST   /api/v1/widgets
GET    /api/v1/widgets
GET    /api/v1/widgets/:id
PUT    /api/v1/widgets/:id
POST   /api/v1/widgets/:id/toggle-status
POST   /api/v1/widgets/:id/duplicate
DELETE /api/v1/widgets/:id
GET    /api/v1/public/sites/:siteKey/widgets

Required Fields / Minimum Payload

Field	Required	Type	Used by events	Description
`name`	Required	`string`	Widget create/update	Human-readable widget name used in dashboard and audit logs.
`type`	Required	`WidgetType`	Widget create/update	Must match supported types (announcement_bar, slide_in, cart_count, newsletter, etc.).
`siteId`	Required	`uuid`	Widget create	Site that owns widget inventory and storefront delivery.
`contentJson`	Optional	`object`	Widget rendering	Content block consumed by runtime renderer.
`stylesJson`	Optional	`object`	Widget rendering	Style overrides applied by storefront runtime.
`segmentTargetingMode`	Optional	`all \| include \| exclude`	Audience gating	Controls whether segmentIds are ignored, allowlist, or blocklist.
`segmentIds`	Conditional	`uuid[]`	Audience gating	Required when targeting mode is include or exclude.

Create widget example

{
"name": "Homepage Free Shipping",
"type": "announcement_bar",
"siteId": "SITE_ID",
"contentJson": {
  "text": "Free shipping over $75",
  "buttonText": "Shop now"
},
"stylesJson": {
  "backgroundColor": "#1f6feb",
  "textColor": "#ffffff"
},
"placementConfig": {
  "position": "top"
},
"isTestMode": false,
"segmentTargetingMode": "all"
}

Event or Endpoint Decision Matrix

Scenario	Use This	Why
Create a new widget module	POST /api/v1/widgets	Initial creation with full payload contract.
Temporarily disable or re-enable a live widget	POST /api/v1/widgets/:id/toggle-status	Fast state switch without editing style/content fields.
Reuse an existing widget as a starting point	POST /api/v1/widgets/:id/duplicate	Copies settings and speeds up variant creation.
Fetch active runtime widgets for storefront	GET /api/v1/public/sites/:siteKey/widgets	Public payload returns active/test-eligible widgets only.
Track real-time product badges	GET /api/v1/public/sites/:siteKey/product-metrics/view-count and /cart-count	Used by product_view_count and cart_count widget types.
Capture tenant newsletter signups in widget runtime	POST /api/v1/public/sites/:siteKey/newsletter	Newsletter widget submits directly to tenant-scoped audience capture flow.

Newsletter widgets are tenant-scoped audience sources, separate from admin/global newsletter domain.

Runtime behavior:

Submit endpoint: POST /api/v1/public/sites/:siteKey/newsletter
Legacy confirm endpoints (backward compatibility): POST /api/v1/public/sites/:siteKey/newsletter/confirm and GET /api/v1/public/sites/:siteKey/newsletter/confirm?token=...
Payload metadata includes visitorId, siteUserId, sourcePath, referrer, and locale.
Browser widget flow writes subscribers directly to tenant EmailRecipient audience pool and does not use admin/global newsletter sender configuration.
API-only clients can bypass widget usage with POST /api/v1/public/sites/:siteKey/newsletter/api/subscribe and x-selwise-api-key.

Common Errors and Fixes

Widget appears in dashboard but not storefront

Cause: Widget inactive, site not verified, or segment targeting excludes visitor.

Fix: Check isActive state, site verification, and segmentTargetingMode/segmentIds.

Validation error on create/update

Cause: Invalid UUID values for siteId or segmentIds.

Fix: Use canonical UUID format for all IDs.

Test widget visible for all users

Cause: isTestMode disabled or storefront test gating not configured as expected.

Fix: Set isTestMode true and verify the storefront test flag workflow.

Count widgets render zero values

Cause: Product metrics endpoint not receiving matching product identifiers, or storefront DOM does not expose `[data-product-id]` for auto-detection.

Fix: Verify product item code mapping in view/cart events, and expose `[data-product-id="<productItemCode>"]` on the PDP container (or set contentJson.productId explicitly).

Production Checklist

All widgets have explicit ownership by siteId.Required
Live widgets are active and old variants are paused or deleted.Required
Segment targeting rules are validated against real segment population.Required
Public /widgets payload tested on production domain origin.Required
PDP DOM exposes `[data-product-id]` for count widgets, or contentJson.productId is set.Required
Count widgets validated against product metrics endpoints.Required