Associating products with designs

11 minutes to read

So, you have registered an online store in your Customer's Canvas account, and a design team has created (or uploaded) several product designs in this online store. You can learn about the creation and upload process in the user guide.

To associate a product with a specific design, you must use the dedicated integration entities of Customer's Canvas: product specifications, product reference, and PIM products.

Then, you can work with products and designs through the Storefront APIs.

Product specifications

When we talk about the association of products with designs, we actually omit a lot of details. To correctly call the personalization tool for a specific product from an online store, you often need to define many more parameters than just the design ID. For example, you can specify the editor where personalization will be performed, the options available to the user, define a background image that helps to visualize the final result, and more.

To associate a product from an online store with a design, we set the binding of this product to a certain specification. A product specification defines a set of parameters that configure the personalization procedure:

an editor to open and UI Framework configuration,
a design to load as a product template,
product options available for the user,
and so on.

The specification is created in Customer's Canvas BackOffice for each product from the online store that will be personalized.

To create a new specification, on the main menu, click Product specifications and click Create new. Then, fill in the available fields according to the selected editor configuration.

StorefrontRegistration

At the moment, the product specification can only be created manually in Customer's Canvas BackOffice.

When binding the product to the specification, you can get a list of all the product specifications stored in the Customer's Canvas account by using the endpoint ProductSpecifications_GetAll.

curl -X \
  GET "https://api.customerscanvashub.com/api/storefront/v1/product-specifications" \
  -H  "accept: text/plain" \
  -H  "Authorization: Bearer <TOKEN>"

GET https://api.customerscanvashub.com/api/storefront/v1/product-specifications

var allProductSpecs = await productSpecificationsApiClient.GetAllAsync();

var allProductSpecs = _productSpecificationsApiClient.getAllProducts();

$allProductSpecs = $productSpecificationsApiClient->productSpecificationsGetAll();

Product references

Customer's Canvas provides a separate entity called product reference to ensure that the product in your online store is as independent as possible from the details of the binding to the specification. It provides a link between three elements — the store (storefrontId), the Customer's Canvas product (productId), and the product identifier in your online store (productReference), which is external to Customer's Canvas.

As a result, you can access the Storefront API endpoints by specifying only the product ID in the online store as the value of the reference field, and Customer's Canvas services will find the product using the binding entity.

We recommend creating product bindings programmatically using Storefront API endpoints. The scheme of creating a binding can be described as follows. In the admin panel of your online store, in the section related to managing the list of products, you need to implement the integration code for the selected product, which prompts you to:

Select a product from the list of available ones in your Customer's Canvas account.
Create a binding of the selected product to the selected specification.

Endpoints ProductReferences_Create, ProductReferences_Get, and ProductReferences_Delete provide a basic set of operations for managing product bindings.

Endpoint ProductReferences_GetAll allows you to get information about all currently available bindings in the specified online store. You can also filter the list by product specification ID and organize the paginated output.

curl -X \
  GET "https://api.customerscanvashub.com/api/storefront/v1/product-references?storefrontId=12&productReference=invitation" \
  -H  "accept: text/plain" \
  -H  "Authorization: Bearer <TOKEN>"

GET https://api.customerscanvashub.com/api/storefront/v1/product-references?storefrontId=12&productReference=invitation

var storefrontId = 12; // Set your storefront ID here
var productReference = "invitation"; // Set a reference
var productReferencePage = await productReferencesApiClient.GetAllAsync(storefrontId, productReference);

var storefrontId = 12; // Set your storefront ID here
var productReference = "invitation"; // Set a reference
var productReferencePage = _productReferencesApiClient.getAll(storefrontId, productReference);

$storefrontId = 12; // Set your storefront ID here
$productReference = "invitation"; // Set a reference
$productReferencePage = $productReferencesApiClient->productReferencesGetAll($storefrontId, $productReference);

Tip

