Working with projects

Last updated on August 6, 2025
•
13 minutes to read

After a successful checkout, you can save the personalization results in your Customer's Canvas account for further processing. Here, the special integration entity Project appears. When creating a project, the corresponding private design is marked as permanent and remains in private storage for as long as this project exists.

Creating projects

The project is primarily used to prepare print files for making a personalized product. Projects store private designs, data obtained during personalization, and information about the order in the online store.

Single-item projects

A separate project is created for each product in the order if the product is linked to the Customer's Canvas specification. Depending on the configuration of the personalization process, a single project may include information about multiple elements and their personalized designs. For example, a project for the product representing a postcard in an envelope may include two elements: a postcard and an envelope.

In the Storefront API, the endpoint POST /api/storefront/v1/projects/with-single-item is responsible for creating projects. You can use it when you have linked your products through a product Reference. The parameters are the product identifier in the online store, order information, and personalization results.

curl -X POST "https://api.customerscanvashub.com/api/storefront/v1/projects?storefrontId=12" \
-H "accept: text/plain" \
-H "Authorization: Bearer <TOKEN>" \
-d '{
     "orderId": 1004,
     "item": {
          "productReference": "invitation",
          "designIds": ["642e793dc46d098d64514607", "62da200abb25c5477797d9cb"]
     }
}'

POST https://api.customerscanvashub.com/api/storefront/v1/projects?storefrontId=12
Content-Type: application/json
{
    "orderId": 1004,
    "item": {
        "productReference": "invitation",
        "designIds": ["642e793dc46d098d64514607", "62da200abb25c5477797d9cb"]
    }
}

// Set a real storefront ID
var storefrontId = 12;
// Set a product reference, order ID, and design IDs
var body = """
{
     "orderId": 1004,
     "item": {
          "productReference": "invitation",
          "designIds": [
               "642e793dc46d098d64514607", 
               "62da200abb25c5477797d9cb"
          ]
     }
}
""";
var project = await projectsApiClient.CreateWithSingleItemAsync(storefrontId, null, body);

// Set a real storefront ID
var storefrontId = 12;
// Set a product reference, order ID, and design IDs
var body = `
{
     "orderId": 1004,
     "item": {
          "productReference": "invitation",
          "designIds": ["642e793dc46d098d64514607", "62da200abb25c5477797d9cb"]
     }
}`;
var project = _projectsApiClient.createWithSingleItem(storefrontId, null, body);

// Set a real storefront ID
$storefrontId = 12;
// Set a product reference, order ID, and design IDs
$body = '
{
     "orderId": 1004,
     "item": {
          "productReference": "invitation",
          "designIds": ["642e793dc46d098d64514607", "62da200abb25c5477797d9cb"]
     }
}';
$project = $projectsApiClient->projectsCreate($storefrontId, null, $body);

Here, the designIds array contains private design IDs saved after personalization. The system will automatically run a pipeline linked to the product.

When you don't need to process an order, but only get a print file for a design, you can create a project with a built-in pipeline that performs a single render-hires task for a singe line item. To do so, use the endpoint POST /api/storefront/v1/projects/by-scenario/render-hires. In the request body, pass the RenderHiResScenarioDto data.

In the orderDetails object, you can pass the description of an e-commerce order:

orderId [string] is an order identifier.
orderUrl [string] is a link to the order.
orderNumber [integer] is an order number.
customerId [string] is a customer identifier.
customerName [string] is a customer name.

Specify the line item by ID or by index. The orderLineItemIndex and orderLineItemId fields can be specified at the root level of the body object or in the orderDetails object.

In the scenario object, you can pass the following rendering parameters:

designId [string] is an identifier of a private design.
name [string] is an output file name, result by default.
dpi [integer] is output file DPI, 300 by default.
format ["Pdf", "Jpeg", "Png", "Tiff", "Bmp"] is the output file format, "Pdf" by default.
colorSpace ["Rgb", "Grayscale", "Cmyk"] is the output file color space, "Cmyk" by default.
flipMode ["None", "Horizontal", "Vertical", "Both"] is a flip mode of the output file, "None" by default.
anonymousAccess [boolean] is the mode of accessing the output file, false by default.

