Skip to content
On this page

Customizations

The customization endpoints allow you to get and export customizations created by end-users.

These endpoints are available to retrieve customization details such as texts the end-user entered in your external software, or to export files needed in your print production workflow.

Please take into account the best practices when implementing these API calls.

Changelog

Version 2022-08 (latest)

  • The endpoint URL's to export print production files have changed:

    New URLPrevious URL
    https://api.colorlab.io/2022-08/export/:id/:tokenhttps://api.colorlab.io/v1/configuration/:id/:token/export
    https://api.colorlab.io/2022-08/export/:id/:token/view/:viewIdhttps://api.colorlab.io/v1/configuration/:id/:token/view/:viewId/export
  • The endpoint URL to retrieve customization details have changed:

    • New URL: https://api.colorlab.io/2022-08/customizations/:id/:token
    • Previous URL: https://api.colorlab.io/v1/configuration/:id/:token

Version v1

Initial API version. Will be deprecated in August 2023. Please update your implementation to point to the latest API version.

How customizations are referenced

When your application or online store received an order, it can contain order line items with products that are personalized. Each personalization has a unique reference, for example:

45.3618204e-f166-4a53-8a7f-0ce2828b17ca
1

This reference breaks down in two parts, separated by a point (.):

ValueDescription
45Customization ID
an ascending integer representing the ID of the customization in Colorlab
3618204e-f166-4a53-8a7f-0ce2828b17caCustomization Token
a unique identifier to access this customization

You need both the Customization ID and Customization Token to access customization endpoints.

Exporting print production files

Use following endpoint to retrieve customization exports:

GET https://api.colorlab.io/2022-08/export/:id/:token
1

Replace :id and :token with the ID and Token of the customization. If the customization contains multiple views (e.g. front and back), you can export a specific view by referencing it in the endpoint:

GET https://api.colorlab.io/2022-08/export/:id/:token/view/:viewId
1

Replace :viewId with the internal ID of the view defined in the template.

The response of this endpoint has a Content-Disposition header equal to attachment and sends the raw data of the file.

Verification string for API Signature

The verification string to generate the signature is: Store ID + Customization ID + Customization Token

When exporting a specific view, the verification string to generate the signature is: Store ID + Customization ID + Customization Token + View ID

Read here how to generate the X-Colorlab-Api-Signature header with this verification string.

Retrieving customization details

Use following endpoint to retrieve customization exports:

GET https://api.colorlab.io/2022-08/customizations/:id
1

Verification string for API Signature

The verification string to generate the signature is Store ID + Customization ID + Customization Token.

Read here how to generate the X-Colorlab-Api-Signature header with this verification string.

Example output
json
{
    "_id": "6351597b892e3ac9713c962e",
    "static": false,
    "name": "iPhone Case",
    "shop": "589adada754c20089ed6cfd8",
    "productId": "iphone-case-demo",
    "views": [
        {
            "active": true,
            "addArtwork": null,
            "addPicture": null,
            "addText": null,
            "allowRearrangeElements": true,
            "areas": [
                {
                    "height": 1911,
                    "id": "area-1",
                    "name": "Cover",
                    "width": 942,
                    "x": 140,
                    "y": 28
                }
            ],
            "cutOutMask": null,
            "elements": [
                {
                    "active": false,
                    "area": "area-1-1",
                    "export": true,
                    "id": "illustration-1",
                    "name": {
                        "en": "Left"
                    },
                    "order": 3,
                    "removable": true,
                    "required": false,
                    "section": 0,
                    "selectable": true,
                    "type": "illustration",
                    "weight": 0,
                    "allColors": true,
                    "allowTransparent": true,
                    "autoResize": "fill",
                    "colorize": false,
                    "colors": [],
                    "draggable": true,
                    "groups": [],
                    "positionX": 616.6253325527155,
                    "positionY": 1093.1438056427298,
                    "resizable": true,
                    "rotatable": true,
                    "rotation": 0,
                    "scale": 1,
                    "scaleArea": "area-1-1",
                    "value": null
                },
                {
                    "active": false,
                    "area": null,
                    "export": true,
                    "id": "illustration-2",
                    "name": {
                        "en": "Right"
                    },
                    "order": 4,
                    "removable": false,
                    "required": false,
                    "section": 0,
                    "selectable": true,
                    "type": "illustration",
                    "weight": 1,
                    "allColors": true,
                    "allowTransparent": true,
                    "autoResize": "none",
                    "colorize": false,
                    "colors": [],
                    "draggable": true,
                    "groups": [],
                    "positionX": 923.5673901604217,
                    "positionY": 726.0217554777572,
                    "resizable": true,
                    "rotatable": true,
                    "rotation": 60,
                    "scale": 0.75,
                    "scaleArea": null,
                    "value": null
                },
                {
                    "active": true,
                    "area": "area-1-1",
                    "export": true,
                    "id": "picture-2",
                    "name": {
                        "en": "Picture"
                    },
                    "order": 2,
                    "removable": true,
                    "required": false,
                    "section": 0,
                    "selectable": true,
                    "type": "picture",
                    "weight": 2,
                    "autoResize": "fit",
                    "colorize": false,
                    "colorizeToColor": null,
                    "custom": [],
                    "draggable": true,
                    "fx": [],
                    "positionX": 572.5553573460255,
                    "positionY": 976.2286960046268,
                    "resizable": true,
                    "rotatable": true,
                    "rotation": 60,
                    "scale": 0.57,
                    "scaleArea": "area-1-1",
                    "value": {
                        "_id": "63515977f5711aff572bc75a",
                        "originalname": "background.jpg",
                        "token": "070b3838-9232-4b26-ad33-ba2e26497887",
                        "mimetype": "image/jpeg",
                        "size": 577190,
                        "meta": {
                            "hasAlpha": false,
                            "height": 2000,
                            "width": 1200
                        }
                    }
                }
            ],
            "export": {
                "area": null,
                "areaType": "template",
                "custom": [],
                "dpi": 300,
                "exportCutOutMask": true,
                "exportTemplate": true,
                "filename": "[id]-[title]",
                "height": 0,
                "mergeDimensions": null,
                "mergeInFile": null,
                "mergePosition": null,
                "type": "pdf",
                "width": 0,
                "x": 0,
                "y": 0
            },
            "groupElements": false,
            "height": 2021,
            "id": "front",
            "name": {
                "en": "Front"
            },
            "required": false,
            "template": {
                "_id": "63514a1b1e4736e97ea4aaae",
                "meta": {
                    "hasAlpha": false,
                    "height": 2021,
                    "width": 1222
                },
                "originalname": "iphone-case-template.jpg",
                "token": "2463e3c6-f48e-4b9c-b572-695e8ef109ba",
                "mimetype": "image/jpeg",
                "size": 418898
            },
            "weight": 0,
            "width": 1222
        }
    ],
    "synchronization": [],
    "domain": "website.com",
    "url": "https://store.website.com/cases/iphone",
    "_created": "2022-10-20T14:00:00.680Z",
    "_updated": "2022-10-20T14:01:30.680Z",
    "configurationId": 155,
    "token": "b79c4175-b833-48d5-9c85-5a65344c911f"
}
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