Using an additional reference filter in ProductReferences_GetAll, you can organize one of the options for verifying the existence of a binding for the product. The result of performing such a search will always be successful, returning the number of elements found. If the number is 0, there are no bindings.

When the product binding is created, endpoints ProductReferences_GetProductSpecification and ProductReferences_GetProductConfig allow you to get the necessary data by product ID in the online store to start the personalization process.

curl -X \
  GET "https://api.customerscanvashub.com/api/storefront/v1/product-references/invitation/product-config?storefrontId=12" \
  -H  "accept: text/plain" \
  -H  "Authorization: Bearer <TOKEN>"

GET https://api.customerscanvashub.com/api/storefront/v1/product-references/invitation/product-config?storefrontId=12

var storefrontId = 12; // Set your storefront ID here
var productReference = "invitation"; // Set a reference
var workflow = await productReferencesApiClient.GetProductConfigAsync(productReference, storefrontId);

var storefrontId = 12; // Set your storefront ID here
var productReference = "invitation"; // Set a reference
var workflow = await _productReferencesApiClient.getProductConfig(productReference, storefrontId);

$storefrontId = 12; // Set your storefront ID here
$productReference = "invitation"; // Set a reference
$workflow = $productReferencesApiClient->productReferencesGetProductConfig($productReference, $storefrontId);

Customer's Canvas products

You can use another approach and configure a single product so that it represents a bunch of similar products in the online store that will be personalized. These Customer's Canvas products can also be created manually in your Customer's Canvas account. To create a new product, on the main menu, click Products and click Create new. Then, fill in the available fields as described in the Creating products topic.

Creating Customer's Canvas products.

According to this approach, you can use both product references and SKUs when working with products through the Storefront API - Products. Let's look at how you can perform basic operations.

Getting a product list

When binding the products, you can get a list of all the products in the Customer's Canvas account by using the endpoint Products_GetAllProducts. To do so, pass the tenantId query parameter. For example, for the tenant 12345:

curl -X \
  GET "https://api.customerscanvashub.com/api/storefront/v1/products?tenantId=12345" \
  -H  "accept: text/plain" \
  -H  "Authorization: Bearer <TOKEN>"

GET https://api.customerscanvashub.com/api/storefront/v1/products?tenantId=12345

var tenantId = 12345; // Set your tenant ID here
var allProducts = await productsApiClient.GetAllProductsAsync(tenantId: tenantId);

var tenantId = 12345; // Set your tenant ID here
var allProducts = _productsApiClient.getAllProducts(null, null, null, null, null, tenantId);

Note

The tenant ID is an optional parameter, since the API can determine this ID by the authorization token.

Finding a product by SKU

To filter products by SKU, you can use the same endpoint Products_GetAllProducts with the additional query parameter sku. Let's assume that your product in Customer's Canvas has SKU 10012:

curl -X \
  GET "https://api.customerscanvashub.com/api/storefront/v1/products?sku=10012" \
  -H  "accept: text/plain" \
  -H  "Authorization: Bearer <TOKEN>"

GET https://api.customerscanvashub.com/api/storefront/v1/products?sku=10012

var ecommerceSku = "10012"; // Set your SKU here
var productBySku = await productsApiClient.GetAllProductsAsync(sku: ecommerceSku);

var ecommerceSku = "10012"; // Set your SKU here
var productBySku = _productsApiClient.getAllProducts(null, null, null, null, ecommerceSku);

Note

If several products in your system have the same SKU, this endpoint will return one product that will be found first.

Finding a product by reference

You can also find a product by a reference that links to your e-commerce product. You specify these references through the user interface on the Links tab of a product in BackOffice.

The endpoint ProductReferences_Get allows you to get the list of all product references in a single storefront. For example, if the storefront ID is 10045:

curl -X \
  GET "https://api.customerscanvashub.com/api/storefront/v1/product-references/ext?storefrontId=10045" \
  -H  "accept: text/plain" \
  -H  "Authorization: Bearer <TOKEN>"

