VU x Shopify Integration and Setup

This guide outlines how VU integrates with the Shopify ecosystem. It covers technical connectivity, product catalog structure, frontend theme implementation, and order processing logic.

Key Concepts within the VU x Shopify Relationship

• Customizer Integration: Customers enter the customizer from a PDP →

  Customer Configures Item → Customer Clicks "Add to Cart".

• The Handshake: VU generates a unique recipe_id token and pushes a payload to the Shopify cart. This allows the customer to check out natively in Shopify.

• Order Flow: Shopify processes the payment → VU imports the paid order → VU generates artwork/production files → VU pushes fulfillment tracking back to Shopify.

---

1. Store Connection (Security & API)

VU requires a "Custom Dev App" to be installed within Shopify, follow the steps below to configure:

Step A: Prerequisites (Access)

1. Collaborator Access:

   • VU will request access via the Shopify Partner Portal.

   • Permissions needed: Themes (optional), Products (Full), Settings, Apps.

2. Plan Requirement :

   • The "Shopify Basic" plan restricts PII (Personally Identifiable Information like Name/Address) via the API for custom apps.

   • VU cannot import order for brands on the Basic plan as this plan limits data available via API

Step B: API App Configuration

1. In Client Shopify Admin: Go to Settings → Apps and sales channels → Develop apps.

2. Click Create an app (Name: VU Customizer).

3. Configure Admin API Scopes (Mandatory):

   • Products: read_products (to link templates), write_products.

   • Orders: read_orders, write_orders (to import).

   • Fulfillments: read_fulfillments, write_fulfillments.

   • Fulfillment Orders: read_assigned_fulfillment_orders, write_assigned_fulfillment_orders, read_merchant_managed_fulfillment_orders, write_merchant_managed_fulfillment_orders.

4. Install & Generate Token:

   • Click Install. Reveal the Admin API access token (begins with shpat_). Copy this immediately - it is only visible once.

To create the Access Token, follow the below steps:

1. Log in to your Shopify admin panel.

1. In the left menu, click Apps > Apps and Sales Channel settings >Develop apps.

1. Click Allow custom app development.

1. Click Enable to confirm and then click Create an app.

1. Enter the following details and click Create app.

   • App name: Brand's app name.

   • App developer email: Brand's team lead email address.

1. Navigate to the Configuration tab.

1. Click Configure, select the permissions, and click Save.

1. Select the Overview tab and click Install app.

1. Confirm Install.

1. Next, you will be redirected to the API Credentials tab. Click Reveal token once and save the token somewhere safe to be used later.

Enable Webhooks

To enable Webhooks:

1. In the left menu, click Notifications.

2. Click Webhooks > Create Webhooks > Create.

1. Enter the following details and click Save.

Field	Description
Event	Select Order creation.
Format	Choose JSON.
URL	Enter the Webhook URL provided by VU Custom.

by now you should have the following:

• Shopify Domain

Step C: VU OS Connection

1. Log into VU Admin → Stores.

2. Add New Store → Select Shopify.

3. Paste the Access Token and Store URL (e.g., brand.myshopify.com).

---

2. Product Catalog

VU uses your store's existing product catalog to ensure the right base products are what drives the offering within the customizer.

2.1. The Linking Logic (Variant ID)

• Concept: Shopify structures data as Product Parent > Variants (Sizes/Colors).

• Configuration: VU links specifically to the Variant ID.

• Why this matters: If your T-Shirt has 5 colors, that represents 5 Variant IDs. Our script listens to the storefront URL to ensure that when a customer selects "Red," the VU Customizer loads the corresponding "Red" visual template.

2.2. Inventory & Stock Settings

In Shopify, in order to add a SKU, inventory must be turned on and a corresponding inventory item must exist. If inventory is not something that tracking is needed for, you can turn off “Continue Selling when OOS”. This will allow the product to continue to be purchased, however you will see a negative inventory value. This can be ignored if inventory is truly not tracked. This may also be achieved if “Track Quantity” is set to NO as well.

Requirement: For all Customizable Base Products and Upcharge items, inventory is expected to be available.

2.3. Upcharges / Add-On Items

VU does not edit product pricing dynamically (e.g., changing a $20 shirt to $25 via code). We use Bundle Logic to increment the price of the base product as upcharges are selected.

• Scenario: A user adds "Premium Embroidery" (+ $5.00).

• Shopify Setup: Create a separate, standalone product or variant in Shopify.

• VU Setup: Link this "Upcharge Product" in the Upcharge module.

• The Experience: When the customer adds to bag, the cart will display two items: 1. The Shirt and 2. The Upcharge Fee. Both must have active inventory.

2.4. SKU Logic

Shopify has Products and Variants. “Products” as “Pants”, “Variants” are “Red Pants”. When we add items to cart, we reference the variant id (this is the unique identifier that we add to cart and link to for templates because Shopify uses this throughout each instance (not the Display Name or SKU). When we receive an order, we place the SKU (which is a property of the variant’s inventory association). This is the factory name for the variant order (“PANTS-RED-XXL”). It is used to 1) route orders to a particular factory if needed 2) Display the product ordered in the factory order view

