---
title: "Input | Customer's Canvas Hub"
canonical: "https://customerscanvas.com/docs/hub/dev-center/frontend-integration/workflow-elements/handy-editor/input/"
---

# Input

> The `input` object of the [editor configuration](https://customerscanvas.com/docs/hub/dev-center/frontend-integration/workflow-elements/handy-editor/initialization.md#3-provide-configuration-parameters) contains product properties for loading the editor. These properties allow you to retrieve products defined in Customer's Canvas in various ways. Let's take a look at them.

Conceptually, all types of inputs can be divided into the following:

- For opening designs without PIM
- For initialization using PIM data
- For recovery scenarios

## Decision flowchart

Choosing the right scenario depends on your integration type and what data you have. Use the flowchart below to find the correct approach:

```plantuml "Selecting Input parameters"
@startuml
top to bottom direction
skinparam RectangleBackgroundColor #f9f9f9

rectangle "Do you use PIM?" as A
rectangle "Working without PIM" as B
rectangle "Working with PIM" as C
rectangle "Known design ID?" as B1
rectangle "Public design template" as D
rectangle "Known private design ID?" as E
rectangle "Private design" as F
rectangle "Need external product link" as G
rectangle "Have external product ID\ne.g. Shopify/WooCommerce?" as C1
rectangle "Product reference" as H
rectangle "Known Customer's Canvas product ID" as I
rectangle "Ordering multiple variants\nwith quantities?" as I2
rectangle "Need to restore a saved design?" as I1
rectangle "Recovery using SKU" as J
rectangle "Recovery using variant ID" as K
rectangle "PIM data" as L
rectangle "Batch order" as M

A --> B : No
A --> C : Yes

B --> B1
B1 --> D : Yes
B1 --> E : No
E --> F : Yes
E --> G : No

C --> C1
C1 --> H : Yes
C1 --> I : No

I --> I2
I2 --> M : Yes
I2 --> I1 : No
I1 --> J : Yes, by SKU
I1 --> K : Yes, by variant ID
I1 --> L : No, start fresh
@enduml
```

:::important
If data in the `input` object is sufficient to initialize two or more scenarios, the first available scenario will be applied. At the same time, a warning will be logged to the console.
:::

## Data model overview

Each scenario serves a specific purpose and requires a certain set of properties:

| Scenario | Used for | Key properties |
| --- | --- | --- |
| Public template | Start from a reusable design template and mockups | `designTemplateId`, `previewMockups`, `mockup3dId` |
| Private design | Re-open a previously saved design | `designId`, `mockup3dId`, `previewMockupIds` |
| Product reference | Link by your e-commerce product ID (Shopify, WooCommerce, etc.) | `productReferenceId`, `designVariantFilter` |
| PIM data | Link by Customer's Canvas product ID (custom integrations) | `productId`, `productVariantId`, `variantDesignId`, `productVersionId` |
| Recovery by SKU | Resume editing using the product SKU | `sku`, `designId`, `productId`, `productVersionId` |
| Recovery by variant | Resume editing using the specific variant ID | `productVariantId`, `designId`, `productId`, `productVersionId` |
| Batch order | Order several variants of the same product with quantities | `productId`, `productVersionId`, `variants` |

Here is how the properties map to scenarios:

| Property | Public template | Private design | Product reference | PIM data | Recovery by SKU | Recovery by variant | Batch order |
| --- | --- | --- | --- | --- | --- | --- | --- |
| `designTemplateId` | **Required** | | | | | | |
| `designId` | | **Required** | | | **Required** | **Required** | |
| `mockup3dId` | Optional | Optional | | | | | |
| `previewMockups` | Optional | | | | | | |
| `previewMockupIds` (deprecated) | | Optional | | | | | |
| `productReferenceId` | | | **Required** | | | | |
| `productId` | | | Optional | **Required** | **Required** | **Required** | **Required** |
| `productVariantId` | | | | Optional | | **Required** | |
| `variantDesignId` | | | | Optional | | | |
| `productVersionId` | | | | Optional | **Required** | **Required** | Optional |
| `productFilterId` | | | | Optional | | | |
| `variants` | | | | | | | **Required** |
| `sku` | | | | | **Required** | | |
| `productLinkId` | | | | | Optional | Optional | |
| `designVariantTemplateId` | | | | | Optional | Optional | |
| `designVariantFilter` | | | Optional | Optional | | | |

:::note
The `previewMockupIds` property is deprecated. Use the `previewMockups` array instead.
:::

**Understanding the model:**

- A **product** in Customer's Canvas (`productId`) is a PIM entity with a catalog of **variants** (`productVariantId`) — each variant is a product variation with specific options (size, material, etc.).
- Each variant is linked to a **template** (`designTemplateId`) — the base design file loaded into the editor.
- When a user customizes a product, the editor creates a **private design** (`designId`) from that template, saving the user's edits.
- `designVariantFilter` applies [additional filtering](#filtering-designs) to designs, for example, by file name or by SKU.
- **Recovery** scenarios (`sku` or `productVariantId`) reconnect a private design to the original product version, restoring the full editing context (options, variant, applied changes).

## Working without PIM

### Public template and mockup

Use this scenario when PIM integration is unnecessary. That is, when you need to work directly with templates and mockups to group them into products or you may not implement an e-commerce scenario at all.

You can load an editor based on public data stored in your tenant. If needed, upload only a design template by its `designTemplateId`. You can also specify preview mockups in this definition. 3D mockups will be displayed in the viewer, and 2D mockups will appear on the approval screen. Depending on the mockup type, pass `mockup3dId` with a single ID or `previewMockups` with an array of IDs. These mockups must be saved in public storage.

The `input` object for providing public designs and mockups has the following properties:

- `designTemplateId` is the ID of a template stored in **Assets** > **Designs**. It's mandatory.
- `previewMockups` is an array of mockup IDs for the approval screen from **Assets** > **Mockups**.
- `mockup3dId` is a 3D mockup for the viewer from **Assets** > **Mockups**. It's passed only to `<au-handy-editor-3d />`, and if not specified, the 3D viewer will not be initialized.

A sample input of the Handy Editor with 2D preview mockups for the approval screen:

```js
const input = {
    // ID of a template stored in assets, mandatory.
    "designTemplateId": "61cd31a43056bcc33e919927",
    // Array of mockup IDs for the approval screen from Images.
    "previewMockups": [
        { "surfaceIndex": 0, "mockupId": "643d05f7c121897df4598271" },
        { "surfaceIndex": 1, "mockupId": "643d05fbc121897df4598277" }
    ] 
};
```

If the `surfaceIndex` field is not specified, the mockup will be used for all design pages.

A sample input of the Handy Editor 3D with mockups for the viewer:

```js
const input = {
    // ID of a template stored in assets, mandatory.
    "designTemplateId": "61cd31a43056bcc33e919927",
    // 3D mockup for the viewer from Mockups.
    "mockup3dId": "6527afc63507abfadd355226"
};
```

### Private design and mockup

When the user has already edited a design template, the customized design is saved in this user's private storage. If a design was generated through the Asset Generator service (parametric design use cases), it's also saved in private storage.

To access private storage, you will need the ID of the user who created the design and [that user's token](https://customerscanvas.com/docs/hub/dev-center/api/storefront/register-customers.md). Then, you can open the editor using the design ID.

You can also specify preview mockups in this definition. 3D mockups will be displayed in the viewer, and 2D mockups will appear on the approval screen. Depending on the mockup type, pass `mockup3dId` or `previewMockups`. We assume that these mockups are private.

The `input` object for providing private designs and mockups has the following properties:

- `designId` is the ID of a design customized by a user.
- `mockup3dId` is a private 3D mockup generated for the viewer through the [Asset Generator API](https://customerscanvas.com/docs/hub/dev-center/api/asset-generator.md).
- `previewMockups` is an array of mockup IDs for the approval screen.

This is how the `input` object may look like:

```js
const input = {
    "designId": "66bcc31cd39271a43cc3e919",  // ID of a design customized by a user.
    "mockup3dId": "6527afc63507abfadd355226" // Private 3D mockup generated for the viewer.
};
```

## Working with PIM

### Product reference

If you integrate Customer's Canvas with a standard e-commerce platform, like Shopify, you can load the editor based on a product ID from that system. In this scenario, Customer's Canvas uses the external product ID to link the product, as described in the [Product Links](https://customerscanvas.com/docs/hub/admin-guide/pim/products-links.md) article.

To load an editor, pass the `productReferenceId` to the `input`:

- `productReferenceId` is a product ID in an e-commerce system.
- `designVariantFilter` applies [additional filtering](#filtering-designs) to designs, for example, by file name or by SKU.

This is how you can define the `input` object to bind external products from a standard e-commerce system to Customer's Canvas products:

```js
const input = {
    "productReferenceId": "8255218868440", // External product ID.
};
```

### PIM data

Use this approach with custom e-commerce integrations, when an external system knows the product ID from Customer's Canvas PIM module. In this case, you create products in Customer's Canvas and receive a list of products in the admin panel of your store. No product link is required here.

The `input` object has the following properties:

- `productId` is a product ID in Customer's Canvas.
- `productVersionId` is a number of the saved product instance.
- `productVariantId` is a product variant ID. If skipped, all the variants will be obtained for managing in your application.
- `variantDesignId` is the ID of the original design that preselects a design variant within `productVariantId`. It works only when `productVariantId` is specified. If skipped, the editor uses the first design variant. If the ID is invalid, the editor raises an error event.
- `productFilterId` is a filter ID to apply to the obtained product variant list.
- `designVariantFilter` applies [additional filtering](#filtering-designs) to designs, for example, by file name or by SKU.

To load an editor, pass the `productId` and `productVariantId` to the `input`. Optionally, pass `variantDesignId` to preselect a design variant.

```js
const input = {
    "productId": 114,         // Product ID in Customer's Canvas.
    "productVersionId": 1011, // Number of the saved product instance.
    "productVariantId": 22698, // Product variant ID.
    "variantDesignId": "66bcc31cd39271a43cc3e919" // Original design ID to preselect a design variant.
};
```

### Batch order

Use this scenario for mass ordering, when a customer orders several variants of the same product in a single editor session. For example, ordering T-shirts of different colors and sizes at once. This input is a modification of the [PIM data](#pim-data) input.

The `input` object has the following properties:

- `productId` is a product ID in Customer's Canvas. It's mandatory.
- `productVersionId` is a number of the saved product instance. It's optional.
- `variants` is an array of variants to order. Each item contains the following properties:
  - `variantId` is a product variant ID in Customer's Canvas.
  - `quantity` is the number of items for this variant.

```js
const input = {
    "productId": 114,         // Product ID in Customer's Canvas.
    "productVersionId": 1011, // Number of the saved product instance. Optional.
    "variants": [
        { "variantId": 22698, "quantity": 10 },
        { "variantId": 22699, "quantity": 5 }
    ]
};
```

To display previews of product variants and allow users to switch the design variant, enable the [`assetLibrary.designVariants`](https://customerscanvas.com/docs/hub/dev-center/frontend-integration/workflow-elements/handy-editor/settings.md#assetlibrary) panel. This panel works only with the batch order input.

### Filtering designs

You can apply additional filtering to designs, for example, by file name, by folder, or by SKU.

The `designVariantFilter` used in the `input` supports the following filter types:

- `search` is a file name substring.
- `designCustomFields` is an object with key-value pairs defining a custom field with a required value.
- `designPath` is a substring of the folder path in asset store.
- `options` is an object with key-value pairs defining an option ID with an option value ID `{ opt_id: opt_value_id }`.
- `sku` is the product variant SKU.

This is how you can filter designs for a product variant by name and by custom fields.

```js
const input = {
    "productId": 114,
    "productVariantId": 22698,
    "designVariantFilter": {
        "search": "card",                        // Filter by file name containing "card".
        "designCustomFields": {"public": "true"} // Filter by custom fields.
    }
};
```

## Recovery strategies

Recovery scenarios are necessary when you need to restore the state of selected PIM options, design, and changes made to that design. This may be required in cases such as:

- Returning to editing from the cart.
- Complex scenarios where a template is edited in multiple editors sequentially.
- When a design was created using the API from variant resources.

Recovery scenarios are necessary if you need to open a design in the editor that was created in an external system based on PIM data or to reopen a design previously created in it.

:::note
In recovery scenarios, the `productVersionId` field is always mandatory. If missing, the editor will open the latest version of the product, which may not match the version in which the design was created.
:::

### Recovery using SKU

Recovery interface:

```js
const input = {
    "sku": "<product_sku>", // SKU of the product variant.
    "designId": "<private_design_id>", // Private design ID.
    "productId": 123, // Product ID.
    "productVersionId": 456, // Product version ID.
    "productLinkId": 789, // Optional: Product link ID.
    "designVariantTemplateId": "<public_design_id>" // Optional: Public design ID from which the Design Variant was created.
};
```

:::note
This scenario is not suitable for cases where different PIM variants reference the same SKU in the external system.
:::

### Recovery using variant ID

Recovery interface:

```js
const input = {
    "productVariantId": 123, // Product variant ID.
    "designId": "<private_design_id>", // Private design ID.
    "productId": 456, // Product ID.
    "productVersionId": 789, // Product version ID.
    "productLinkId": 1011, // Optional: Product link ID.
    "designVariantTemplateId": "<public_design_id>" // Optional: Public design ID from which the Design Variant was created.
};
```

### Note on the designVariantTemplateId field

The optional field `designVariantTemplateId` is used to indicate to the editor from which design variant the provided `designId` was created. Currently, the Handy Editor does not use this information, but it may be necessary to indicate the selected design variant in the user interface, similar to the Simple Editor.

If you initialize the editor with a template previously created in the Handy Editor, you can pass the `event.detail.designVariantTemplateId` field from the `addtocart` event.

If you created the design via the API, you can use the information from the `/api/storefront/v1/products/{id}/variant-designs` endpoint. The `designId` field of the variant you need is what you require for this case.