GET https://api.customerscanvashub.com/api/storefront/v1/product-references/ext?storefrontId=10045

var storefrontId = 10045; // Set your storefront ID here
var productReferences = await productsReferencesApiClient.GetAllAsync(storefrontId);

var storefrontId = 10045; // Set your storefront ID here
var productReferences = _productsReferencesApiClient.getAll(storefrontId);

Next, to find a product by reference, use the endpoint ProductReferences_Get and pass the identifiers of your storefront and reference. Let's assume that your e-commerce product has SKU "12345" and the storefront ID is 10045. In this case, the request will look as follows:

curl -X \
  GET "https://api.customerscanvashub.com/api/storefront/v1/product-references/ext/12345/product?storefrontId=10045" \
  -H  "accept: text/plain" \
  -H  "Authorization: Bearer <TOKEN>"

GET https://api.customerscanvashub.com/api/storefront/v1/product-references/ext/12345/product?storefrontId=10045

var reference = "12345"; // Set your refernce ID here
var storefrontId = 10045; // Set your storefront ID here
var productBySku = await productsApiClient.GetProductAsync(reference, storefrontId);

var reference = "12345"; // Set your refernce ID here
var storefrontId = 10045; // Set your storefront ID here
var productBySku = _productsApiClient.getProduct(reference, storefrontId);

Getting product options

The Storefront Products API allows you to retrieve a list of product options for all products using the endpoint Products_GetAllProductOptions. For example, this is how you can get the list of all product options defined in your tenant:

curl -X \
  GET "https://api.customerscanvashub.com/api/storefront/v1/products/options" \
  -H  "accept: text/plain" \
  -H  "Authorization: Bearer <TOKEN>"

GET https://api.customerscanvashub.com/api/storefront/v1/products/options

var allProductOptions = await productsApiClient.GetAllProductOptionsAsync();

var allProductOptions = _productsApiClient.getAllProductOptions();

To get an option list of a single product, use the endpoint Products_GetProductOptions. For example, you can get options of product 42 as follows:

curl -X \
  GET "https://api.customerscanvashub.com/api/storefront/v1/products/42/options" \
  -H  "accept: text/plain" \
  -H  "Authorization: Bearer <TOKEN>"

GET https://api.customerscanvashub.com/api/storefront/v1/products/42/options

var productId = 42; // Set your product ID here
var allProductOptions = await productsApiClient.GetProductOptionsAsync(productId);

var productId = 42; // Set your product ID here
var allProductOptions = _productsApiClient.getProductOptions(productId);

Getting variants for option values

After you have retrieved an option list, you may want to get product variants corresponding to these options.

A single product in your e-commerce system may have many options available to users. As a result, Customer's Canvas will create product variants that match all the possible combinations of option values. You can get all of these products by product ID through the Products_GetProductVariants endpoint. For example, if your productId is 42:

curl -X \
  GET "https://api.customerscanvashub.com/api/storefront/v1/products/42/variants" \
  -H  "accept: text/plain" \
  -H  "Authorization: Bearer <TOKEN>"

GET https://api.customerscanvashub.com/api/storefront/v1/products/42/variants

var productId = 42; // Set your product ID here
var variants = await productsApiClient.GetProductVariantsAsync(productId);

var productId = 42; // Set your product ID here
var variants = _productsApiClient.getProductVariants(productId);

To limit the variant list, you can apply an option value filter to the list. This filter is a string representing a JSON object, where the key is an option identifier, and the value is one or more comma-separated identifiers of option values. You can find these identifiers in the response of Products_GetProductOptions. For example, to filter variants by an option with ID 18894 and its value with ID 67221, use the following object:

{
  "18894": "67221"
}

Next, pass this filter as a query parameter in a GET request or as a parameter of the corresponding client method.

