Room Planner

Before you start

The Room Planner is off until your team turns it on in Studio.
Renders come out of a monthly allowance your team sets. Saving and sending always work, even when the allowance is used.

GET /visualizer/roomplanner/bootstrap

Your brand and the published products with real sizes and, where ready, a top-down view for the floor plan. canRender says whether a render is available right now. Prices are never included.

{
  "brand": "Sample Furniture Co.",
  "storeName": "Main Street Showroom",
  "tenantId": "a123456789012",
  "keyType": "site",
  "preview": false,
  "canRender": true,
  "products": [
    {
      "sku": "SF-1042",
      "name": "Harbor Sofa",
      "imageUrl": "https://…/sf-1042.png",
      "category": "Sofas",
      "widthIn": 88, "depthIn": 38, "heightIn": 34,
      "topViewUrl": "https://…/sf-1042-top.png"
    }
  ]
}

POST /visualizer/roomplanner/render

Field	Type	Notes
`operation`	string	`add_items` (default), `clear_room` or `generate_empty_room`
`roomImageUrl`	string	The room photo. Required except for `generate_empty_room`
`referenceItems[]`	array	Up to 30 products: `{ url, role, name, productType, description, widthInches, depthInches, heightInches }`
`roomWidthFt` · `roomDepthFt` · `roomHeightFt`	number	Room size, for true scale
`prompt`	string	Where things go, in plain words
`aspectRatio`	string	Default `16:9`

{ "renderId": "3f0c9a…", "status": "processing" }

Status	Code	When
`403`	`not_enabled`	The Room Planner is turned off for your account
`429`	`rate_limited`	Per-IP burst limit
`429`	`daily_cap_reached`	The key’s daily render cap is spent
`429`	`allowance_reached`	This month’s render allowance is used. Saving and sending still work.

GET /visualizer/roomplanner/render/{renderId}

Poll until status is completed (with renderUrl) or failed (with error).

POST /visualizer/roomplanner/save

Saves the room as a lead: { name, email, consent: true, phone?, plan }. Returns { planId, saveToken }. Keep both, and send them back with later saves to update the same room. Consent is required.

POST /visualizer/roomplanner/send

Sends a saved room to your sales team: { planId, saveToken, message? }. Returns { "ok": true }.

Was this helpful?

Still stuck? Contact support and include the job or page you were on.