Create Virtual Products from Blanks, Targeting Specific Print Areas

The createVirtualsFromBlanks GraphQL mutation provides a way to create multiple virtual products, programmatically, in a single API call. The mutation is similar to the createVirtualProductsFromArtwork mutation but provides additional functionality such as targeting specific print areas with the artwork, defining the fit mode that will be used and the artwork type.

There are 3 requests involved in this process. In the first request createVirtualsFromBlanks, details of the blank products, the artworks and the print areas the artworks should be applied to, are provided. This results in a UUID being returned.

That UUID can then be used in a subsequent mutation pollAsyncTask, to poll the API and get updates on the progress of the request. The IDs of the new virtual products are provided when the status field of the response has the value “COMPLETED”.

Finally, a products request using the IDs returned in the result field of the pollAsyncTask response, will return data from the new virtual products we’ve created.

Authentication

The GraphQL API uses OAuth authentication. A request for an OAuth token is made to the OAuth endpoint, which returns an access token. This token can then be used in requests made to the GraphQL API endpoint.

To make a request for a token, you will require an OAuth user to be set up in the Kornit^X platform. The user will require specific access and permissions depending on the API request. The permissions required for this request can be found in the “OAuth User Requirements” section below.

If you don’t have an OAuth user set up, please contact the support team, who will be happy to help. The support team will set up the OAuth user in the Kornit^X platform for you and supply you with the OAuth user client ID and client secret. These credentials can then be used to obtain a token from the OAuth token endpoint.

OAuth Token Endpoint - https://oauth.kornitx.net/token

The OAuth token can be obtained by making a POST to the above endpoint. The request type for the OAuth token is x-www-form-urlencoded and must include the following form keys and values.

Key	Value
`client_id`	The client ID of the OAuth user provided by the support team.
`client_secret`	The client secret of the OAuth user provided by the support team.
`grant_type`	`client_credentials`
`scope`	`products.customisable.list`

For the createVirtualsFromBlanks and pollAsyncTask requests, the value of scope can be empty when requesting an OAuth token. The requests only requires the OAuth user to have access to the relevant categories. However, we will later be making a request using the products GraphQL query, which does require the products.customisable.list permission.

Example Response

CODE

{"token_type":"Bearer","expires_in":3600,"access_token":"..."}

OAuth User Requirements

To make the createVirtualsFromBlanks , pollAsyncTask and products requests to the GraphQL API, the OAuth user must have:

Read access to the categories that the blank products are assigned to.
Write access to the target category specified in the categoryId variable.
The products.customisable.list permission enabled on the OAuth user.

The Create Virtuals From Blanks GraphQL Mutation

Now we have the access token, we can now make the createVirtualsFromBlanks request.

We will be making a POST request to the https://graphql.kornitx.net endpoint.

The request will have 2 headers listed below.

Content-Type: “application/json”

Authorization: “Bearer [OAUTH_ACCESS_TOKEN]“

[OAUTH_ACCESS_TOKEN] should be replaced by the access token that was returned when we made the token request to the https://oauth.kornitx.net/token endpoint.

Mutation

In this example, we will be using 2 blank products and and creating 3 virtual products from each, giving us a total of 6 virtual products. The 3 virtual products that are created from each blank will consist of a front and back print, a front only print and a back only print.

Example createVirtualsFromBlanks Mutation

GRAPHQL

mutation($specs: [KansasCatalog_CreateVirtualsFromBlanks_VirtualSpec]!, $categoryId: ID!) {
	c: kansas_catalog {
		m: createVirtualsFromBlanks(specs: $specs, targetCategoryId: $categoryId) {
			uuid
		}
	}
}

Variables

The mutation contains references to 2 variables - $categoryId and $specs. Descriptions of these variables can be found in the tables below.

Variable	Type	Description
`specs`	`[KansasCatalog_CreateVirtualsFromBlanks_VirtualSpec]!`	A collection of `spec` objects, each containing a `blank_product_id` and an `artworks` array. This is where we specify the blank products and the artwork that will be applied for the new virtual products we are creating.
`categoryId`	`ID!`	The ID of the target product category into which the new virtual products will be created.

