Personalize videos using merge fields

One of the many use cases for the Shotstack API is personalized video marketing. By combining high volume video generation with data, you can create thousands of personalized videos.

In one of our own marketing initiatives we achieved a 50% open rates and 30% CTRs.

Personalized content can perform 202% better than generic content. The case for personalization across all types of media is clear.

How to create a personalized video

There are a few different ways how to do personal video marketing. Most common, is to hire an agency that specializes in personalized video production. These agencies will work with you from start to finish.

They define a brief, scripts, storyboards and design a custom video template in After Effects. The manage your data sources and hook it all up to their proprietary rendering platform. Project managers, producers, motion graphics designers and developers get involved.

Of course all this comes with a price. Many personalized video marketing activations cost hundreds of thousands of dollars.

The other alternative is to build your own application and workflow. You can do this with command line tools and libraries such as FFmpeg or Dataclay. Building your own video system is complex and time consuming.

How Shotstack does video personalization

At Shotstack we take a different approach. Our white label, public API lets you create your own video personalization workflow, the way you want. Create your own templates or hire a designer. Define your own personalization fields and bring your own data source. You can integrate our API using the programming language of your choice.

Shotstack only charges for the volume of videos you create, with subscriptions starting from $49. Everything else from design, motion graphics and integration is up to you. We even have off the shelf templates and integrations with Integromat and Zapier.

Personalizing videos with merge fields

Shotstack merge fields are designed to work the same way as email or document mail merge fields. For developers, they work like template frameworks such as React, Angular or Vue. Using curly braces you can create placeholders in a video template that get replaced during rendering. A placeholder in a video will look like {{PLACEHOLDER}}.

Using merge fields makes it easy to insert dynamic data into your video templates. Add placeholders to your template. Collate your dynamic data and use the merge fields to perform a find and replace of the placeholders. The alternative is managing and replacing variables inside your workflow or application.

Adding placeholders to a template

The first step is to add the placeholders to your video template. For this example we'll use one of our Christmas templates that we used in this personalized Christmas demo.

Below is a segment of the JSON from the template. It has a placeholder for {{FIRST_NAME}}, which will display with the text Merry Christmas.

"asset": {
"type": "html",
"html": "<p>MERRY CHRISTMAS</p>",
"css": "p { font-family: \"Montserrat\"; color: #ffffff; font-size: 14px; text-align: center; font-weight: bold }",
"width": 450,
"height": 30
"start": 3.8,
"length": 3.4
"asset": {
"type": "html",
"html": "<p>{{FIRST_NAME}}</p>",
"css": "p { font-family: \"Amatic SC\"; color: #ffffff; font-size: 64px; text-align: center; font-weight: bold; }",
"width": 450,
"height": 100
"start": 4,
"length": 2.8

Find and replace the placeholder using merge fields

The merge property contains an array of merge parameters, added to the root of the JSON template.

Each element in the merge array is an object containing a find and replace property. find is the placeholder to search for, and replace is the value to merge.

The JSON below shows how we will set up the merge fields for our Christmas video. Notice that the find value excludes the curly braces:

"merge": [
"find": "FIRST_NAME",
"replace": "RALPH"
"timeline": {

Our personalized Christmas video

The final output video is below, specially personalized to RALPH:

Create personalized videos using PHP, Node and Ruby SDK's

It is possible to use the same technique to personalize videos using the Shotstack SDK. The Shotstack video editing SDK is available in PHP, Ruby and Node.js.

Below is a section of code showing how you would prepare a text asset, with a placeholder, using PHP:

$titleAsset = new TitleAsset();
->setText('Hello {{NAME}}');

And the merge field, to replace NAME with Jane:

$mergeField = new MergeField();

$edit = new Edit();

You can see the full example on our GitHub PHP demos repo, as well as examples for Node.js and Ruby.

Creating personalized video from a data source

Merge fields allows you to personalize your videos using your own dynamic data.

Using our SDK, or any language that can interact with a RESTful API opens up the possibility to connect data. Connecting to a database or form is a trivial job for any programming language. Now with Shotstack you can take that data and with a few lines of code personalize thousands of videos.

Take a look through the merging data documentation for an in-depth overview.

Derk Zomer

3rd December, 2021

Become an Automated Video Editing Pro

Every month we share articles like this one to keep you up to speed with automated video editing.

Related articles

How to generate videos using Integromat

How to generate videos using Integromat

Use Integromat in your video editing workflow to automatically generate videos.

Derk Zomer
How I built 1,000 personalised videos in 60 seconds

How I built 1,000 personalised videos in 60 seconds

How to automatically generate thousands of personalised videos from a spreadsheet using Node.js.

Derk Zomer
Merge fields, probe endpoint, transformations and other updates

Merge fields, probe endpoint, transformations and other updates

A summary of the latest features available now in our docs, SDK's and GitHub.

Jeff Shillitto