Integration Guide

StitchIQ works alongside your existing Shopify store setup. This guide covers the two main integration points: the cart product (required for Add to Cart) and Shopify navigation (recommended for discoverability).

Step 1 — Create an Embroidery Cart Product

StitchIQ's "Add to Cart" button adds a line item to the Shopify cart using a real Shopify product. You need to create this product in your Shopify admin.

Why a separate product?

Shopify requires all cart items to reference a valid product variant. StitchIQ uses a single generic "Custom Embroidery" product to represent all embroidery orders. The specific design details (design name, thread colors, stitch count) are attached as line item properties — not variants.

Creating the product

1. In your Shopify admin, go to Products → Add product.
2. Set the product name to something like Custom Embroidery Order.
3. Set the price to $0.00 — StitchIQ will update the price dynamically via the cart API.
4. Set inventory to "Don't track inventory".
5. Set "This is a physical product" — check this if you ship embroidered items, uncheck if you offer digital files only.
6. Save the product and copy the variant ID from the URL (it appears as a long number after /variants/).

Finding the variant ID

After saving the product, click on the default variant. The URL will look like: https://your-store.myshopify.com/admin/products/123456789/variants/987654321

The variant ID is 987654321.

Linking the product to StitchIQ

1. In your StitchIQ admin, go to Settings → Integration.
2. Paste the variant ID into the Embroidery Product Variant ID field.
3. Save.

StitchIQ will now use this product when adding items to the cart.

Step 2 — Add the Catalog to Your Navigation

Make the catalog easy to find for customers:

1. Go to Online Store → Navigation in Shopify.
2. Click your Main Menu.
3. Click Add menu item.
4. Name: Embroidery Catalog (or similar)
5. Link: /apps/stitchiq
6. Save.

For category-specific links (e.g. "Sports Logos"), use the full URL:

https://your-store.myshopify.com/apps/stitchiq?category=Sports

See Gallery & Deep Links for more linking options.

Step 3 — Test the Full Flow

1. Visit your catalog at /apps/stitchiq as a customer (incognito window).
2. Click a design and click Add to Cart.
3. Open your Shopify cart — the embroidery product should appear with design properties visible.
4. Complete a test checkout using a Shopify test gateway.
5. Check the order in your StitchIQ admin — it should appear in the Orders list with all design details.

Cart Line Item Properties

When a customer adds an embroidery item, StitchIQ attaches these properties to the cart line item:

Property	Example Value
Design	"Rose Floral Emblem"
Format	".pes"
Stitch Count	"8,432"
Thread Colors	{"0":"#c0392b","1":"#2ecc71"}
Price	"$24.00"
_design_id	Internal design identifier (hidden from customer)

Properties prefixed with _ are hidden from customers on the cart/order pages but visible to you in the Shopify admin.

Hiding the Cart Product from Your Store

You likely don't want the "Custom Embroidery Order" product appearing in your regular store collections. To hide it:

1. In the product editor, set the Sales channels so the product is only available to the Online Store (or remove it entirely from Online Store and leave just the Storefront API/StitchIQ).
2. Do not add it to any collections.
3. Set it as Draft — StitchIQ can still add draft products to the cart.

Keep the product active in the Storefront API

If you set the product to Draft, ensure it's still accessible via the Storefront API, otherwise Add to Cart will fail. The safest option is to leave it Active but not linked from any collections or navigation.

App Proxy Configuration

The App Proxy is configured automatically when you install StitchIQ. Shopify routes:

your-store.myshopify.com/apps/stitchiq/* → stitchiq.saasyllama.com/proxy

No manual setup is needed. If you see a 404 at /apps/stitchiq, see Troubleshooting.