Merging Data

Shotstack makes it easy to build reusable templates with merge fields. Similar to what you would expect with a mail merge application or template language.

Shotstack edits are described using JSON to create a template. Within the JSON you can use placeholders with double braces, like this: {{ FIRST_NAME }}.

The merge parameter provides an array of key/value pairs that can be used to find and replace the placeholder value.

Setting up the template

First of all, prepare the template with a placeholder. The JSON edit below will generate a 5 second video with a text title. A placeholder will be replaced when the video is rendered:

{
    "timeline": {
        "tracks": [
            {
                "clips": [
                    {
                        "asset": {
                            "type": "text",
                            "text": "Hello {{ NAME }}",
                            "font": {
                                "size": 32,
                                "align": "center",
                                "font": "Montserrat ExtraBold",
                                "color": "#FFFFFF"
                            },
                            "alignment": {
                                "horizontal": "center"
                            }
                        },
                        "start": 0,
                        "length": 5
                    }
                ]
            }
        ]
    },
    "output": {
        "format": "mp4",
        "resolution": "hd"
    }
}

In the JSON above we have added a placeholder {{ NAME }} to the title text parameter. Our JSON is now ready to be used as a template.

Tip

Whitespace between the braces and text is ignored. The placeholder text is case sensitive and we recommend all upper case, snake case variable names, using underscores (_) instead of spaces. At this time the {{ delimiter can not be changed.

Setting up the merge field

To merge data, use the merge parameter with an array of key/value pairs, like this:

"merge": [
    {
        "find": "NAME",
        "replace": "World"
    }
]

Tip

Note that the find parameter value does not include the braces delimiter.

Before posting the JSON to the API, add the merge array so that the final JSON body looks like:

{
    "merge": [
        {
            "find": "NAME",
            "replace": "World"
        }
    ],
    "timeline": {
        "tracks": [
            {
                "clips": [
                    {
                        "asset": {
                            "type": "text",
                            "text": "Hello {{ NAME }}}}",
                            "font": {
                                "size": 32,
                                "align": "center",
                                "font": "Montserrat ExtraBold",
                                "color": "#FFFFFF"
                            },
                            "alignment": {
                                "horizontal": "center"
                            }
                        },
                        "start": 0,
                        "length": 5
                    }
                ]
            }
        ]
    },
    "output": {
        "format": "mp4",
        "resolution": "hd"
    }
}

Checking the merge status

If the render fails or you want to check that the merge was successful, you can pass the query string parameter ?data=true&merge=true in the status request.

The status request would be similar to:

GET https://api.shotstack.io/{{ENV}}/render/{{RENDER_ID}}?data=true&merged=true

Where {{ENV}} is the environment you are using, for example stage or v1. The data parameter returns the edit JSON in the response, and merged merges the data with the edit JSON.

Using multiple placeholders and merge fields

You can use multiple placeholders and merge fields for the following scenarios:

• Multiple placeholders with the same variable, which will be replaced by a single merge field.
• Multiple placeholders with different variables, which will be replaced by multiple merge fields.