Working with projects
- Last updated on July 21, 2025
- •
- 11 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"]
}
}'
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"
}
}'
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"]
}
]
}'
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 (bypipelineId
). Here, you can configure a set of pipelines applicable to different items as an alternative to a single pipeline specified inpipelineId
.
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
}
}'
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
}
}
}'
Browsing 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
. This endpoint supports a paginated output as well as filtering by creation date and status.
curl -X GET "https://api.customerscanvashub.com/api/storefront/v1/projects?storefrontId=12" \
-H "accept: text/plain" \
-H "Authorization: Bearer <TOKEN>"
Working with project statuses
During the lifecycle of a project, it can move from one status to another, reflecting the completed stages: creation, confirmation, preparation of a print file, production of products, delivery, and so on.
To get information about possible project states and transitions between them, you can use the endpoints GET /api/storefront/v1/projects/statuses
and GET /api/storefront/v1/projects/transitions
.
curl -X GET "https://api.customerscanvashub.com/api/storefront/v1/projects/statuses" \
-H "accept: text/plain" \
-H "Authorization: Bearer <TOKEN>"
The transition between states is performed using the endpoint POST /api/storefront/v1/projects/{id}/transitions/{transition}
. For example, if the project ID is 906
, you can make it confirmed as follows:
curl -X POST "https://api.customerscanvashub.com/api/storefront/v1/projects/906/transitions/confirm" \
-H "accept: text/plain" \
-H "Authorization: Bearer <TOKEN>"
To prepare and download a print file for making a personalized product, you can get its URL from the response of the endpoint GET /api/storefront/v1/projects/{id}/processing-results
. The only parameter is the project identifier. For example, if the project ID is 906
, you can get the print file links as follows: