> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.bannerify.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Modifications

> Learn how to change text, images, colors, and data in a template each time you generate a file.

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:

```json theme={null}
{
  "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](/docs/api-reference/endpoint/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`](/docs/api-reference/errors/code/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`.

```json theme={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.

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

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](/docs/essentials/signed-urls) |
| `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.

```json theme={null}
{
  "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`](/docs/api-reference/errors/code/BAD_REQUEST). The message names the path of the field, for example `modifications[0].text`.

The [Modification schema](/docs/api-reference/modification) lists every field with its type.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.