Downloading artifacts for an order
- 13 minutes to read
Let's say your customers have created personalized designs using a Customer's Canvas editor and placed an order on your online store. If your store is based on one of the e-commerce platforms we support (like Shopify, BigCommerce, WooCommerce, Magento, or nopCommerce), or if you've followed the steps in the integration guide, a project is created once the order is placed. You can easily access the project in the Customer's Canvas BackOffice app and download the print files from it.
However, downloading print files manually isn't always an option. For instance, if you don't handle order fulfillment in-house and instead use an API to send orders to your printing company.
In such a scenario, you can use the Customer's Canvas API to automatically download print files (or, speaking more widely, artifacts, which can include additional files if required) for completed orders. This article provides instructions on how to do so.
Here are some assumptions that we will make for this guide:
Your application can receive information about orders from your e-commerce platform, and your app can differentiate between new orders and orders you have already processed.
For example, if you're using Shopify, your app may subscribe to the
orders/createwebhook. Alternatively, you could request all new orders once a day and mark them as processed once you've downloaded the order artifacts (print files).
An online store is integrated with Customer's Canvas and you have its
The rendering pipelines are properly configured for the products you want to process.
Your objective is to download all artifacts for the selected orders.
How we are going to achieve this goal
The diagram below illustrates the flow initiated by an e-commerce platform when a user completes an order for a product with Customer's Canvas data.
When a user completes an order for a product with Customer's Canvas data, the e-commerce platform triggers the order creation webhook. Customer's Canvas handles this webhook and creates a project record, which starts the rendering job. Since the rendering job works asynchronously, it may take some time to complete all steps. However, once finished, the artifacts created by its tasks are saved in Asset Storage.
As soon as the project is created, Customer's Canvas saves the order ID and its number as the project metadata. This allows your app to request projects related to your orders. Once you have the project information, you can find the rendering job associated with it. Only one rendering job per project may exist. A job is not created immediately with a project, but any delay is typically quite small.
The rendering job can have several statuses, such as pending or in progress. You need to implement a polling scheme and repeat the request at some time interval until the job becomes completed. Note that the job may fail, and in this case, you need to stop polling. You should decide what your app should do in such cases, such as saving this information to a log or attempting to restart it.
When the job successfully completes, all relevant print files and other artifacts become available to download.
The following sequence diagram illustrates the process.
| Failed Note over A: Once Job is Completed A ->> C : Get artifacts C ->> A : List of URLs loop For each artifact A ->> C : Download artifact C ->> -A : Artifact binary (e.g. PDF) end A ->> E : Tag order as done end
Using the API
This guide assumes that you are familiar with the principles of how you should use the Customer's Canvas API. If not, we recommend that you take a look at these articles first.
- API Reference - for an API overview and information about supported API Client libraries
- C# API Client - for the guide on how you can properly integrate the C# API Client library to your .NET app
Authenticating your app
Before we start, make sure that your app has credentials to make API calls. For the scenario described above, the most relevant authentication scheme is the Client Credentials.
Register your app in your tenant and implement the authentication in your app as explained in the Authentication in Customer's Canvas article.
Determining your storefrontId
Customer's Canvas allows for integrating a single tenant with multiple storefronts (i.e., online stores) simultaneously. For example, you may have two Shopify stores with different domains for different products. Or, you may have one store based on WooCommerce and another one on BigCommerce.
When you work with projects, you need to know the
storefrontId, which allows you to distinguish one store from another. It is especially important considering that the uniqueness of the order numbers between different online stores is not guaranteed.
To determine the
storefrontId, in your Customer's Canvas account, go to Settings -> Integrations. The
storefrontId is in the left column.
Searching projects for an order
You can use the Projects_GetAll endpoint of the Storefront API to receive a list of projects. You need to provide at least two arguments to achieve our goal:
storefrontId- obtained as explained above.
orderId- an ID of an order you need to process.
Let's assume that the
storefrontId is 42 and the
orderId is 123.
curl -X \ GET "https://api.customerscanvashub.com/api/storefront/v1/projects?orderId=123&storefrontId=42" \ -H "accept: text/plain"\ -H "Authorization: Bearer <TOKEN>"
It returns a structure containing a list of project items filtered by this order ID. Note that it is a normal scenario when a single order includes multiple projects. For example, if an order consists of several line items and these line items represent products associated with Customer's Canvas, a project per each such line item is created.
You need to use the
id of each project in this list as explained further.
Getting a project's artifacts directly
To simplify the process, we have introduced a dedicated endpoint that enables you to receive artifacts directly from a project without worrying about the rendering job. You can access this endpoint at Projects_GetProjectProcessingResults by passing the ID of each project returned in the previous step.
For example, if the project ID is 4567, the API call may look like this.
curl -X \ GET "https://api.customerscanvashub.com/api/storefront/v1/projects/4567/processing-results" \ -H "accept: text/plain" \ -H "Authorization: Bearer <TOKEN>"
Once you receive the processing results, you need to check the
status field, which can have one of four values:
- If the status is
InProgress, you should wait and retry after some interval, such as several minutes (minimum 60 seconds).
- If the status is
Failed, refer to the
statusDescriptionfield for additional details.
- If the status is
Completed, the artifacts are ready, and you can retrieve them from the
When processing the
outputFileDetails, keep in mind that depending on the rendering pipeline, the results may include more than one file. For example, it may include a print-ready PDF file, a reference preview, and a JSON description of the order. It may also include multiple PDF files for a VDP scenario, or it may contain a single ZIP archive that includes all files.
One important parameter to consider is whether artifacts can be downloaded using a direct link without authentication. An author of a rendering pipeline may control whether artifacts are available anonymously or not. Your app can determine this by checking the
anonymousAccess flag. If the flag is
true, you can download the artifact using the
url property. If it is not
true, you will need to use the Artifacts_GetFile endpoint of the Asset Storage API as explained later in this article.
These steps should be sufficient to achieve your goal of downloading print files for an order. However, if you need more control over the rendering process for any reason, you may want to explore other capabilities of the API.
Restarting failed jobs
There are several reasons why a job may have a
Failed status. Some of these reasons may be temporary, in which case you may want to retry the job execution. There are two operations you can use to retry a failed job:
- Resume (Projects_ResumeProjectProcessing): This operation continues the job from the point of the last failed task.
- Restart (Projects_RestartProjectProcessing): This operation restarts the job from the first task.
We recommend using the Resume operation to recover a failed job. This is because there is no need to redo operations that have already succeeded, which can reduce overhead. Additionally, certain tasks should not be repeated without a good reason. For example, if a task purchases a photo from a stock service, and the job fails on a subsequent task, restarting the job would cause a second purchase of the item, which has already been paid for.
However, the Restart operation is useful in situations where you need to regenerate all temporary artifacts from scratch, such as when editing a personalized design after the user has submitted it.
When retrying a failed job, it is important to use a reasonable delay between attempts. Ideally, this delay should be several minutes and should not be less than one minute.
To resume a failed job, use the following API call.
curl -X \ POST "https://api.customerscanvashub.com/api/storefront/v1/projects/4567/resume-processing" \ -H "accept: text/plain" \ -H "Authorization: Bearer <TOKEN>" \ -d ""
A Restart operation is called in a similar manner.
curl -X \ POST "https://api.customerscanvashub.com/api/storefront/v1/projects/4567/restart-processing" \ -H "accept: text/plain" \ -H "Authorization: Bearer <TOKEN>" \ -d ""
Finding a rendering job for a project
To retrieve a rendering job by its associated project ID, you will need to use the RenderingService API. The RenderingJobs_GetAll endpoint allows you to filter the results by the
projectId parameter, ensuring that you only retrieve the job that is relevant to the specified project.
curl -X \ GET "https://api.customerscanvashub.com/api/rendering/v1/jobs?projectId=4567" \ -H "accept: text/plain"\ -H "Authorization: Bearer <TOKEN>"
Typically, there should only be one job associated with each project, so you can assume that the first result returned corresponds to the relevant job. The job description contains various details, such as its ID and status.
However, keep in mind that there may be situations where no job has been created for a project yet. In such cases, it may be necessary to make several attempts with a reasonable delay between each attempt.
Getting a list of artifacts
If you need to get a list of artifacts by job ID, you can use the Artifacts_GetAll endpoint of the Asset Storage API. This is useful in situations where you need to get some extended details about them compared to the approach with Projects_GetProjectProcessingResults.
To use the endpoint, pass the job ID as a
group parameter. This result will show only the artifacts that were generated as part of the specified job. You can also filter out all temporary artifacts by specifying the type as Final.
For example, if you wanted to get a list of all final artifacts generated by a job with ID 12345, you could make the following API call:
curl -X \ GET "https://api.customerscanvashub.com/api/storage/v1/artifacts?group=12345&type=Final" \ -H "accept: text/json"\ -H "Authorization: Bearer <TOKEN>"
This would return a list of all final artifacts generated by the specified job.
When using the Artifacts_GetAll endpoint to retrieve artifacts, as explained above, the output structure contains additional fields, such as
lastModified, in addition to the ones returned by Projects_GetProjectProcessingResults.
To download the results, you can simply use the Artifacts_GetFile endpoint and provide the artifact ID. If needed, you can include the
attachment flag to control whether the
Content-Disposition header with the file name should be included in the API response or not.
Let's see how you can get an artifact with ID = 98765 with the attachment mode enabled.
curl -X \ GET "https://api.customerscanvashub.com/api/storage/v1/artifacts/98765/file?attachment=true" \ -H "accept: application/octet-stream" \ -H "Authorization: Bearer <TOKEN>"
If the rendering pipeline author has enabled the ability to download artifacts via a direct link, you can access these files more easily by using the
url property without requiring authentication. To ensure that direct URLs are available, check if the
anonymousAccess property is set to
In this article, we have discussed the flow required to download print files and other artifacts for completed e-commerce orders, which is a crucial task in integrating Customer's Canvas with order fulfillment systems.
We have determined that the most efficient way to achieve this goal is by utilizing the Projects_GetProjectProcessingResults endpoint. However, we have also explored an additional endpoint that performs other tasks, such as recovering failed jobs, checking the project status, and receiving the binary content of the artifacts.
By following the guidelines provided in this article, you can easily integrate Customer's Canvas into your e-commerce system and streamline your order fulfillment process.