Managing templates

The template endpoints allow you to create, update and delete templates in Colorlab.

These endpoint help you to automatically synchronize externally managed template data, such as a Product Information Management system or a custom database. This integration eliminates the need without the need to manually create and update templates in the Colorlab Console.

Integrating these endpoints in your software or service guarantee that new templates and updates are immediately available in Colorlab.

Creating a template

To create an template, use the POST http method to send a JSON payload to the following endpoint:

1
POST https://api.colorlab.io/v1/template

Example payload

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
{
"name": "iPhone XS case",
"productId": "SKU_456",
"views": [
{
"name": {
"en": "Front"
},
"active": true,
"weight": 0,
"template": "media-id-here",
"groupElements": true,
"areas": [
{
"id":"area-1",
"name": "Area 1",
"x": 0,
"y": 0,
"width": 100,
"height": 100
},
{
"id":"area-2",
"name": "Area 2",
"x": 100,
"y": 100,
"width": 100,
"height": 100
}
],
"allowRearrangeElements": true,
"fields": [
{
"id": "picture-1",
"name": {
"en": "Your picture"
},
"type": "picture",
"value": "default-media-id-here",
"draggable": true,
"resizable": true,
"rotatable": true,
"scale": 1,
"positionX": 950,
"positionY": 949,
"rotation": 0,
"selectable": true,
"required": false,
"active": false,
"weight": 3,
"export": true,
"scaleArea": "area-1",
"area": "area-1",
"autoResize": "fill",
"removable": false,
"section": 0
},
{
"id": "text-1",
"name": {
"en": "Your text"
},
"type": "text",
"value": {
"en": "Initial text shown"
},
"multiline": true,
"align": "center",
"maxCharacters": 0,
"draggable": true,
"resizable": true,
"rotatable": true,
"readOnly": false,
"fontsize": 171,
"minFontsize": 171,
"maxFontsize": 713,
"bold": false,
"italic": false,
"allColors": true,
"positionX": 950,
"positionY": 949,
"rotation": 0,
"selectable": true,
"required": false,
"active": false,
"weight": 2,
"export": true,
"colors": [
{
"default": true,
"color": "#000000",
"name": {
"en": "Black"
}
},
{
"default": false,
"color": "#ffffff",
"name": {
"en": "White"
}
},
{
"default": false,
"color": "#fe5a49",
"name": {
"en": "Tomato Red"
}
},
{
"default": false,
"color": "#40bdff",
"name": {
"en": "Sky Blue"
}
},
{
"default": false,
"color": "#ffe459",
"name": {
"en": "Lemon Yellow"
}
},
{
"default": false,
"color": "#81cc82",
"name": {
"en": "Avocado Green"
}
}
],
"area": "area-2",
"removable": false,
"section": 0
},
{
"id": "illustration-1",
"name": {
"en": "Select artwork"
},
"type": "illustration",
"draggable": true,
"resizable": true,
"rotatable": true,
"scale": 1,
"positionX": 950,
"positionY": 949,
"rotation": 0,
"selectable": true,
"required": false,
"active": false,
"weight": 1,
"export": true,
"removable": false,
"section": 0
},
{
"id": "background-1",
"name": {
"en": "Background color"
},
"type": "background",
"allColors": true,
"allowTransparent": true,
"selectable": true,
"required": false,
"active": true,
"weight": 0,
"export": true,
"colors": [
{
"default": false,
"color": "#000000",
"name": {
"en": "Black"
}
},
{
"default": false,
"color": "#ffffff",
"name": {
"en": "White"
}
}
],
"removable": false,
"section": 0
}
],
"export": {
"type": "pdf",
"dpi": 300,
"filename": "[id]-[title]",
"areaType": "template",
"exportTemplate": true
},
"addText": {
"active": false,
"align": "left",
"allColors": true,
"allFonts": true,
"area": null,
"bold": false,
"charSpacing": 0,
"colors": [
{
"name": {
"en": "Black",
"nl": "Zwart"
},
"color": "#000000",
"default": true
}
],
"defaultFont": null,
"draggable": true,
"export": true,
"fonts": [],
"fontsize": 500,
"italic": false,
"lineHeight": 1,
"maxCharacters": 0,
"maxFontsize": 1000,
"minFontsize": 100,
"multiline": true,
"name": {
"en": "Text",
"nl": "Tekst"
},
"order": 0,
"positionX": 1500,
"positionY": 868,
"readOnly": false,
"required": false,
"resizable": true,
"rotatable": true,
"rotation": 0,
"selectable": true,
"type": "text",
"useGlobalColors": false,
"value": {
"en": "Your text",
"nl": "Je tekst"
},
"weight": 0,
"section": 0,
"removable": true
},
"addPicture": {
"active": false,
"area": null,
"autoResize": "fill",
"colorize": false,
"colorizeToColor": "#5092da",
"draggable": true,
"export": true,
"fx": [],
"name": {
"en": "Picture",
"nl": "Afbeelding"
},
"order": 0,
"positionX": 186,
"positionY": 200,
"required": false,
"resizable": true,
"rotatable": true,
"rotation": 0,
"scale": 1,
"scaleArea": null,
"selectable": true,
"type": "picture",
"value": null,
"weight": 0,
"section": 0,
"removable": true
},
"addArtwork": {
"active": false,
"allColors": true,
"allowTransparent": true,
"area": null,
"autoResize": "fit",
"colorize": false,
"colors": [],
"groups": [],
"draggable": true,
"export": true,
"name": {
"en": "Artwork",
"nl": "Illustratie"
},
"order": 0,
"positionX": 500,
"positionY": 200,
"required": false,
"resizable": true,
"rotatable": true,
"rotation": 0,
"scale": 1,
"scaleArea": null,
"selectable": true,
"type": "illustration",
"useGlobalColors": false,
"value": null,
"weight": 0,
"section": 0,
"removable": true
}
}
]
}

