Integration to e-commerce platform

• 8-9 minutes to read

One of the most common scenarios for using Customer's Canvas is its integration into an online store and use for ordering personalized products. Integration is not limited to embedding the editor on the product page. Here are some aspects that you may want to implement with this integration:

• Setting up and publishing Customer's Canvas products in the store.
• Displaying various elements of the order workflow on the store's frontend - both the editor and additional elements such as the selection of options, the approval screen, the shopping cart, etc. In some cases, you can embed Customer's Canvas components entirely, and in others, you can integrate the components into existing ones or develop them from scratch, relying on the Customer's Canvas API.
• Calculating the price if there are not enough opportunities in your system to get the price of a personalized product, for example, for products with a custom size (the price depends on the area) or when there is a complex combination of options.
• Temporary saving of personalization results until the moment of purchase.
• Processing the order and creating print files.
• Downloading the print files or transferring them to the production system.
• Complete repeat order or re-personalization.

The Customer's Canvas API allows you to implement a large number of web-to-print scripts based on any e-commerce system, including self-written ones. Below we will take a look at popular use cases and ways to implement them.

Common tasks

Authorization and authentication

Customer's Canvas has two authentication systems — for the common API and for working with the Storefront API.

The common auth system is described in the article Authentication in Customer's Canvas Hub. When implementing e-commerce integration, the Client Credentials scheme is usually used, when all calls occur backend-to-backend.

Storefront registration

Each storefront must be registered in Customer's Canvas in the Integration section, as described in the article Registering a storefront.

If you have several storefronts, for example, for each customer or product type, register each of them separately. Their ID will need to be used when working with the Storefront API. This will allow us to understand which store the order is being placed in.

Use cases

E-commerce system admin panel

Publishing Customer's Canvas products in the customer's store

The products in Customer's Canvas are used to describe the edited product in terms of personalization. Like e-commerce, it can have options — certain properties of the product that the user can choose — for example, the material color, the artwork position, size, printing method, etc. The property can determine which mockup we visualize the product and which design template we use. All combinations of option values form a variant set, for example, the pen may have the following variants identified by SKU:

• "Blue" / "Design on the barrel of the pen" / "Engraving"
• "White" / "Design under the clip" / "Color printing"

Product catalog models in different e-commerce systems may have a different structure, but it is often close to how it is described in Customer's Canvas. In addition to a single product, there is also the concept of options and product variants. The description of products in the e-commerce system may be richer, for example, include options that do not affect the design and do not require the use of Customer's Canvas. So, when we want to publish a Customer's Canvas product on a product page in the e-commerce system, we need to solve two tasks: associate the Customer's Canvas product with the product page and reflect a set of SKUs from the e-commerce system to a set of SKUs in Customer's Canvas.

There are two ways to link the products:

1. Save the Customer's Canvas product ID in the product database of your e-commerce system.
2. Save your product ID in Customer's Canvas product by creating a product reference.

These aspects are covered in the article Publishing Customer's Canvas products on your online store.

Saving personalization data when processing an order

Below, we will discuss how the customer creates a private design (or several designs) during the order process. Until the moment of purchase, links to these designs are stored somewhere along with information about the line items in the cart.

When the customer completes the payment, the shopping cart turns into an order in your system. As a rule, e-commerce systems can process this event through the UI or an internal event of your e-commerce system. The handler of such an event is the right place to transfer information about personalized orders to the Customer's Canvas to turn the designs into print files.

To do this, you need to create a project, which is a Customer's Canvas structure that describes the order personalization data. For more details, refer to the article Processing personalization results.

Once a project is created or transferred to another status, its processing pipeline runs. Usually, a pipeline describes how a personalized design will be processed, for example, turning it into a PDF, as well as transferring it to an order fulfillment system. More on this below.

Obtaining print files

Rendering and processing of the designs does not occur immediately. They are placed in a queue, and print files are generated asynchronously. In some cases, the process of creating such artifacts may take a long time.

If you do not need to automate the transfer of these files externally, your order fulfillment staff can simply go to the Customer's Canvas admin panel, find the corresponding project, and download the files manually. However, if you want to automatically extract these files from the system, Customer's Canvas supports two approaches to getting print files:

1. You can poll the created projects (or all those with a certain status) and check if the artifacts are ready. As soon as they are ready, download them.
2. You can configure the rendering pipeline to transfer files via FTP or HTTP request immediately after rendering is complete.

The first approach is described in the article Downloading artifacts for an order. Use this approach if rendering does not take a long time, and it is convenient for you to receive print files in the same order processor where you create projects.

For the second approach, examine the documentation on creating a pipeline. You may want to create an application that accepts files on your side.

Working with project statuses

Depending on your tasks, you will need to switch project statuses. This may be necessary to synchronize the order processing statuses in your order fulfillment system, or simply distinguish projects for which you have received print files from those that have not yet been processed.

Visualization of personalized orders

When you display a list of orders in your storefront admin panel, it may be convenient for you to show which orders have personalized data. This can be useful if you can order more than just personalized products in the storefront, and you have different processing procedures. In addition, the order fulfillment staff may want to view personalized designs without going to the Customer's Canvas when viewing orders.

Storefront

The beginning of personalization

• Every customer using your storefront needs to be registered in your Customer's Canvas account to create private storage of personalized data. To work with the customer's private storage, you will need to generate an access token. For more details, refer to the article Launching the personalization process.
• To provide a product for personalization, you will need to find a product variant by SKU or by a reference that links to your e-commerce product. For more details, refer to the article Associating products with designs.
• To open a product for personalization, you first need to determine which editors are provided for working with this product. These can Workflow Elements, UI Framework, Design Editor, Simple Editor, etc. The list and configuration of such tools is set in a personalization workflow. Depending on the workflow type, you can open the appropriate editor as described in the article Opening products for editing.

Saving personalization data to a cart

All editors have a certain button that stops the personalization process, like "Finish", "Add to cart", etc. For example, you can learn how to catch this event triggered by the Simple Editor in JavaScript and extract the ID of a personalized design.

Creating a personalized design in the editor is not enough in Customer's Canvas to make a purchase. It may take a long time between the moment when the buyer created the design and completed the payment, they may add more products to the order, etc. Therefore, before transferring design data to Customer's Canvas for processing, it is necessary to temporarily save links to these designs.

The organization of storing this data until the moment of purchase is entirely the responsibility of your system and its specific implementation strongly depends on its design. As a rule, e-commerce systems have the concept of a shopping cart, such a temporary order that is stored for some time for all users, including anonymous ones. Usually each product in it is represented by a line item, to which arbitrary data can be added as meta fields, for example, the ID of personalized designs.

The shopping cart is displayed in a special UI element. You can replace the standard product image with a personalized preview. It is also often possible to return to editing the design. Knowing the design ID, you can call the editor again and pass it.

Pay attention to the data retention policy in Customer's Canvas. When a file is created in the editor, it is considered temporary. By default, it will be deleted after 30 days. But when you put it in a project, it will be stored for as long as the project exists. By default, projects and artifacts are never deleted.

Creating an order confirmation page

On the page displaying the personalized product, the customer must confirm the result. Also, you may want to display general information about the order, such as the selected options and price.

Calculating the price

The cost calculation is based on the price calculation rules, which allow you to take into account various data (options, tags, SKU, etc.) of the product used to calculate the final cost of the product variant.

The discount is calculated based on the discount rules, which allow you to take into account various data (options, tags, SKU, etc.) of the product used to calculate the final discount on the product.