This document describes a way on how to integrate the Printess Editor for personalized produts 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.
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:
Scroll down and find the „Metafields“ option. Select Products.
Click on „Add definition“ to create a new form field definition.
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”.
Use “Single line text” as type and click on “Save”.
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.
By creating additional definitions for “printess.dpi” (integer) or “printess.outputformat” (single line text, supported values pdf, png, jpg) you can add additional options for controlling the output dpi and the file format of the produced files after an order.
Inside the shop configuration go to “Products” and open an existing one (or create a new one).
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.
Use “-1” for “dropshipping product definition id” (Disable dropshipping) and click on “Save”
Go to the Administration interface of your shop and open the the theme editor (Online Store → Themes → Customize)
Open the code editor.
Download the 3 files printesseditor.css, printesseditor.js and printessshopspecific.js from the printess pluginless gist and upload all 3 to the shoppify theme assets:
Inside the “Add new asset” dialog, click on “Add file”
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 (config folder).
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
Save the changes. It is mandatory to create a default value. For that, inside the theme code editor, open the file settings_data.json and paste the content of the settings_data.json into the „current“ json node:
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:
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 which displays the “Add to basket” button on products that have no printess.templateName property 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, output 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 main-product.liquid variable block” block from the gist main-product-variable_block.liquid right below the external file imports:
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 main-product.liquid show original add to cart button block right under the theme’s “buy_buttons” block:
Copy the contents of the Printess main-product.liquid show printess add to cart button block right above the {%- when ‘rating’ -%} code 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 main-cart-items.liquid variable block block right after the loop definition.
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 for printess products. The thumbnail can be found inside the “cart-item__media” block. Paste the code of the Printess main-cart-items.liquid thumbnail block 1 right below the “cart-item__media” block.
Right after the inserted Printess “Printess main-cart-items.liquid thumbnail block 1”, the theme is testing if the line item image exists.
You have to find the matching {% endif %} block and paste the contents of the Printess main-cart-items.liquid thumbnail block 2 right underneath.
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 making 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 main-cart-items.liquid edit button block 1 atop of the for loop {%- for property in item.properties -%}
The contents of the Printess main-cart-items.liquid edit button block 2 needs to be copied directly below the closing tag of the property for loop {%- endfor -%}
The last thing left to do, is making sure that the uploaded JavaScript and CSS files that have been uploaded to the assets section of the theme are loaded automatically on each page load.
Open the “theme.liquid” file inside the “Layout” folder.
Paste the contetnts of the Printess theme.liquid header block 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.
Then scroll down to the bottom of the page. Search for the Body end tag “” and paste the contents of the Printess theme.liquid body block above the end tag.
In order to notify the printess system about new orders so that it can start producing the PDF’s of your personalized products you need to register a webhook at the shopify webhook configuration. You will need to contact the printess support as first 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.
There, open the notification settings.
And scroll to the bottom where you will find the web hooks configuration.
Click on “Create webhook” and select “Order creation” from the events and configure the format to be “JSON”:
Inside the url setting, use the following url: https://api.printess.com/shops/shopify/order/xxxxxxxxxxx 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
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.
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 inside the Printess account portal.
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.
Click on Develop apps on the top right side.
Click on Create an app
Provide a name for the app.
Now click on “Configure Admin API scopes”
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’
Click on Save on the top right (bottom right) corner of the page.
To receive an access token, the app needs to be installed on the current shop. Click on Install app on the top right corner.
Click on Install
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.
The token should start with shpat_. Now provide the printess support with this token and the domain name of your shop.