Template properties

Property Description
name Name of the template which will be displayed in the Console.
productId Your reference to the template. This will be used to update the template later on. Must be unique per shop.
views Array of views in the template (e.g. Front and Back). See View properties for each object in this array.

View properties

Property Description
name An object with the name of the view which will be displayed in the app. Provide a translation for each language activated in your account.
active Defines which view will be active by default in the app. Only 1 view in the array of views can be active.
weight The order of the views as displayed in the app. Ascending number, starting from 0. The lowest number will be displayed first.
template The ID of the media object to display in the app (see Uploading media)
width The width of the template in pixels
height The height of the template in pixels
groupElements Boolean, indicates if tabs in the app should be grouped by type
allowRearrangeElements Allow the user to rearrange elements in a layer modal
fields Array of elements to be displayed in the app for this view. See Element properties for each object in this array.
export See view export properties below.
areas See view areas properties below.
addText Contains the same properties as the text element properties. Allows the user to add his own text elements based on the defaults in this property
addPicture Contains the same properties as the picture element properties. Allows the user to add his own picture elements based on the defaults in this property
addArtwork Contains the same properties as the artwork element properties. Allows the user to add his own artwork elements based on the defaults in this property

View export properties

Sets the default export properties for the view.

Property Description
type Could be pdf, png or pdf-simple (PNG-based PDF).
dpi The export dpi.
filename Default filename is [id]-[title]. You can use following tokens: [id] configuration id, [date] date in yyyy-mm-dd format, [title] configuration name, [product] template id`
areaType Defines the export dimensions type. Could be template, custom or area.
area This property is required when areaType is area. A valid area id must be given here.
exportTemplate Boolean defining if the export should contain the template.
x Required when areaType is custom. Defines the export x position.
y Required when areaType is custom. Defines the export y position.
width Required when areaType is custom. Defines the export width.
height Required when areaType is custom. Defines the export height.

View areas properties

Sets the default export properties for the view.

Property Description
id Unique id for this area.
name The human readable name for this area.
x X position of the area.
y Y position of the area.
width Area width.
height Area height.

Element properties

Each element has these properties. Each element type has additional properties, unique to this element type. These properties are displayed later in this page.

Property Description
id Your unique ID for this element. This can be used to access the element later.
name An object with the name of the element which will be displayed in the app. Provide a translation for each language activated in your account.
selectable Defines if the user is able to edit this element.
required Marks an element required, which will trigger a message in the app if the end user doesn’t have a value selected for this element.
active Defines which element will be active by default in the view. Only 1 element in the array of elements can be active.
weight The order of the elements as displayed in the app. Ascending number, starting from 0. The lowest number will be displayed below all other elements, just like layers in Photoshop.
export Defines if the element should be included in customization exports.
type Defines the element type. This can be text, picture, illustration or background.
area Define the area this element is visible in. Only a valid area id from the areas property is allowed.
removable Allows the user to delete this pre-defined element.
section Determines where the element is rendered. -1 = footer, 0 = body, 1 = header.

Element (text) properties

Following additional properties are required for text elements.

Property Description
multiline Allow the user to enter multiple lines
value An object with the default text value which will initially be displayed in the app. Provide a translation for each language activated in your account.
align Default alignment of the text if multiple lines are used (left, center (default) or right)
maxCharacters Defines the maximum amount of characters that can be entered. Set to 0 to allow unlimited characters.
draggable Allows the user to change the position of the element.
resizable Allows the user to change the size of the element.
rotatable Allows the user to rotate the element.
minFontsize The minimum font size of the text.
maxFontsize The maximum font size of the text.
bold Boolean indicating if the bold version of the font should be used.
italic Boolean indicating if the italic version of the font should be used. When combined with bold, the boldItalic version of the font is used
allColors Allows the user to add and use all colors.
colors An array of the colors displayed in the app. Each color is defined as an object containing a name (object with translations for each language in your account), default (one color can be the default in the array) and the color (a hex string defining the color to be used).
positionX The horizontal position of the text in pixels. Calculated from the top left corner of the view.
positionY The vertical position of the text in pixels. Calculated from the top left corner of the view.
rotation The initial rotation of the element (0 - 360).

Element (picture) properties

Following additional properties are required for picture elements.

Property Description
value The ID of the Media object which is used as default value when opening the app (see Uploading media).
draggable Allows the user to change the position of the element.
resizable Allows the user to change the size of the element.
rotatable Allows the user to rotate the element.
scale The initial scale of the picture (if a value is set)
positionX The horizontal position of the picture in pixels. Calculated from the top left corner of the view.
positionY The vertical position of the picture in pixels. Calculated from the top left corner of the view.
rotation The initial rotation of the element (0 - 360).
scaleArea Define the area this element is scaled to. Only a valid area from the areas property is allowed.
autoResize Resize options how the picture should behave inside an area. Allowed values are none, fill and fit

Element (illustration) properties

Following additional properties are required for artwork elements (type illustration).

Property Description
value The ID of the Media object which is used as default value when opening the app.
draggable Allows the user to change the position of the element.
resizable Allows the user to change the size of the element.
rotatable Allows the user to rotate the element.
scale The initial scale of the picture (if a value is set)
positionX The horizontal position of the picture in pixels. Calculated from the top left corner of the view.
positionY The vertical position of the picture in pixels. Calculated from the top left corner of the view.
rotation The initial rotation of the element (0 - 360).
scaleArea Define the area this element is scaled to. Only a valid area from the areas property is allowed.
autoResize Resize options how the picture should behave inside an area. Allowed values are none, fill and fit

Element (background) properties

Following additional properties are required for artwork elements (type illustration).

Property Description
allColors Allows the user to add and use all colors.
colors An array of the colors displayed in the app. Each color is defined as an object containing a name (object with translations for each language in your account), default (one color can be the default in the array) and the color (a hex string defining the color to be used).
allowTransparant Allows the user to select no color (transparent).

Updating a template

To update a template, use the POST http method to send the JSON payload to the following endpoint:

1
POST https://api.colorlab.io/v1/template/:id

And replace :id with the productId property that was used used when creating the template. The endpoint uses the exact same JSON payload as the create endpoint.

Deleting a template

To delete a template, use the DELETE http method to the following endpoint:

1
DELETE https://api.colorlab.io/v1/template/:id

Important: created customizations based on this template won't be deleted. Referenced media documents are deleted automatically.

Generating the signature

Create a verification string containing this data:
shopId + productId

Example: with a shopIdequal to 555 and a productId equal to SKU_456, the verification string is:

1
555SKU_456

Now use your API secret to compute a sha256 HMAC signature. You can test the output using online generators like https://www.freeformatter.com/hmac-generator.html.

Use the resulting value in the X-Colorlab-Api-Signature header when sending requests to the above API endpoints.