Colorlab Help CenterAppearance
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 URL Previous URL https://api.colorlab.io/2022-08/export/:id/:tokenhttps://api.colorlab.io/v1/configuration/:id/:token/exporthttps://api.colorlab.io/2022-08/export/:id/:token/view/:viewIdhttps://api.colorlab.io/v1/configuration/:id/:token/view/:viewId/exportThe 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
- New URL:
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
This reference breaks down in two parts, separated by a point (.):
| Value | Description |
|---|---|
45 | Customization ID an ascending integer representing the ID of the customization in Colorlab |
3618204e-f166-4a53-8a7f-0ce2828b17ca | Customization 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
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
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 details:
GET https://api.colorlab.io/2022-08/customizations/:id/:token
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"
}