Printess pluginless Shopify integration

This document describes a way how to integrate the Printess Editor for personalized prodcuts into your shopify shop without installing any kind of plugin. This method only relies on Shopify standard ways of product configuration and on small modifications of the shops frontend theme. The unmodified "Dawn" standard theme is used inside this documentation. Steps required might be slightly different on modified theme versions or on other themes.

1) Creation of required product meta fields

Before making any changes on our themes, we need a way to distinguish „normal“ shopify products from printess products. We also need a way to map a printess template to a specific shopify product. Shopify provides Metafields as a way to add custom configurations to its products. We will create one metafield called templateName that will be used to map a specific product to a published printess product.

Go into the administration interface of your shop and open the meta field configuration:

Append a sales channel

Scroll down and find the „Metafields“ option. Select Products.

Where to find product meta fields

Click on „Add definition“ to create a new form field definition.

Where to find the add definitioon button

You have to create one field for the printess template name. The name property is the display name that is shown within the product configuration. Use Printess Template Name as Value.
„Namespace and key“ is the value that is IMPORTANT for the integration. This is the key that will be used to access the value from within the frontend. Use „printess“ as namespace and „templateName“ as key. The final value that needs to be written to „Namespace and key“ is „printess.templateName“. Its is important to use exactly this value.
„Description“ is the description that will be displayed inside the product configuration.

Values to enter:

Name: Printess Template Name
Namespace and key: printess.templateName
Description: The printess template name that should be used for this product

Select „Expose this metafield to Storefront API requests“ and click on "Select content type".

Where to select the content type

Use „Single line text“ as type and click on "Save".

Use single line text

Now, create a second meta data definition for the drop shipping configuration. This field contains the „Printess drop shipping product definition id“. The available ids (Product definitions) can be found inside your printess account portal under „Dropshippers“. Use „Dropshipping product definition id“ for name and „printess.productDefinitionId“ under „Namespace and key“. As description, add „(Integer value) -1: No dropshipping; 0: Use template settings; >0: Dropshipping product definition id“
Make sure that the value in „Namespace and key“ is correct. Shopify prefills this value with wrong values. Casing is important!

The field value type has to be set to Integer.

Set field value type to integer

2) Product configuration

Inside the shop configuration go to "Products" and open an existing one (or create a new one).

Opening a product

Inside the product configuration of the created ( / selected product), scroll down to the bottom where the meta fields section is located. Enter a name of an exsiting, published printess template.

Where to configure the printess template

Use "-1" for "dropshipping product definition id" (Disable dropshipping) and click on "Save"

3) Theme configuration

Go to the Administration interface of your shop and open the the theme editor (Online Store → Themes → Customize)

Where to find the shopify theme editor

Open the code editor.

How to open the shopify code editing

Download the and upload the 3 contained files to shopify (printesseditor.css, printesseditor.js, printessshopspecific.js)

where to find the add new asset button

Inside the "Add new asset" dialog, click on "Add file"

Where to find the file upload button

Do this for all 3 files inside the uploads folder (printesseditor.css, printesseditor.js, printessshopspecific.js)

You will need to provide the Printess „Shop- Token“ to the editor. Instead of hard coding this token into the sourcecode, it will be added as a theme setting. The shop token can then be changed in certain situations later on. To create a new Theme setting, open the file settings_schema.json (snippets folder).

Where to find the settings_schema.json file

Scroll to the bottom of the file. The last line’s content should be a closing JSON array tag „]“. Add a new line on top and paste in the content of the file settings_schema.json (snippets folder).

Location where the custom settings have to be added

Save the changes.
It is required to create a default value. For that, open the file settings_data.json (snippets folder) and paste the content into the „current“ json node:

Where to paste the shop token

Replace the token value with your own shop token. Save the changes on the file.

If you go back to the theme wysiwyg editor, and open the settings you should see the new printess setting at the bottom of the settings list:

The theme setttings inside the theme editor after adding custom settings

