Creating Virtual Products Using GraphQL

The createVirtualProductsFromArtwork GraphQL mutation provides a way to create multiple virtual products, programmatically, in a single API call.

The mutation takes a list of blank product IDs, one or more artwork URL’s and a target product category ID and creates and returns the details of one or more virtual products.

So a request that has 5 blank product ID’s and 5 artwork URL’s would create and return the details of 25 virtual products.

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.create`

Example Response

JSON

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

Oauth User Requirements

To make the createVirtualProductsFromArtwork request to the GraphQL API, the oauth user must have:

Read access to the categories that the products listed in the baseProducts variable, are assigned to.
Write access to the target category specified in the categoryId variable.
The products.customisable.create user permission enabled.

The Create Virtual Products from Artwork GraphQL Mutation

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

We will be making a POST request to the https://cpp.custom-gateway.net/v2/product-manager/products-graphql 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 including 2 base products and 2 pieces of artwork, which will create 4 virtual products and return the following information about each of the 4 products.

Product ID
Product Ref (This reference can be prefixed with “P-” to give a print on demand reference that can be used in the submission of item type 3 in the Order API. For example, “P-643374A6E2C4385“. A description of this item type can be found here).
Name
Retail SKU
Various snapshots

However, the GraphQL API call can return numerous other pieces of information about the product, details of which, can be found in the schema here - https://developers-v2.custom-gateway.net/graphql/product.doc.html

Example Mutation

JSON

mutation ($baseProducts: [ID]!, $categoryId: ID!, $artwork: [CreateVirtualProductsFromArtworkArtwork]!)
  {
    createVirtualProductsFromArtwork(baseProducts: $baseProducts, categoryId: $categoryId, artwork: $artwork)
    {
        id
        ref
        name
        retail_sku
        snapshots
        {
            super_large
            extra_large
            large
            medium
            small
            extra_small
        }
    }
  }

Variables

The mutation contains references to 3 variables - $baseProducts, $categoryId and $artwork. Descriptions of these variables can be found in the table below.

Variable Descriptions

Variable

Type

Description

baseProducts

[ID]!

A collection of base product IDs.

categoryId

ID!

The ID of the target product category into which the new virtual products will be created.

artwork

CreateVirtualProductsFromArtworkArtwork

A collection of artwork objects.

Each artwork object has a:

design name
preview URL (used in live preview smartlinks)
full size URL (using for artwork generation)

Example Variables

JSON

{
   "baseProducts":[
      11330713, 9817445
   ],
   "categoryId":20097,
   "artwork":[
      {
         "design_name":"Army Print",
         "urls":[
            {
               "preview":"https://s3-eu-west-1.amazonaws.com/user-images-gateway3d-com/user-images/0f34/6511/9dcb/d926/624b/7b12/e625/413b/e254/1bcb/b445/7369/16d6/1ca4/3441/4195-original.jpg",
               "original":"https://s3-eu-west-1.amazonaws.com/user-images-gateway3d-com/user-images/0f34/6511/9dcb/d926/624b/7b12/e625/413b/e254/1bcb/b445/7369/16d6/1ca4/3441/4195-original.jpg"
            }
         ]
      },
      {
         "design_name":"Fruit Print",
         "urls":[
            {
               "preview":"https://s3-eu-west-1.amazonaws.com/user-images-gateway3d-com/user-images/52d8/2cf7/b89d/8fc2/b969/bdb3/aea9/b9bb/0d32/a14c/0c2d/9f88/0d3b/c435/300b/305b-original.jpg",
               "original":"https://s3-eu-west-1.amazonaws.com/user-images-gateway3d-com/user-images/52d8/2cf7/b89d/8fc2/b969/bdb3/aea9/b9bb/0d32/a14c/0c2d/9f88/0d3b/c435/300b/305b-original.jpg"
            }
         ]
      }
   ]
}

Response

A successful request will return the details of the virtual products that were created. For the example we have been working with, the response data can be viewed below.

Example response

JSON

{
    "data": {
        "createVirtualProductsFromArtwork": [
            {
                "id": 11669052,
                "ref": "BE468BF0328F6C6",
                "name": "Army Print - Ladies' Heavy Cotton T-Shirt",
                "retail_sku": "5000L-PSTEST-11669052",
                "snapshots": {
                    "super_large": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/BE468BF0328F6C6/snapshot/super-large.jpg",
                    "extra_large": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/BE468BF0328F6C6/snapshot/extra-large.jpg",
                    "large": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/BE468BF0328F6C6/snapshot/large.jpg",
                    "medium": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/BE468BF0328F6C6/snapshot/medium.jpg",
                    "small": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/BE468BF0328F6C6/snapshot/small.jpg",
                    "extra_small": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/BE468BF0328F6C6/snapshot/extra-small.jpg"
                }
            },
            {
                "id": 11669053,
                "ref": "21ED4FA421C8C46",
                "name": "Fruit Print - Ladies' Heavy Cotton T-Shirt",
                "retail_sku": "5000L-PSTEST-11669053",
                "snapshots": {
                    "super_large": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/21ED4FA421C8C46/snapshot/super-large.jpg",
                    "extra_large": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/21ED4FA421C8C46/snapshot/extra-large.jpg",
                    "large": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/21ED4FA421C8C46/snapshot/large.jpg",
                    "medium": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/21ED4FA421C8C46/snapshot/medium.jpg",
                    "small": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/21ED4FA421C8C46/snapshot/small.jpg",
                    "extra_small": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/21ED4FA421C8C46/snapshot/extra-small.jpg"
                }
            },
            {
                "id": 11669054,
                "ref": "5242E5EDC950598",
                "name": "Army Print - Pullover Hoodie for Adults – Customized",
                "retail_sku": "97200-PSTEST-11669054",
                "snapshots": {
                    "super_large": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/5242E5EDC950598/snapshot/super-large.jpg",
                    "extra_large": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/5242E5EDC950598/snapshot/extra-large.jpg",
                    "large": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/5242E5EDC950598/snapshot/large.jpg",
                    "medium": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/5242E5EDC950598/snapshot/medium.jpg",
                    "small": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/5242E5EDC950598/snapshot/small.jpg",
                    "extra_small": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/5242E5EDC950598/snapshot/extra-small.jpg"
                }
            },
            {
                "id": 11669055,
                "ref": "643374A6E2C4385",
                "name": "Fruit Print - Pullover Hoodie for Adults – Customized",
                "retail_sku": "97200-PSTEST-11669055",
                "snapshots": {
                    "super_large": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/643374A6E2C4385/snapshot/super-large.jpg",
                    "extra_large": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/643374A6E2C4385/snapshot/extra-large.jpg",
                    "large": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/643374A6E2C4385/snapshot/large.jpg",
                    "medium": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/643374A6E2C4385/snapshot/medium.jpg",
                    "small": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/643374A6E2C4385/snapshot/small.jpg",
                    "extra_small": "https://s3-eu-west-1.amazonaws.com/generated-assets-gateway3d-com/product/643374A6E2C4385/snapshot/extra-small.jpg"
                }
            }
        ]
    }
}