> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.templated.io/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Passing Data to the Embedded Editor

You can open the Templated embedded editor with your user's data already in the template (name, photo, logo, colors), and attach your own IDs so they come back in your webhook.

## Prefill layers with the `layers` parameter

`layers` is a base64-encoded JSON object. The keys are layer names (exactly as in the layers panel) and the values are the same layer properties as in the API (`text`, `color`, `image_url`, `fill`, `hide`...).

### Step 1: Build the data

```js
const layerData = {
  "title": { "text": "Welcome, José!" },
  "subtitle": { "text": "Your personalized design" },
  "logo": { "image_url": "https://example.com/user-logo.png" },
  "background-shape": { "fill": "#0066CC" }
};
```

### Step 2: Encode it (UTF-8 safe)

```js
const encoded = btoa(unescape(encodeURIComponent(JSON.stringify(layerData))));
```

Do not use only `btoa(JSON.stringify(layerData))`. It fails when the text has accents, emojis or non-Latin characters (for example "José", Arabic or Chinese).

### Step 3: Add it to the embed URL

```js
const url = `https://app.templated.io/editor/TEMPLATE_ID?embed=EMBED_ID&layers=${encodeURIComponent(encoded)}`;
```

### Python

```python
import json, base64, urllib.parse

layer_data = {
    "title": {"text": "Hello"},
    "photo": {"image_url": "https://example.com/photo.jpg"}
}
encoded = base64.b64encode(json.dumps(layer_data).encode("utf-8")).decode("utf-8")
url = f"https://app.templated.io/editor/TEMPLATE_ID?embed=EMBED_ID&layers={urllib.parse.quote(encoded)}"
```

### Multi-page templates

Send the same structure as the API `pages` array:

```json
{
  "pages": [
    { "page": "page-1", "layers": { "title": { "text": "Cover" } } },
    { "page": "page-2", "layers": { "title": { "text": "Details" } } }
  ]
}
```

A page with `"hide": true` is removed from the editor.

### Tips

- Layer names must match exactly (uppercase and lowercase, hyphens and underscores). A name that does not match is ignored without an error.
- Images must be public direct links.
- Very long data makes very long URLs. For large data, load the template first and send the values with the `UPDATE_LAYERS` message (below).
- Combine with `&clone=true` so the prefilled design is saved as a clone and your original template stays unchanged.

## Update layers after the editor loads

Send an `UPDATE_LAYERS` message to the iframe after the `EDITOR_READY` event:

```js
iframe.contentWindow.postMessage({
  type: 'UPDATE_LAYERS',
  data: { 'title': { text: 'New title', color: '#FF0000' } }
}, '*');
```

See "Embedded Editor Events" for all messages.

## Send your own data to webhooks with `metadata`

`metadata` is also base64-encoded JSON. Use it for your own IDs, for example user ID or order ID:

```js
const metadata = { userId: "user-123", orderId: "order-456" };
const encodedMetadata = btoa(unescape(encodeURIComponent(JSON.stringify(metadata))));
const url = `https://app.templated.io/editor/TEMPLATE_ID?embed=EMBED_ID&metadata=${encodeURIComponent(encodedMetadata)}`;
```

The metadata is included in the `create`, `save` and `download` webhook calls and frontend events, so you can match each template or render to the right record in your system. It is not shown to the user and does not change the design. Keep metadata to simple IDs (letters, numbers, hyphens); accented or non-Latin text in metadata may come back garbled.

## Common use cases

- Personalization: prefill the user's name, photo and company logo.
- Product customization: load the product image and price.
- Orders: pass the order ID in `metadata` and receive it back with the render URL on download.

Docs: https://templated.io/docs/embed/advanced/ and https://templated.io/docs/embed/url-parameters/

## FAQ

Q: How do I prefill the embedded editor with my user's data?
A: Add the `layers` parameter with base64-encoded JSON of layer names and values.

Q: My prefilled text with accents does not appear or the editor shows an error. Why?
A: Encode the JSON as UTF-8 before base64: `btoa(unescape(encodeURIComponent(JSON.stringify(data))))`.

Q: Some layers are not prefilled. Why?
A: The layer names in your JSON do not match the template exactly. Copy them from the layers panel.

Q: Can I change layer values without reloading the editor?
A: Yes. Send an `UPDATE_LAYERS` message to the iframe.

Q: How do I know which of my users created a template?
A: Pass your user ID in `metadata` (or use `external-id`). It comes back in the webhook and frontend events.