Shopper App API overview

Quick answer

The Shopper App API at https://share.plunk.io runs Plunk’s consumer-facing visualizer apps. Use the one-line website embed, or call the same endpoints from your own shopper experience. Every request carries a Visualizer App key in the x-visualizer-key header.

Before you start

• The Shopper App API is included with Studio Storefront and Plunk Commerce. See which plans include the API.
• Shopper renders spend your workspace’s credits. Shoppers never see credits, and cached results are free.

Keys and authentication

Keys are created in Studio under Visualizer Apps: choose + New app, pick where it runs and which surfaces it can drive, then Create app key. The raw key is shown once, at creation. There is no shopper login: the key is the app’s identity.

Key type	Prefix	Where it runs	What the API enforces
Device	kk_	In-store displays and showroom tablets you manage	No origin check and no daily cap by default. The device itself is the security boundary.
Site	sk_	Your public website, visible by design	Locked to the domains registered on the key, a daily render cap, per-IP burst limiting, and optional capture-first (an email is required before a render is spent).

Caution

A visualizer site key starts with sk_ but is a different key from a Customer API secret key. It is made to sit in your web page and only opens the visualizer apps it is scoped to, from your domains. Never put a Customer API sk_live_ key in a web page.

Surfaces

Each key is scoped to one or more surfaces:

Surface	App
com	COM/COL Visualizer
sectional	Sectional Builder
roomplanner	Room Planner

Your app declares which surface it is with the x-surface header (or ?surface=). Requests outside the key’s scope are refused with 403.

The API at a glance

Area	Endpoints	Page
Website embed	embed.js, GET /embed	Website embed
App config	GET /visualizer/config	App config
Visualizer renders	POST /visualizer/render, GET /visualizer/render/{runId}	Visualizer renders
Lead capture	POST /visualizer/capture, POST /visualizer/swatch-lead	Lead capture
COM/COL requests	/visualizer/comcol/…	COM/COL requests
Sectional Builder	/sb/bootstrap, /sb/render, /sb/save	Sectional Builder
Room Planner	/visualizer/roomplanner/…	Room Planner
Webhooks	comcol.request.*	Webhooks

Tip

Want a custom shopper app? Plunk also designs and builds custom visualizer, sectional-builder and room-planning apps on these same APIs. Ask through support.

Related

• Website embed
• Customer API