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

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)

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

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

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:

{
  "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:

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:

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.

Updated on: 01/10/2026