Best Practice: Ensure your SKUs follow a consistent naming convention. VU uses SKU prefixes/suffixes to route orders to specific factories or printing stations.

---

3. Frontend Integration

This section details how the customizer is embedded onto the Product Detail Page (PDP) and install Custom Shopify theme. Note: Always perform installation on a Duplicate/Draft Theme first.

3.1. File Creation

Two key files are added to the Shopify Theme (Online Store > Themes > Edit Code):

1. The Container: snippets/template-1.liquid.

   • This holds the structural HTML: <div id="customizer-root">...</div>.

2. The Controller: sections/vu-custom.liquid.

   • This enables the customizer to be dragged-and-dropped via the Shopify "Customize" Visual Editor.

3.2. Embed The Customizer

The driver script connects the page to the VU Engine. It allows the Customizer to react to Shopify dropdowns (like size/color selectors).

<script
  id="customizer"
  src="https://vu-customizer.s3.amazonaws.com/production/main.js"
  data-variant="{{ product.selected_or_first_available_variant.id }}"
></script>

Functionality:

• The liquid tag product.selected_or_first_available_variant.id ensures that the 3D model currently displayed always matches the physical inventory selection on the page.

• The JS Snippet functions by calling the VU Custom server to fetch the VU widget. It determines which widget to pull based on the variant ID that is passed through as {VARIANT}. The JS Snippet should sit on the product display page for all products that are getting customized.

  • The usual method that brands implement this JS snippet is through a ruleset in the Shopify code that chooses when to include the JS Snippet. This ruleset is looking for a tag, metafield, or other identifier from the product setup page in Shopify admin.

    • For example, you could tag every personalized product with the tag “VU CUSTOM”, and then inside of the product display page, write a method that checks for this tag and inserts the JS snippet if the “VU CUSTOM” tag is true.

  • This implementation methodology allows for scalability when future products are added to the program, and also makes it easy to toggle the widget for an existing product. In order to turn the widget off, all you would need to do is remove the “VU CUSTOM” tag from the product.

NOTE: The widget will not show right away when the .JS Snippet is added, as VU Custom developers need to do some setup in VU Admin as well.

For detailed instructions, refer Integrating The VU Customizer in Shopify.

3.3. Styling the Customizer

To style the customizer in Shopify, you can use HTML and CSS as per brand guidelines. For a detailed walkthrough and code examples, refer to this article. In summary, here are the actions to take:

1. Add the necessary HTML to your Shopify page.

2. Insert the JS Snippet from the Embed Customizers page.

3. Ensure the JS Snippet links customizer elements to your HTML.

For a complete guide, please refer Styling the Customizer in Shopify

OR

3.4. Use one of VU's OTB Shopify Styles

VU has a library of Front-End styles that can be used for the styling of the customizer. Each can instantly be used directly in your store's theme. Our styles serve as an initial starting point and can be used for then entire customizer design, or modified directly in the theme per brand preference. For a detailed walkthrough and code examples, refer to the linked article below. In summary, here are the few simple steps to get started with one of the OTB VU themes:

1. Create new Theme code

2. Select Template

3. Publish the Theme

For a complete guide, please refer to Installation Guide - OTB Shopify Styles.

Download the customizer themes using the zip file below:

54KB

vu-customizer-themes(liquid_files).zip

archive

Open

---

4. Order Creation, Import, and Updates

4.1. Add-To-Cart (ATC)

When Add to Cart is clicked in VU, the system hands data back to Shopify.

• Config Token: We inject a unique token into the Line Item Properties.

  • Property Name: _recipe_id (Standard) or recipeid (Legacy).

  • Note: The underscore _ hides the property from the customer in checkout.

• Thumbnail: A visual thumbnail of the user's specific creation.

• Readable Props: Human-readable specs

4.2. Order Import Logic & Validation

VU ingests orders via webhook or polling when the status is Paid. The import service acts as a gatekeeper and will REJECT the entire order if the Shopify payload is incomplete.

Mandatory Fields (Rejection Criteria)

If any of the following data points are missing from the Shopify JSON, the order will fail to import into VU:

Order Root	created_at	Timestamp of purchase.
Order Root	name	The Order Number (e.g., "#1001").
Order Root	shipping_lines	Must be present (even if empty or free).
Line Items	line_items array	Must exist.
Line Item Object	id, sku, price, title, quantity, vendor	All standard fields required per item.
Config Token	properties: { recipe_id }	At least one item must have the recipe token property.
Shipping Address	first_name, last_name, address1, city, zip, country_code	Derived from shipping_address or customer.default_address.

Optional Fields

The service will process and store these if present, but they do not cause rejection if missing:

• Order Level: note, total_weight

• Address: address2, company, phone, province_code (State), and billing_address.

• Item Level: grams, product_id, variant_id.

4.3. Tracking Updates (Fulfillment)

When production is complete, VU pushes data back to Shopify.

1. VU identifies the Shopify Order #.

2. VU triggers the fulfillment_create API endpoint.

3. Result: Shopify marks the order as Fulfilled, triggers the transactional email to the customer, and creates a "Shipment" with the tracking number/carrier.