curl -X \
  GET "https://api.customerscanvashub.com/api/storefront/v1/products/42/variants?options=%7B%2218894%22%3A%20%2267221%22%7D" \
  -H  "accept: text/plain" \
  -H  "Authorization: Bearer <TOKEN>"

GET https://api.customerscanvashub.com/api/storefront/v1/products/42/variants?options=%7B%2218894%22%3A%20%2267221%22%7D

var productId = 42; // Set your product ID here
var filter = "{'18894': '67221'}"; // Set your option ID and option value ID here
var variants = await productsApiClient.GetProductVariantsAsync(id: productId, options: filter);

var productId = 42; // Set your product ID here
var filter = "{'18894': '67221'}"; // Set your option ID and option value ID here
var variants = _productsApiClient.getProductVariants(productId, null, null, null, filter);

Getting designs for a variant

After you have received the product variants, you will need to get assets for them to create your product gallery by using the endpoints Products_GetProductVariantDesigns and Products_GetProductVariantMockups.

For example, this is how you can get URLs that link to designs of a single product variant with ID 687078. Here, the product ID is 42.

curl -X \
  GET "https://api.customerscanvashub.com/api/storefront/v1/products/42/variant-designs?productVariantId=687078" \
  -H  "accept: text/plain" \
  -H  "Authorization: Bearer <TOKEN>"

GET https://api.customerscanvashub.com/api/storefront/v1/products/42/variant-designs?productVariantId=687078

var productId = 42; // Set your product ID here
var variantId = 687078; // Set the required variant ID here
var variants = await productsApiClient.GetProductVariantDesignsAsync(productId, null, variantId);

var productId = 42; // Set your product ID here
var variantId = 687078; // Set the required variant ID here
var variants = _productsApiClient.getProductVariantDesigns(productId, null, variantId);

The request to get URLs that link to mockups:

curl -X \
  GET "https://api.customerscanvashub.com/api/storefront/v1/products/42/variant-mockups?productVariantId=687078" \
  -H  "accept: text/plain" \
  -H  "Authorization: Bearer <TOKEN>"

GET https://api.customerscanvashub.com/api/storefront/v1/products/42/variant-mockups?productVariantId=687078

var productId = 42; // Set your product ID here
var variantId = 687078; // Set the required variant ID here
var variants = await productsApiClient.GetProductVariantMockupsAsync(productId, null, variantId);

var productId = 42; // Set your product ID here
var variantId = 687078; // Set the required variant ID here
var variants = _productsApiClient.getProductVariantMockups(productId, null, variantId);

Optimizing variant manipulations

The previous approach implies that you need to make API calls every time to switch product variants in your application. This may cause delays.

However, you can avoid this by using the endpoint Products_GetProductVariantDesigns with no restrictions on variants. The response will contain all the details about both variants and designs. In this case, you will get all the variants on the frontend at once, and then you will be able to implement a search for variants and quickly switch between them.

Note

When a product contains many product variants with many designs, Customer's Canvas may return so much data to the front end that the processing time will increase instead.

For example, this is how you can get URLs that link to the product variant designs. Here, the product ID is 42.

curl -X \
  GET "https://api.customerscanvashub.com/api/storefront/v1/products/42/variant-designs" \
  -H  "accept: text/plain" \
  -H  "Authorization: Bearer <TOKEN>"

GET https://api.customerscanvashub.com/api/storefront/v1/products/42/variant-designs

var productId = 42; // Set your product ID here
var variants = await productsApiClient.GetProductVariantDesignsAsync(productId);

var productId = 42; // Set your product ID here
var variants = _productsApiClient.getProductVariantDesigns(productId);

Next, let's learn about launching the personalization process.

Associating products with designs

Product specifications

Product references

Tip

Customer's Canvas products

Getting a product list

Note

Finding a product by SKU

Note

Finding a product by reference

Getting product options

Getting variants for option values

Getting designs for a variant

Optimizing variant manipulations

Note

Was this page helpful?