For printess products, the „Add to basket“ button has to be replaced with a customize button. Go back to code editing and open the „Sections folder“. Open the file „main-product.liquid“. A switch needs to be added whichdisplays the „Add to basket“ button on products that have no printess templateName set and add a „Customize“ button for products with a configured template name.

To make this work, some variables needs to be declared, that contain the templateName, some dropshipping Info and the flag that says if the current product is a printess product.

At the top of the „main-product.liquid“ file, you will find a „section“ definition. The first few childs of the section node "<section", are imports of external files. Copy the „Printess Variable Block“ from the file „CodeBlocks.txt“ (snippets folder) right below the external file imports:

Location where to paste the Printess Variable Block

Now you have to search for the „Add to basket button“. It is wrapped in a „buy_buttons“ block that is used by the theme wysiwyg editor. Look out for:

{%- when 'buy_buttons' -%}

That whole buy buttons block ends with the definition of the „rating block“:

{%- when 'rating' -%}

You have to hide all content of the „buy_buttons“ block into an if else switch that is hiding all contents for non printess products and showing the customize button instead for printess products.

Copy the contents of the „Printess Customize Button 1 Block“ that can be found inside the file „CodeBlocks.txt“ (snippets folder) right under the themes „buy_buttons“ block.

Location where to paste the Printess Customize Button 1 Block

Paste the contents of the „Printess Customize Button 2 Block“ that can be found inside the file „CodeBlocks.txt“ (snippets folder) right above the

{%- when 'rating' -%}


Location where to paste the Printess Customize Button 2 Block

Save the file changes.

The next step is to add a customize button to your shopping cart. Open the file „main-cart-items.liquid“

Inside the shopping basket view, the theme iterates through all shopping cart items and displays some additional information / controls like the thumbnail, product details, quantity selector etc. For printess products you will have to exchange the thumbnail and add the edit button to the product details section.

Search for the loop that iterates through all products and paste the contents of the „Printess Modify Button Block 1“ hat can be found inside the attached „CodeBlocks.txt“ right after the loop definition.

Location where to paste the Printess Modify Button Block 1

This block reads the printess product specific settings from the cart line item and makes them available to the liquid theme code.

Now search for the code that is responsible for displaying the thumbnail and add a switch that hides the standard thumbnail and displays the printess thumbnail. The thumbnail can be found inside the „cart-item__media“ block. Paste the code that can be found in „Printess Thumbnail Block 1“ inside the file „CodeBlocks.txt“ (snippets folder) right below the „cart-item__media“ block.

Location where to paste the Printess Thumbnail Block 1

Right after the inserted Printess „Thumbnail Block 1“, the theme is testing if the line item image exists.

Location of the if item.image theme code

You have to find the matching {% endif %} block and paste the contents of the „Printess Thumbnail Block 2“ inside the file „CodeBlocks.txt“ (snippets folder) right underneath.

Location where to paste the Printess Thumbnail Block 2

Within the product details block, the theme displays all property values of the cart line item that has been added by any kind of shopify integration. For Printess prodcuts, this block should be hidden and replaced with an edit button that reopens the Printess Editor and allows makign changes to designs that have been already added to the cart. Search for the foor loop that is iterating through all the cart line item properties and paste the contents of the "Printess Edit Button Block 1" which can be found at the file „CodeBlocks.txt“ (snippets folder) atop of the for loop {%- for property in -%}

Location where to paste the Printess Edit Button Block 1

The contents of the "Printess Edit Button Block 2" which can be found inside the file „CodeBlocks.txt“ (snippets folder) needs to be copied directly below the closing tag of the property for loop "{%- endfor -%}".

Location where to paste the Printess Edit Button Block 2

The last thing left to do, is loading the javascript helpers that have been uploaded to the assets section and initializing them.

Open the „theme.liquid“ file inside the „Layout“ folder.

Location of the theme.liquid file

Paste the „Printess Download Files Block“ inside the file „CodeBlocks.txt“ (snippets folder) somewhere in the html header definition of the theme. We added it right at the top after the „meta data“ that is specified by the original theme.

Location where to paste the Printess Download Files Block

Then scroll down to the bottom of the page. Search for the Body end tag "</body>" and paste the contents of the "Printess Initialization Block" inside the file „CodeBlocks.txt“ (snippets folder) above the end tag.

Location where to paste the Printess Initialization Block

4) Webhook registration

The last thing left to do is registering the order webhook so that the printess system is notified about new orders and can start producing the PDF’s of your personalized products. For this you will need to contact the printess support and ask for a order webhook key. After you have been provided with a key, you need to go to the „App and saleschannel settings“ of your shop administration.

Location of the Shopify App and sales channel settings

There, open the notification settings.

Location of the notification settings

And scroll to the bottom where you will find the web hooks configuration.

Location of the web hook settings

Click on „Create webhook“ and select „Order creation“ from the events and configure the format to be JSON:

Where to find the Order creation value for the event type setting

Inside the url setting, use the following url: You have to replace the xxxxxxxxxxx inside the url with the key that has been provided to you by the printess support. For Shopify Webhook API version select the current release version

Web hook configuration after filling out the values

Click on save. Now, shopify will display a „secret key“ that is being used to sign shopify requests and that is being used to verify that the webhook call is really done by the shopify system.

Location where the web hook secret key can be found

Provide this key to the Printess support and wait until you got the ok that the key has been added to your account. This completes the printess integration. After ordering a printess product, you should see the order and the produced pdf isnide the Printess account portal.

5) Hiding printess specific product settings from the buyer side

Newer versions of this pluginless integration prefix their product properties (templateName, thumbnailUrl, productDefinitionId etc) with an underscore. This is the standard way for shopify themes to hide these from being displayed on the buyer side. Pluginless soure codes that have been downloaded before mid January 2022 did not prefix their properties and therefore will display additional product properties inside the shopping basket and the order overview. The backend of the order webhook that is used for the pluginless version supports both versions, with and without underscore.

For older pluginless versions, open the file assets->printessshopspecific.js and find lines 25-27 and lines 44-46 that are responsible for writing these properties to the shopify basket items:

Code parts that have to be changed to hide the printess specific settings from the buer side

And prefix the keys (printessSaveToken, printessThumbnail and printessProductDefinitionId) with an underscore.

Screenshot of the code after the code changes have been applied

For most themes that honor shopify standard behaviours this is all needed to hide these properties from the buyer side for each product that is added to the basket from now on. In rare occassions, where themes do not honor these, you will have to find the code positions that are responsible for rendering these properties and manually prevent all properties that start with _printess from being rendered. On the Shopify standard theme Dawn, they can be found in the source editor in the following files: cart-notification-product.liquid, main-cart-items.liquid, main-order.liquid and cart-drawer.liquid.
In all files, the sourcecode for rendering the product properties looks similar. At first, a variable is assigned that contains the first character of the property name. In a second step, it is tested if this first character is an underscore. If not, it is not rendered.

Screenshot of the item loop

Above screenshot is taken from the file main-cart-items.liquid. All the listed liquid files listed above have the same sourcecode regarding these properties. In order to hide all properties that start with an underscore, just copy the sourcecode from the orignal theme shown above and use that.
{%- for property in -%} {%- assign property_first_char = property.first | slice: 0 -%} {%- if property.last != blank and property_first_char != '_' -%} <div class="product-option"> <dt>{{ property.first }}: </dt> <dd> {%- if property.last contains '/uploads/' -%} <a href="{{ property.last }}" class="link" target="_blank"> {{ property.last | split: '/' | last }} </a> {%- else -%} {{ property.last }} {%- endif -%} </dd> </div> {%- endif -%} {%- endfor -%}

For hiding printess properties only, this code can be modified to hide all properties that start with printess, replace the line
{%- assign property_first_char = property.first | slice: 0 -%}
With this line:
{%- assign startsWithPrintess = property.first | slice: 0,8 -%}

or for _printess with this line:
{%- assign startsWithPrintess = property.first | slice: 0,9 -%}

Then rewrite the check for underscore with the one for printess / _printess:

