Widget events

Use widget events to update storefront status, save cart metadata, and show recovery actions.

Current events

The production widget emits these events today:

Event	When to use it
`stackfill:shown`	Modal is opening.
`stackfill:loaded`	Session and form loaded.
`stackfill:saved`	Personalization saved and a `fill.id` is available.
`stackfill:closed`	Shopper closed the modal.
`stackfill:error`	The widget or session failed.

Save handler

window.addEventListener("stackfill:saved", (event) => {
  const payload = event.detail;
  orderDraft.stackfill_fill_id = payload.fill.id;
  orderDraft.stackfill_template_id = payload.fill.template_id;
});

Common errors

Always listen for stackfill:error. Show a retry option and include product/variant context in logs.

Planned lifecycle events such as stackfill:field_changed, stackfill:render_queued, and stackfill:render_succeeded are not emitted by the current production widget yet.

See Embed widget.