Let's render a design from the order 1004 to the file print.pdf.

curl -X POST "https://api.customerscanvashub.com/api/storefront/v1/projects/by-scenario/render-hires?storefrontId=12" \
-H "accept: text/plain" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <TOKEN>" \
-d '{
     "orderDetails": {"orderId": 1004},
     "orderLineItemId": "642e798d6451dc407693d046",
     "scenario": {
          "designId": "62da200abb25c5477797d9cb",
          "name": "print"
     }
}'

POST https://api.customerscanvashub.com/api/storefront/v1/projects/by-scenario/render-hires?storefrontId=12
Content-Type: application/json
{
    "orderDetails": {"orderId": 1004},
    "orderLineItemId": "642e798d6451dc407693d046",
    "scenario": {
         "designId": "62da200abb25c5477797d9cb",
         "name": "print"
    }
}

// Set a real storefront ID
var storefrontId = 12;
// Set a product reference, order ID, and design IDs
var body = """
{
    "orderDetails": {"orderId": 1004},
    "orderLineItemId": "642e798d6451dc407693d046",
    "scenario"": {
        "designId": "62da200abb25c5477797d9cb",
        "name": "print"
    }
}
""";
var project = await projectsApiClient.CreateByRenderHiResScenarioAsync(storefrontId, null, body);

// Set a real storefront ID
var storefrontId = 12;
// Set a product reference, order ID, and design IDs
var body = `
{
     "orderDetails": {"orderId": 1004},
     "orderLineItemId": "642e798d6451dc407693d046",
     "scenario": {
          "designId": "62da200abb25c5477797d9cb",
          "name": "print"
     }
}`;
var project = _projectsApiClient.createByRenderHiResScenario(storefrontId, null, body);

// Set a real storefront ID
$storefrontId = 12;
// Set a product reference, order ID, and design IDs
$body = '
{
     "orderDetails": {"orderId": 1004},
     "orderLineItemId": "642e798d6451dc407693d046",
     "scenario": {
          "designId": "62da200abb25c5477797d9cb",
          "name": "print"
     }
}';
$project = $projectsApiClient->projectsCreateByRenderHiResScenario($storefrontId, null, $body);

Multi-item projects

To rid yourself from implementing post-processing of the results of single-item projects and at the same time process the entire order, you can use the endpoint POST /api/storefront/v1/projects/with-multiple-items, which creates a project for many products. This endpoint uses pipelines specified in every product configuration and the post-processing pipeline specified in the integration settings.

In the request body, pass the CreateMultiItemProjectDto data.

curl -X POST "https://api.customerscanvashub.com/api/storefront/v1/projects/with-multiple-items?storefrontId=12" \
-H "accept: text/plain" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <TOKEN>" \
-d '{
     "orderId": 1004,
     "items": [
          {
               "orderLineItemIndex": 0,
               "productReference": "24298",
               "designIds": ["642e793dc46d098d64514607", "62da200abb25c5477797d9cb"]
          },
          {
               "orderLineItemIndex": 1,
               "productReference": "24299",
               "designIds": ["642d0e469793dc8d64460751", "62d777a20cbbb25c5497d0a9"]
          }
     ]
}'

POST https://api.customerscanvashub.com/api/storefront/v1/projects/with-multiple-items?storefrontId=12
Content-Type: application/json
{
    "orderId": 1004,
    "items": [
         {
              "orderLineItemIndex": 0,
              "productReference": "24298",
              "designIds": ["642e793dc46d098d64514607", "62da200abb25c5477797d9cb"]
         },
         {
              "orderLineItemIndex": 1,
              "productReference": "24299",
              "designIds": ["642d0e469793dc8d64460751", "62d777a20cbbb25c5497d0a9"]
         }
    ]
}

