Colorlab Help Center

Appearance

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

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

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"
}