API V1 to V2 migration

In version 1 of our API every template contains one single page. In other words: in version 1 you need 2 templates to create a single order. We felt the need to improve this and in order to do that, we have developed a new version of the API.

In our new version of the API (v2), a template contains multiple pages. Therefore, only one template is required to create an order.

Because of the change in structure, it is not possible to use v1 templates on our v2 API and vice-versa. We have developed a simple solution to migrate your v1 templates to v2 templates. This page will guide you in the migration steps.

Please note: we will keep version 1 of the API running until March 1, 2024. There is no need to hurry. If you need support, please contact us.

Step 1 - Migrate design template

The first step to migrating to our new version is updating your templates. To make this easier, you can find a migration wizard in our portal. In this wizard, you need to select a front and back template, after which you will be able to combine these two pages into one single template (see reference image below):

After you have selected the two pages, you can choose to delete the old versions or keep them. Please note: it is recommended to keep the old templates if you are currently using them in your integration. When you are not sending live orders yet - it should be safe to delete your old templates.

Step 2 - Updating your integration

Our integrations

When you are using one of our integrations you can start using the new version when it rolls out.

Custom integrations

To update your integration from v1 to v2 you will need to update your API calls. The following JSON represents the data you are sending right now to our API.

Example JSON body v1

1{
2  "sender": { ... },
3  "recipient": { ... },
4  "mergeVariables": { ... },
5  "pages": {
6    "1": "tmpl_12345678900987654321",
7    "2": "tmpl_09876543211234567890"
8  },
9  "format": "POSTCARD_A5",
10  "billingId": "..."
11}

In the below JSON example, you can see the parts of the JSON that have changed since our new version.

Example JSON body v2 differences

1{
2  "sender": { ... },
3  "recipient": { ... },
4  "mergeVariables": { ... },
5  "templateId": "tmpl_12345678900987654321",
6  "finish": "MATTE",
7  "billingId": "..."
8}

As you can see, you no longer need to send the different pages - you can just send us a single templateId which we will fetch the different pages from.

Step 3 - Send a test order to confirm the migration

In order to confirm if the migration process was successful, you can send a test-order through our portal. In the flow - you will only find v2 templates. After the order is complete and a successfully rendered preview shows up - the migration process for that template is done.

Repeat step 1 as often as you must, this will be different based on the amount of v1 templates you have.

Can I use v2 templates on my v1 integration?

No, you cannot. Our V1 API only accepts V1 templates, and our V2 API only accepts V2 templates. This is necessary to prevent rendering issues during your migration process.

If you have any questions regarding migrating, please contact us