// Set a real storefront ID
var storefrontId = 12;
// Set a product reference, order ID, and design IDs
var body = """
{
     "orderId": 1004,
     "items": [
          {
               "orderLineItemIndex": 0,
               "productReference": "24298",
               "designIds": [
                    "642e793dc46d098d64514607", 
                    "62da200abb25c5477797d9cb"
               ]
          },
          {
               "orderLineItemIndex": 1,
               "productReference": "24299",
               "designIds": [
                    "642d0e469793dc8d64460751", 
                    "62d777a20cbbb25c5497d0a9"
               ]
          }
     ]
}
""";
var project = await projectsApiClient.CreateWithMultipleItemsAsync(storefrontId, null, body);

// Set a real storefront ID
var storefrontId = 12;
// Set a product reference, order ID, and design IDs
var body = `
{
     "orderId": 1004,
     "items": [
          {
               "orderLineItemIndex": 0,
               "productReference": "24298",
               "designIds": ["642e793dc46d098d64514607", "62da200abb25c5477797d9cb"]
          },
          {
               "orderLineItemIndex": 1,
               "productReference": "24299",
               "designIds": ["642d0e469793dc8d64460751", "62d777a20cbbb25c5497d0a9"]
          }
     ]
}`;
var project = _projectsApiClient.createWithMultipleItems(storefrontId, null, body);

When you haven't linked products by product reference, you can create a product by using the endpoint POST /api/storefront/v1/projects/by-scenario/specific-pipeline. It creates a project to process several line items of an order.

In the request body, pass the CreateProjectBySpecificPipelineScenarioDto data. You can use an arbitrary pipeline defined in your BackOffice panel or the pipeline linked to the product. In the latter case, get its ID through the endpoint GET /api/storefront/v1/products/{id}.

When defining the scenario object, you must specify the pipelines to be applied by name or by ID:

pipelineId [integer] is an identifier of an existing processing pipeline, which will be applied to all the items.
postProcessingPipelineId [integer] is an existing processing pipeline identifier for project post-processing.
itemPipelines [] is an array of objects describing connections between project items (by itemName) and processing pipelines (by pipelineId). Here, you can configure a set of pipelines applicable to different items as an alternative to a single pipeline specified in pipelineId.

curl -X POST "https://api.customerscanvashub.com/api/storefront/v1/projects/by-scenario/specific-pipeline?storefrontId=12" \
-H "accept: text/plain" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <TOKEN>" \
-d '{
     "orderDetails": {"orderId": 1004},
     "items": [
          {
               "orderLineItemIndex": 0,
               "designIds": ["642e793dc46d098d64514607", "62da200abb25c5477797d9cb"]
          },
          {
               "orderLineItemIndex": 1,
               "designIds": ["642d0e469793dc8d64460751", "62d777a20cbbb25c5497d0a9"]
          }
     ],
     "scenario": {
          "pipelineId": 247,
          "postProcessingPipelineId": 243
     }
}'

POST https://api.customerscanvashub.com/api/storefront/v1/projects/by-scenario/specific-pipeline?storefrontId=12
Content-Type: application/json
{
    "orderDetails": {"orderId": 1004},
    "items": [
         {
              "orderLineItemIndex": 0,
              "designIds": ["642e793dc46d098d64514607", "62da200abb25c5477797d9cb"]
         },
         {
              "orderLineItemIndex": 1,
              "designIds": ["642d0e469793dc8d64460751", "62d777a20cbbb25c5497d0a9"]
         }
    ],
    "scenario": {
         "pipelineId": 247,
         "postProcessingPipelineId": 243
    }
}

