# Design endpoints

The design endpoints allow you to **get** and **export** designs created by customers.

These endpoints are available to **retrieve design details** such as texts the customer has entered in your external software, or to **export files** needed in your print production workflow.

Please take into account the [best practices](https://support.printlane.com/en/articles/10470412-authentication-and-best-practices) when implementing these API calls.

# Changelog

## Version 2026-01 (latest)**[​](https://help.printlane.com/api/media.html#version-2023-10-latest)**

The only change is that the usage of the domain `colorlab.io` and headers containing `colorlab` are not allowed anymore.

If you have already implemented these changes, you can simply use that latest version.

## Version 2023-10

- You can now use api version `2023-10`

- The domain name of all API endpoints has changed from `colorlab.io` to `printlane.com`.

- header `X-Colorlab-Shop` has changed to `X-Printlane-Store` (notice the change from `Shop` to `Store`)

- header `X-Colorlab-Api-Key` has changed to `X-Printlane-Api-Key`

- header `X-Colorlab-Api-Signature` has changed to `X-Printlane-Api-Signature`

- The endpoint for retrieving design details has changed from `customizations` to `designs`.

- Please find the overview of all URL changes below:

| **New URL**                                                                    | **Old URL**                                                                  |
| ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| `https://api.printlane.com/2023-10/export/:designId/:designToken`              | `https://api.colorlab.io/2022-08/export/:designId/:designToken`              |
| `https://api.printlane.com/2023-10/export/:designId/:designToken/view/:viewId` | `https://api.colorlab.io/2022-08/export/:designId/:designToken/view/:viewId` |
| `https://api.printlane.com/2023-10/designs/:designId/:designToken`             | `https://api.colorlab.io/2022-08/customizations/:designId/:designToken`      |

## Version 2022-08

- You can now use api version `2022-08`

- The endpoint URL's to export print production files and retrieve design details have changed:**[​](https://help.printlane.com/api/designs.html#version-2022-08)**

| **New URL**                                                                  | **Old URL**                                                                           |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `https://api.colorlab.io/2022-08/export/:designId/:designToken`              | `https://api.colorlab.io/v1/configuration/:designId/:designToken/export`              |
| `https://api.colorlab.io/2022-08/export/:designId/:designToken/view/:viewId` | `https://api.colorlab.io/v1/configuration/:designId/:designToken/view/:viewId/export` |
| `https://api.colorlab.io/2022-08/customizations/:designId/:designToken`      | `https://api.colorlab.io/v1/configuration/:designId/:designToken`                     |

## Version v1 (deprecrated)**[​](https://help.printlane.com/api/designs.html#version-v1-deprecrated)**

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

# How designs are referenced

When you receive an order, it contains order line items. Each order line item containing a product that's been personalized contains a unique reference that looks like this:

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

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

| **Value**                                                                           | **Description**                        |
| ----------------------------------------------------------------------------------- | -------------------------------------- |
| **Design ID**
an ascending integer representing the ID of the design in Printlane | `45`                                   |
| **Design Token**
a unique identifier to access this design                        | `3618204e-f166-4a53-8a7f-0ce2828b17ca` |

You need both the Design ID and Token to access design endpoints.

# Downloading print production files

## Endpoint to download a design

```
GET https://api.printlane.com/2023-10/export/:designId/:designToken
```

Replace `:designId` and `:designToken` with the ID and Token of the design. If the design contains multiple views (e.g. `front` and `back`), you can export a specific view by referencing its `viewId`:

```
GET https://api.printlane.com/2023-10/export/:designId/:designToken/view/:viewId
```

Replace `:viewId` with the internal ID of the view defined in the template, which you can find in the tab `Dimensions` under `Advanced settings`.

## Generating the verification string for the API Signature

The verification string to generate the signature is: `Store ID` + `Design ID` + `Design Token`. When exporting a specific view, you need to append the View ID so the verification string becomes: `Store ID` + `Design ID` + `Design Token` + `View ID`

[Read here](https://support.printlane.com/en/articles/10470412-authentication-and-best-practices) how to generate the `X-Printlane-Api-Signature` header with this verification string.

## Response file type

The response of the endpoint has a `Content-Disposition` header equal to `attachment` and delivers the file as raw data.

The `Content-Type` header is set to either `application/pdf` or `image/png`, depending on the export format configured for the design.

By default, the file type aligns with the export settings of the template at the time the design was created, which is either as PDF or PNG. You can refer to [this article](https://help.printlane.com/en/articles/10469990-configure-template-export-settings) to configure the export file type in templates.

- When exporting a design with multiple views, the export type of the first view is used.

- When exporting a specific view, the export type of that view is used.

**Tip:** You can override the file type by appending `?exportType=pdf` or `?exportType=png` to the endpoint URL.

## Code example (Node.js)

```
import { createWriteStream } from 'node:fs';
import { createHmac } from 'node:crypto';
import axios from 'axios';

const API_VERSION = '2026-01';
const API_KEY = 'your_api_key';
const API_SECRET = 'your_api_secret';

async function downloadDesign(storeId, designId, designToken, outputPath = 'design.pdf') {
  const apiSignature = createHmac('sha256', API_SECRET)
    .update(`${storeId}${designId}${designToken}`)
    .digest('hex');

  const response = await axios.get(
    `https://api.printlane.com/${API_VERSION}/export/${designId}/${designToken}`,
    {
      responseType: 'stream',
      headers: {
        'X-Printlane-Store': storeId,
        'X-Printlane-Api-Key': API_KEY,
        'X-Printlane-Api-Signature': apiSignature,
      },
    }
  );

  const writer = createWriteStream(outputPath);
  response.data.pipe(writer);

  return new Promise((resolve, reject) => {
    writer.on('finish', resolve);
    writer.on('error', reject);
  });
}

// Example execution:
downloadDesign('your_store_id', 'your_design_id', 'your_design_token', 'design.pdf')
  .then(() => console.log('Downloaded successfully'))
  .catch(console.error);
```

## Code example (cURL)

```
curl -X GET "https://api.printlane.com/2026-01/export/DESIGN_ID/DESIGN_TOKEN" \
  -H "X-Printlane-Store: YOUR_STORE_ID" \
  -H "X-Printlane-Api-Key: YOUR_API_KEY" \
  -H "X-Printlane-Api-Signature: GENERATED_API_SIGNATURE" \
  --output design.pdf
```

# Retrieving design details

Use following endpoint to retrieve design details:

```
GET https://api.printlane.com/2023-10/designs/:designId/:designToken
```

**Verification string for API Signature**

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

[Read here](https://support.printlane.com/en/articles/10470412-authentication-and-best-practices) how to generate the `X-Printlane-Api-Signature` header with this verification string.

**## Example output**

```
{
    "_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"
}
```