The `specs` Object

Key	Type	Description
`artworks`	`Array`	A collection of `artwork` objects. Each `artwork` object will create a new virtual product, using the `blank_product_id` found within the same `spec` object that the `artworks` array belongs to.
`blank_product_id`	`Int`	The ID of the blank product that will be used to create the virtual products.

The `artwork` Object

Key	Type	Description
`urls`	`Array`	The `urls` array contains one or more `url` objects, each one defining the artwork to be applied, the print area it should be applied to, the fit mode, as well as the artwork type.
`design_name`	`String`	The design name given to the new virtual product.

The `url` Object

Key	Type	Description
`original`	`String`	URL to the full sized artwork.
`preview`	`String`	URL to the artwork preview suitable for use in Smartlink (i.e. original scaled to max 800x800 with locked aspect ratio).
`fit_mode`	`Int`	0 (cover) or 1 (contain)
`type`	`String`	The artwork type - `raster`, `vrbtim` (verbatim) or `vector`.
`target_surface_area`	`String`	The name of the print area that the artwork should be applied to. i.e. Front, Back, Neck etc.

Example Variables

JSON

{
	"specs": [
		{
			"blank_product_id": 10062664,
			"artworks": [
				{
                    "design_name": "T-Shirt Front & Back Print",
					"urls": [
						{
							"original": "https://s3-eu-west-1.amazonaws.com/user-images-gateway3d-com/user-images/04cb/78ea/6589/8784/9d73/6749/0830/10a5/3856/2a7b/5cd5/5116/f396/2f3b/cdae/da6c-original.jpg",
							"preview": "https://s3-eu-west-1.amazonaws.com/user-images-gateway3d-com/user-images/d3a4/8f77/fa48/69de/2574/1b05/2065/b814/1672/aeff/0b55/f00b/aecd/5a87/bfb4/e247-original.jpg",
							"fit_mode": 1,
							"type": "raster",
							"target_surface_area": "Front"
						},

						{
							"original": "https://s3-eu-west-1.amazonaws.com/user-images-gateway3d-com/user-images/84ff/fbf1/b4ad/444c/8c31/90a5/a834/71d6/70a7/8105/e958/dff2/2b0f/ac3f/869f/01ac-original.jpg",
							"preview": "https://s3-eu-west-1.amazonaws.com/user-images-gateway3d-com/user-images/c3b9/4a5b/52f1/45a2/be3a/b4de/5e52/1b6d/10a5/e600/2999/b422/3f7b/2d04/3a21/9c1b-original.jpg",
							"fit_mode": 0,
							"type": "raster",
							"target_surface_area": "Back"
						}
					]
				},
                {
                    "design_name": "T-Shirt Front Print Only",
					"urls": [
						{
							"original": "https://s3-eu-west-1.amazonaws.com/user-images-gateway3d-com/user-images/04cb/78ea/6589/8784/9d73/6749/0830/10a5/3856/2a7b/5cd5/5116/f396/2f3b/cdae/da6c-original.jpg",
							"preview": "https://s3-eu-west-1.amazonaws.com/user-images-gateway3d-com/user-images/d3a4/8f77/fa48/69de/2574/1b05/2065/b814/1672/aeff/0b55/f00b/aecd/5a87/bfb4/e247-original.jpg",
							"fit_mode": 1,
							"type": "raster",
							"target_surface_area": "Front"
						}
					]
				},
                {
                    "design_name": "T-Shirt Back Print Only",
					"urls": [
						{
							"original": "https://s3-eu-west-1.amazonaws.com/user-images-gateway3d-com/user-images/84ff/fbf1/b4ad/444c/8c31/90a5/a834/71d6/70a7/8105/e958/dff2/2b0f/ac3f/869f/01ac-original.jpg",
							"preview": "https://s3-eu-west-1.amazonaws.com/user-images-gateway3d-com/user-images/c3b9/4a5b/52f1/45a2/be3a/b4de/5e52/1b6d/10a5/e600/2999/b422/3f7b/2d04/3a21/9c1b-original.jpg",
							"fit_mode": 0,
							"type": "raster",
							"target_surface_area": "Back"
						}
					]
				}
			]
		},
        {
			"blank_product_id": 14846662,
			"artworks": [
				{
                    "design_name": "Hoodie Front & Back Print",
					"urls": [
						{
							"original": "https://s3-eu-west-1.amazonaws.com/user-images-gateway3d-com/user-images/04cb/78ea/6589/8784/9d73/6749/0830/10a5/3856/2a7b/5cd5/5116/f396/2f3b/cdae/da6c-original.jpg",
							"preview": "https://s3-eu-west-1.amazonaws.com/user-images-gateway3d-com/user-images/d3a4/8f77/fa48/69de/2574/1b05/2065/b814/1672/aeff/0b55/f00b/aecd/5a87/bfb4/e247-original.jpg",
							"fit_mode": 1,
							"type": "raster",
							"target_surface_area": "Front"
						},

						{
							"original": "https://s3-eu-west-1.amazonaws.com/user-images-gateway3d-com/user-images/84ff/fbf1/b4ad/444c/8c31/90a5/a834/71d6/70a7/8105/e958/dff2/2b0f/ac3f/869f/01ac-original.jpg",
							"preview": "https://s3-eu-west-1.amazonaws.com/user-images-gateway3d-com/user-images/c3b9/4a5b/52f1/45a2/be3a/b4de/5e52/1b6d/10a5/e600/2999/b422/3f7b/2d04/3a21/9c1b-original.jpg",
							"fit_mode": 0,
							"type": "raster",
							"target_surface_area": "Back"
						}
					]
				},
                {
                    "design_name": "Hoodie Front Print Only",
					"urls": [
						{
							"original": "https://s3-eu-west-1.amazonaws.com/user-images-gateway3d-com/user-images/04cb/78ea/6589/8784/9d73/6749/0830/10a5/3856/2a7b/5cd5/5116/f396/2f3b/cdae/da6c-original.jpg",
							"preview": "https://s3-eu-west-1.amazonaws.com/user-images-gateway3d-com/user-images/d3a4/8f77/fa48/69de/2574/1b05/2065/b814/1672/aeff/0b55/f00b/aecd/5a87/bfb4/e247-original.jpg",
							"fit_mode": 1,
							"type": "raster",
							"target_surface_area": "Front"
						}
					]
				},
                {
                    "design_name": "Hoodie Back Print Only",
					"urls": [
						{
							"original": "https://s3-eu-west-1.amazonaws.com/user-images-gateway3d-com/user-images/84ff/fbf1/b4ad/444c/8c31/90a5/a834/71d6/70a7/8105/e958/dff2/2b0f/ac3f/869f/01ac-original.jpg",
							"preview": "https://s3-eu-west-1.amazonaws.com/user-images-gateway3d-com/user-images/c3b9/4a5b/52f1/45a2/be3a/b4de/5e52/1b6d/10a5/e600/2999/b422/3f7b/2d04/3a21/9c1b-original.jpg",
							"fit_mode": 0,
							"type": "raster",
							"target_surface_area": "Back"
						}
					]
				}
			]
		}
	],

	"categoryId": 20097
}

