This is an old documentation. Go to the latest Customer's Canvas docs

User Images

Customer's Canvas provides a Web API to download and upload user images. After your users have created products in the web-to-print designer, you may want to improve their images prior to the PDF generation. In this case, you can extract user images from user states with this API, change these images on a local computer, and then put them back using the same API. Moreover, you don't have to manually download these images or photos in a browser for a single product. You can implement a desktop application to download user images from orders that were placed within a certain period of time, say, daily or all recent orders. Your application could automatically put these images into a folder where you can process them. When you finish working with images, this application could upload the changed copies back to your site with the same API.

This API works based on HTTPS requests and is handled by the UserImages controller (~/api/UserImages). It has the following functionality:

Function Request type URL Description
Create and download an image archive POST ~/api/UserImages/create Creates an archive of user images which they use in a product. It requires a pair of UserId and StateId.
Upload an image archive POST ~/api/UserImages/upload Uploads an archive and pastes images into corresponding state files. It uses file names of the images to define the destination.

To make changes in downloaded images and apply them to your product, you should unpack the archive, edit the images, and then pack them back. Make sure that image names and their hierarchy remain unchanged when you pack the images back into an archive.

Image file names have the following format: <UserId>_<StateId>_<ImageId>.<ext>


The snippet below defines the API security key in JavaScript code. It could be highly insecure if it runs on a public site. However, you can use it this way in your admin panel, or just for demonstration purposes.


The following example displays a form that allows you to archive images for a specified pair of UserId and StateId.

<!DOCTYPE html>
<html xmlns="">
    <title>User Images API Sample</title>
    <script type="text/javascript" src="">
    <script language="javascript">
        // Set a link to the UserImages controller.
        var url = "";
        // Set a unique key for using the Web API.
        var apiKey = "UniqueSecurityKey";

        // Define a function for obtaining an image archive.
        var getArchive = function() {
            var pairs = [];
            // Set a product state ID and a user ID for whoever created the state.
            pairs.push({UserId: "default", StateId: "a37a86bd-2d75-4f6e-a0e2-01fc4e4fc144"});

            // Make the create request.
                url: url + "/create",
                type: "POST",
                headers: { "X-CustomersCanvasAPIKey": apiKey },
                dataType: "json",
                contentType: "application/json; charset=utf-8",
                data: JSON.stringify(pairs)
            fail(function (d) { console.log(d.statusText); }).
            done(function (d) {
                window.location = d;

        // Define a function for uploading the updated archive back to a server.
        var uploadArchive = function () {
            var data = new FormData(document.getElementById("upload_archive"));

            // Make the upload request.
                url: url + "/upload",
                type: "POST",
                headers: { "X-CustomersCanvasAPIKey": apiKey },
                data: data,
                processData: false,
                contentType: false
    <h3>Download Images</h3>
    <input type="button" value="Get archive" onclick="getArchive()" />

    <h3>Upload Images</h3>
    <form id="upload_archive" enctype="multipart/form-data">
        File: <input type="file" name="file" />
        <input type="button" value="Upload archive" onclick="uploadArchive()" />


Customer's Canvas provides a Web API to reload images added from direct URLs in state files.

See Also