// Set a real storefront ID
var storefrontId = 12;
// Set a product reference, order ID, and design IDs
var body = """
{
     "orderDetails": {"orderId": 1004},
     "items": [
          {
               "orderLineItemIndex": 0,
               "designIds": ["642e793dc46d098d64514607", "62da200abb25c5477797d9cb"]
          },
          {
               "orderLineItemIndex": 1,
               "designIds": ["642d0e469793dc8d64460751", "62d777a20cbbb25c5497d0a9"]
          }
     ],
     "scenario": {
          "pipelineId": 247,
          "postProcessingPipelineId": 243
     }
}
""";
var project = await projectsApiClient.CreateWithMultipleItemsAsync(storefrontId, null, body);

// Set a real storefront ID
var storefrontId = 12;
// Set a product reference, order ID, and design IDs
var body = "{
     'orderDetails': {'orderId': 1004},
     'items': [
          {
               'orderLineItemIndex': 0,
               'designIds': ['642e793dc46d098d64514607', '62da200abb25c5477797d9cb']
          },
          {
               'orderLineItemIndex': 1,
               'designIds': ['642d0e469793dc8d64460751', '62d777a20cbbb25c5497d0a9']
          }
     ],
     'scenario': {
          'pipelineId': 247,
          'postProcessingPipelineId': 243
     }
}";
var project = _projectsApiClient.createWithMultipleItems(storefrontId, null, body);

Defining project fields

To add flexibility to processing pipeline, you can define project fields with metadata about the order. For more details, refer to the Customizing workflows with project fields topic.

Let's consider a practical example. Imagine you're working on a project to render the design identified by the ID '62da200abb25c5477797d9cb', using a predefined pipeline tailored specifically for the product '24297'. Assume this pipeline offers functionality to modify the print file name, adjust orientation, and apply trimming to the final rendered output by using project fields. Here's what the model configuration might look like:

{
    "ownerId": "6527afc635b52bfadd355226",
    "item": {
        "productReference": "24297",
        "designIds": ["62da200abb25c5477797d9cb"],
        "fields": {
            "name": "Campaign",
            "orientation": "Vertical",
            "trim": false
        }
    }
}

Let's create a project for a single product. Other endpoints accept the same optional parameters and can be configured similarly.

Call the endpoint /api/storefront/v1/projects/with-single-item and pass the model there.

curl -X POST "https://api.customerscanvashub.com/api/storefront/v1/projects/with-single-item?storefrontId=12" \
-H "accept: text/plain" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <TOKEN>" \
-d '{
    "ownerId": "6527afc635b52bfadd355226",
    "item": {
        "productReference": "24297",
        "designIds": ["62da200abb25c5477797d9cb"],
        "fields": {
            "name": "Campaign",
            "orientation": "Vertical",
            "trim": false
        }
    }
}'

POST https://api.customerscanvashub.com/api/storefront/v1/projects/with-single-item?storefrontId=12
{
    "ownerId": "6527afc635b52bfadd355226",
    "item": {
        "productReference": "24297",
        "designIds": ["62da200abb25c5477797d9cb"],
        "fields": {
            "name": "Campaign",
            "orientation": "Vertical",
            "trim": false
        }
    }
}

// Set a real storefront ID.
var storefrontId = 12;
// Set a product reference, owner ID, design IDs, and custom fields.
var body = """
{
    "ownerId": "6527afc635b52bfadd355226",
    "item": {
        "productReference": "24297",
        "designIds": ["62da200abb25c5477797d9cb"],
        "fields": {
            "name": "Campaign",
            "orientation": "Vertical",
            "trim": false
        }
    }
}
""";
var project = await projectsApiClient.CreateWithSingleItemAsync(storefrontId, null, body);

// Set a real storefront ID.
var storefrontId = 12;
// Set a product reference, owner ID, design IDs, and custom fields.
var body = {
    "ownerId": "6527afc635b52bfadd355226",
    "item": {
        "productReference": "24297",
        "designIds": ["62da200abb25c5477797d9cb"],
        "fields": {
            "name": "Campaign",
            "orientation": "Vertical",
            "trim": false
        }
    }
};
var project = _projectsApiClient.createWithSingleItem(storefrontId, null, JSON.stringify(body));