{%- if startsWithPrintess != 'printess' -%}
or _printess:
{%- if startsWithPrintess != '_printess' -%}

6) Fulfillment

In case your Printess account has fulfillments activated, we (Printess) need a shopify app token that is allowed to access and modify fulfillment information on your orders. You will need to create a private app inside your shop that has the following access scopes activated: 'read_fulfillments', 'write_fulfillments', 'read_assigned_fulfillment_orders', 'write_assigned_fulfillment_orders', 'read_merchant_managed_fulfillment_orders', 'write_merchant_managed_fulfillment_orders'

To create such a private app, head over to the apps "App and sales channel settings" inside the admin area of your shop.

Location of the apps and sales channel settings

Click on Develop apps on the top right side.

Location of the Develop apps button

Click on Create an app

Location of the Create an app button

Provide a name for the app.

Screenshot of the input field where the name has to be entered

Now click on "Configure Admin API scopes"

Location of the Configure Admin API scopes button

Select the following api scopes: 'read_fulfillments', 'write_fulfillments', 'read_assigned_fulfillment_orders', 'write_assigned_fulfillment_orders', 'read_merchant_managed_fulfillment_orders', 'write_merchant_managed_fulfillment_orders'

Screenshot of the read_assigned_fulfillment_orders and write_assigned_fulfillment_orders settings

Screenshot of the read_fulfillments and write_fulfillments settings

Screenshot of the read_merchant_managed_fulfillment_orders and write_merchant_managed_fulfillment_orders settings

Click on Save on the top right (bottom right) corner of the page.

Location of the save button

To receive an access token, the app needs to be installed on the current shop. Click on Install app on the top right corner.

Location of the Install app button

Click on Install

Loation of the save button

Shopify will now display the Admin API access token as well as the API key and secret key. In the Admin API access token section, click on reveal token once and copy it to your clipboard or write it down.

Location of the reveal token button

The token should start with shpat_. Now provide us with this token.

7) Output settings

It is possible to specify the format of the output file (pdf, png jpeg) as well as the output resolution in dpi (Dots per inch). To specify these output settings on product level, go to your shops administration and open your shop settings.

Location of teh apps and sales channel settings

Open the metafield settings for products and create 2 new meta definitions for output format and output dpi.

Location of the product metafield settings

Open the metafield settings for products and create 2 new meta definitions for output format and output dpi.

Location of the Add definition button

Screenshot of the output format metafield configuration

Screenshot of the output format metafield configuration

The settings for output format are:

Name Output Format
Namespace and key printess.outputFormat
Description The file output format (pdf, png, jpg)
Type Single line text

The settings for output resolution are:
Name Value
Name Output Resolution in DPI
Namespace and key printess.dpi
Description The file output resolution in dots per inch
Type Single line text

Go back to the store administration and open the theme code editing as shown in "3) Theme configuration" and open the file main-product.liquid.
Copy the code block <!------------- Printess Variable Block2 -------------> that can be found in the attached file „CodeBlocks.txt“ and place it directly under the code block <!------------- Printess Variable Block -------------> that has been placed in step "3) Theme configuration".

Screenshot of the Printess variable block location

Still inside the main-product.liquid file, search for <!------------- Printess Customize Button 2 Block -------------> and replace it with the latest (most up to date) <!------------- Printess Customize Button 2 Block -------------> that can be found inside the attached file „CodeBlocks.txt“

Screenshot of the Printess Customize Button 2 Block replacement

Now replace the file "printessshopspecific.js" that can be found inside the assets folder with the newest one available inside the package. Direct file link: printessshopspecific.js)

Screenshot of the location of the printessshopspecific.js file

In case you need to have global settings instead of product specific ones, you need to add some entries to the settingsdata.json that can be found inside the "Config" folder. Search vor the entry printess_shoptoken. Put a new line after that line and add the following entrys:
"printess_outputdpi": "300", "printess_outputformat": "pdf",

Screenshot of the output settings location

To output png or jpg images instead of pdf's replace "pdf" with "png" or "jpg"