Response

A successful request will return the UUID of the virtual product creation task. For the example we have been working with, the response data can be viewed below.

Example response

JSON

{
    "data": {
        "c": {
            "m": {
                "uuid": "1a8e1f8e-f3a0-4366-9b0e-b8130483a921"
            }
        }
    }
}

Polling the Async Task Using the UUID

Now we have the UUID, we can use it to make the pollAsyncTask request, and check the status of the virtual product creation process.

We will again be making a POST request to the https://graphql.kornitx.net endpoint.

The request will have 2 headers listed below.

Content-Type: “application/json”

Authorization: “Bearer [OAUTH_ACCESS_TOKEN]“

[OAUTH_ACCESS_TOKEN] should be replaced by the access token that was returned when we made the token request to the https://oauth.kornitx.net/token endpoint.

The same OAuth access token used in the previous request can be used for this request, assuming it hasn’t yet expired.

Example pollAsyncTask Mutation

GRAPHQL

mutation($uuid: Uuid!) {
	core {
		t: pollAsyncTask(uuid: $uuid) {
			status
			result
			progress_datetime
			progress_message
		}
	}
}

Variables

The mutation contains a reference to a single variable - $uuid. A description of that variable can be found in the table below.

Variable	Type	Description
`uuid`	`Uuid!`	The unique ID of the virtual product creation task.