Searching projects

You can get a list of projects related to a given online store and track their status by using the Storefront API endpoint GET /api/storefront/v1/projects.

curl -X GET "https://api.customerscanvashub.com/api/storefront/v1/projects?storefrontId=12" \
-H "accept: text/plain" \
-H "Authorization: Bearer <TOKEN>"

GET https://api.customerscanvashub.com/api/storefront/v1/projects?storefrontId=12

var storefrontId = 12; // Set a real storefront ID here
var projects = await projectsApiClient.GetAllAsync(storefrontId: storefrontId);

var storefrontId = 12; // Set a real storefront ID here
var projects = _projectsApiClient.getAll(null, null, null, null, null, null, null, null, null, null, null, storefrontId);

$storefrontId = 12; // Set a real storefront ID here
$projects = $projectsApiClient->projectsGetAll(null, null, null, null, null, null, null, null, null, $storefrontId);

To look up projects by partially matching the project ID, order name, or customer name, use the search query parameter.

This endpoint also supports a paginated output (using the skip and take query parameters) as well as filtering by creation date (datePeriod, one of All, Today, Last7Days, or Last30Days) and status (status). Let's output projects created in the last 7 days and apply pagination, starting from the 11th item with 10 items per page.

curl -X GET "https://api.customerscanvashub.com/api/storefront/v1/projects?storefrontId=12&datePeriod=Last7Days&skip=11&take=10" \
-H "accept: text/plain" \
-H "Authorization: Bearer <TOKEN>"

GET https://api.customerscanvashub.com/api/storefront/v1/projects?storefrontId=12&datePeriod=Last7Days&skip=11&take=10

var storefrontId = 12; // Set a real storefront ID here
var datePeriod = "Last7Days"; // Filter by creation date: "All", "Today", "Last7Days", or "Last30Days"
var skip = 11; // Number of items to skip
var take = 10; // Number of items per page
var projects = await projectsApiClient.GetAllAsync(datePeriod: datePeriod, skip: skip, take: take, storefrontId: storefrontId);

var storefrontId = 12; // Set a real storefront ID here
var datePeriod = "Last7Days"; // Filter by creation date: "All", "Today", "Last7Days", or "Last30Days"
var skip = 11; // Number of items to skip
var take = 10; // Number of items per page
var projects = _projectsApiClient.getAll(null, null, null, datePeriod, skip, take, null, null, null, null, null, storefrontId);

$storefrontId = 12; // Set a real storefront ID here
$datePeriod = "Last7Days"; // Filter by creation date: "All", "Today", "Last7Days", or "Last30Days"
$skip = 11; // Number of items to skip
$take = 10; // Number of items per page
$projects = $projectsApiClient->projectsGetAll(null, null, null, $datePeriod, $skip, $take, null, null, null, $storefrontId);

To filter projects by an external order number, use the orderID parameter. For example, if your e-commerce order has the identifier "54321", you can retrieve the corresponding Customer's Canvas project like this:

curl -X GET "https://api.customerscanvashub.com/api/storefront/v1/orders?storefrontId=12&orderID=54321" \
-H "accept: text/plain" \
-H "Authorization: Bearer <TOKEN>"

GET https://api.customerscanvashub.com/api/storefront/v1/orders?storefrontId=12&orderID=54321

var storefrontId = 12; // Set a real storefront ID here
var orderID = "54321"; // Set a real order ID here
var orders = await ordersApiClient.GetAllAsync(orderID: orderID, storefrontId: storefrontId);

var storefrontId = 12; // Set a real storefront ID here
var orderID = "54321"; // Set a real order ID here
var orders = ordersApiClient.getAll(null, null, null, null, null, null, null, null, orderID, null, null, storefrontId);

$storefrontId = 12; // Set a real storefront ID here
$orderID = "54321"; // Set a real order ID here
$orders = $ordersApiClient->ordersGetAll(null, null, null, null, null, null, null, null, $orderID, $storefrontId);