Modifications

A template is a design with named layers. A modification changes one of those layers for a single render, so one template can produce a different file for each product, customer, or post. The template does not change, and a layer without a modification keeps the values you set in the editor.

You send modifications with every request that generates a file:

{
  "apiKey": "YOUR_API_KEY",
  "templateId": "tpl_xxx",
  "modifications": [
    { "name": "headline", "text": "Summer sale" },
    { "name": "photo", "src": "https://example.com/shoes.png" },
    { "name": "badge", "visible": false }
  ]
}

Name your layers

name has to match a layer name in the template. The match is exact, so Headline and headline are two different names.

To rename a layer, double-click it in the layers panel of the editor. To list the layer names of a template over the API, call Template list with includeLayers=true.

Two rules help when a value does not change:

• If no layer has the name, Bannerify ignores the modification and returns no error. Check the spelling first.
• If several layers share a name, they all get the same modification.

Fields

Field	Type	What it changes
name	string	The layer to change. Required
text	string	The text of a text layer, the body of an alert, or the signer name of a signature
color	string	The text color of a text layer, for example #ff5733
src	string	The image URL of an image layer
visible	boolean	Shows or hides any layer
qrcode	string	The content of a QR code layer
barcode	string	The value of a barcode layer
star	number	The rating of a star layer. A value of 0 is ignored
rows	array	The data of a table, chart, or key value layer
columns	array	The columns of a table layer
title	string	The heading of an alert, or the job title of a signature
date	string	The date of a signature

Bannerify ignores a field that does not fit the layer. For example, src on a text layer does nothing, and color changes text layers only. It also ignores fields it does not know.

What each layer reads

Layer	Fields
Text	text, color, visible
Image	src, visible
QR code	qrcode, visible
Barcode	barcode, visible
Star	star, visible
Table	rows, columns, visible
Chart	rows, visible
Key value	rows, visible
Signature	text, title, date, visible
Alert	title, text, visible
Icon, frame, line	visible

A modification cannot change the canvas, a layer’s position or size, or a fill color. Change those in the editor.

Text

The new text replaces the whole text of the layer. A new line starts a new paragraph. The layer keeps its own style, such as font and size, but formatting inside the text, such as one bold word, is lost.

Images

src must be a public URL of a PNG, JPEG, WebP, or SVG file. Bannerify downloads the file while it renders. A download waits up to 5 seconds and retries twice. If the download fails, or the file is another type, the request fails with FETCH_IMAGE_ERROR.

Tables

A table takes columns and rows. Each row is an object keyed by column name. A cell holds a string, a number, a boolean, or null.

{
  "name": "line-items",
  "columns": ["Item", "Qty", "Total"],
  "rows": [
    { "Item": "Pro plan", "Qty": 1, "Total": "$29.00" },
    { "Item": "Extra seat", "Qty": 2, "Total": "$10.00" }
  ]
}

A column is a name, or an object with these fields:

Field	Type	Description
key	string	The key that rows use for this column
header	string	The text in the header cell
align	left, center, or right	The cell alignment
width	string or number	The column width

If you send rows without columns, the table keeps the columns from the template, and each row needs the keys of those columns.

Charts

A chart takes rows. Send points for one series, or series for several.

{
  "name": "revenue",
  "rows": [
    { "label": "Jan", "value": 22 },
    { "label": "Feb", "value": 31, "color": "#0d9373" }
  ]
}

{
  "name": "revenue",
  "rows": [
    { "name": "2025", "data": [{ "label": "Jan", "value": 22 }, { "label": "Feb", "value": 31 }] },
    { "name": "2026", "data": [{ "label": "Jan", "value": 27 }, { "label": "Feb", "value": 35 }] }
  ]
}

A point has a label, a numeric value, and an optional color. A series has a name, its data points, and an optional color.

Key value

A key value layer takes rows with one entry for each line. value can be a string or a number, and Bannerify shows it as text.

{
  "name": "order-details",
  "rows": [
    { "key": "Order", "value": "1042" },
    { "key": "Total", "value": 29 }
  ]
}

Accepted formats

The modifications field accepts four shapes, and all of them produce the same file.

Shape	Use it for
An array of modifications	The format the SDKs send. This page uses it
An object with one key for each layer	No-code tools and quick requests
A JSON string of either shape	Query strings, such as a signed URL
null or an empty string	No modifications

In the object shape, a key names a layer. A string or number value sets text, and an object value keeps its own fields.

{
  "modifications": {
    "headline": "Summer sale",
    "photo": { "src": "https://example.com/shoes.png" },
    "badge": { "visible": false }
  }
}

A boolean needs an object. "badge": false sets the text of the layer to false, and "badge": { "visible": false } hides it.

Check a request

An invalid modification returns BAD_REQUEST. The message names the path of the field, for example modifications[0].text.

The Modification schema lists every field with its type.