Example Variables

JSON

{
    "uuid":"1a8e1f8e-f3a0-4366-9b0e-b8130483a921"
}

Response

A successful request will return details of the current status of the virtual product creation task. For the example we have been working with, the response data can be viewed below.

Example response

JSON

{
    "data": {
        "core": {
            "t": {
                "status": "COMPLETED",
                "result": "[15755385,15755386,15755387,15755388,15755389,15755390]",
                "progress_datetime": "2024-09-19 08:59:45",
                "progress_message": "Created 6 products so far..."
            }
        }
    }
}

The Response Fields

Key	Type	Description
`status`	`String`	The current status of the task.
`result`	`String`	A list of virtual product IDs created by the task.
`progress_datetime`	`String`	The current date and time (UTC).
`progress_message`	`String`	A message relating to the status of the task.

Retrieving the Product Data of the New Virtual Products

We can now use the list of product IDs returned in the result field of the pollAsyncTask response data, to fetch details of the new virtual products.

We will be making another POST request to the https://graphql.kornitx.net endpoint.

The request will have 2 headers listed below.

Content-Type: “application/json”

Authorization: “Bearer [OAUTH_ACCESS_TOKEN]“

[OAUTH_ACCESS_TOKEN] should be replaced by the access token that was returned when we made the token request to the https://oauth.kornitx.net/token endpoint.

The same OAuth access token used in the previous request can be used for this request, assuming it hasn’t yet expired.

Example products Query

GRAPHQL

query ($page: Int!, $filter: Json!) {
  core {
    products(filter: $filter, page: $page, count: 1000) {
      items {
        id
        name
        retail_sku
        snapshots {
            extra_small
            small
            medium
            large
            extra_large
            super_large
        }
      }
    }
  }
}

Variables

The query contains a reference to 2 variables - $filter which we will use to filter to the new virtual products we’ve created, and $page to define the page number.

Example Variables

JSON

{
    "filter": {
        "id:in": [15755385,15755386,15755387,15755388,15755389,15755390]
    },
    "page": 1
}

Response

A successful request will return the id, name, retail_sku as well as various snapshots of each new virtual product.

Example response

JSON

