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": "Automate 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.

Get Started

Essentials

Integrations

MCP

CLI

Account

Name your layers

Fields

What each layer reads

Text

Images

Tables

Charts

Key value

Accepted formats

Check a request

​Name your layers

​Fields

​What each layer reads

​Text

​Images

​Tables

​Charts

​Key value

​Accepted formats

​Check a request

Name your layers

Fields

What each layer reads

Text

Images

Tables

Charts

Key value

Accepted formats

Check a request