{
    "data": {
        "core": {
            "products": {
                "items": [
                    {
                        "id": 15755385,
                        "name": "T-Shirt Front & Back Print - AWDis Hooded Sweatshirt",
                        "retail_sku": "Jh001-PSTEST-15755385",
                        "snapshots": {
                            "extra_small": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/EDDDB7866D6F8EE/snapshot/extra-small.jpg",
                            "small": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/EDDDB7866D6F8EE/snapshot/small.jpg",
                            "medium": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/EDDDB7866D6F8EE/snapshot/medium.jpg",
                            "large": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/EDDDB7866D6F8EE/snapshot/large.jpg",
                            "extra_large": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/EDDDB7866D6F8EE/snapshot/extra-large.jpg",
                            "super_large": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/EDDDB7866D6F8EE/snapshot/super-large.jpg"
                        }
                    },
                    {
                        "id": 15755386,
                        "name": "T-Shirt Front Print Only - AWDis Hooded Sweatshirt",
                        "retail_sku": "Jh001-PSTEST-15755386",
                        "snapshots": {
                            "extra_small": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/9ADB32FE60C9E55/snapshot/extra-small.jpg",
                            "small": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/9ADB32FE60C9E55/snapshot/small.jpg",
                            "medium": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/9ADB32FE60C9E55/snapshot/medium.jpg",
                            "large": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/9ADB32FE60C9E55/snapshot/large.jpg",
                            "extra_large": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/9ADB32FE60C9E55/snapshot/extra-large.jpg",
                            "super_large": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/9ADB32FE60C9E55/snapshot/super-large.jpg"
                        }
                    },
                    {
                        "id": 15755387,
                        "name": "T-Shirt Back Print Only - AWDis Hooded Sweatshirt",
                        "retail_sku": "Jh001-PSTEST-15755387",
                        "snapshots": {
                            "extra_small": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/47080C70B915BCE/snapshot/extra-small.jpg",
                            "small": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/47080C70B915BCE/snapshot/small.jpg",
                            "medium": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/47080C70B915BCE/snapshot/medium.jpg",
                            "large": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/47080C70B915BCE/snapshot/large.jpg",
                            "extra_large": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/47080C70B915BCE/snapshot/extra-large.jpg",
                            "super_large": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/47080C70B915BCE/snapshot/super-large.jpg"
                        }
                    },
                    {
                        "id": 15755388,
                        "name": "Hoodie Front & Back Print - HFT71 - Value Unisex Pullover Hoodie",
                        "retail_sku": "VALUE-UNISEX-HOODIE-GFN-PSTEST-15755388",
                        "snapshots": {
                            "extra_small": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/AFDC92E84ACA49C/snapshot/extra-small.jpg",
                            "small": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/AFDC92E84ACA49C/snapshot/small.jpg",
                            "medium": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/AFDC92E84ACA49C/snapshot/medium.jpg",
                            "large": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/AFDC92E84ACA49C/snapshot/large.jpg",
                            "extra_large": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/AFDC92E84ACA49C/snapshot/extra-large.jpg",
                            "super_large": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/AFDC92E84ACA49C/snapshot/super-large.jpg"
                        }
                    },
                    {
                        "id": 15755389,
                        "name": "Hoodie Front Print Only - HFT71 - Value Unisex Pullover Hoodie",
                        "retail_sku": "VALUE-UNISEX-HOODIE-GFN-PSTEST-15755389",
                        "snapshots": {
                            "extra_small": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/08E3FECFE68A646/snapshot/extra-small.jpg",
                            "small": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/08E3FECFE68A646/snapshot/small.jpg",
                            "medium": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/08E3FECFE68A646/snapshot/medium.jpg",
                            "large": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/08E3FECFE68A646/snapshot/large.jpg",
                            "extra_large": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/08E3FECFE68A646/snapshot/extra-large.jpg",
                            "super_large": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/08E3FECFE68A646/snapshot/super-large.jpg"
                        }
                    },
                    {
                        "id": 15755390,
                        "name": "Hoodie Back Print Only - HFT71 - Value Unisex Pullover Hoodie",
                        "retail_sku": "VALUE-UNISEX-HOODIE-GFN-PSTEST-15755390",
                        "snapshots": {
                            "extra_small": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/D94A61FBBE12FE0/snapshot/extra-small.jpg",
                            "small": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/D94A61FBBE12FE0/snapshot/small.jpg",
                            "medium": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/D94A61FBBE12FE0/snapshot/medium.jpg",
                            "large": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/D94A61FBBE12FE0/snapshot/large.jpg",
                            "extra_large": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/D94A61FBBE12FE0/snapshot/extra-large.jpg",
                            "super_large": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/D94A61FBBE12FE0/snapshot/super-large.jpg"
                        }
                    }
                ]
            }
        }
    }
}

Authentication

OAuth User Requirements

The Create Virtuals From Blanks GraphQL Mutation

Mutation

Variables

The specs Object

The artwork Object

The url Object

Response

Polling the Async Task Using the UUID

Variables

Response

The Response Fields

Retrieving the Product Data of the New Virtual Products

Variables

Response

The `specs` Object

The `artwork` Object

The `url` Object