Shopify Integration

This page covers the full Shopify integration — how the builder connects to your store's product, cart, and webhook system.

Architecture Overview

Shopify Product Page
  └─ "Create Gang Sheet" button
       └─ Opens builder URL with ?variant=VAR_ID&size=22x48&shop=store.myshopify.com
            └─ Customer builds layout
                 └─ "Save & Add to Cart" clicked
                      └─ POST /api/upload-gang-sheet → returns downloadUrl
                           └─ GET /cart/add?id=VAR_ID&qty=1&properties[Gang Sheet File]=URL
                                └─ Customer redirected to Shopify cart
                                     └─ Checkout → Order placed
                                          └─ Shopify webhook → backend email → you download & print

---

URL Parameters

The builder reads the following URL parameters when launched from the product page:

Parameter	Description	Example
variant	Shopify variant ID for the selected size	?variant=43890123456
size	Sheet dimensions in WxH format (inches, no spaces)	?size=22x48
shop	Your Shopify store domain	?shop=mystore.myshopify.com
quantity	Pre-fill the quantity field	?quantity=2
price	Override the price display	?price=40.00

The button script on the product page constructs and passes these automatically.

---

Supported Sheet Sizes

Sheet sizes are configured in the backend's tenant config (see Branding & White-Label). The default sizes are:

Label	Width	Height	Default Price
22" × 12"	22	12	$7.00
22" × 24"	22	24	$20.00
22" × 36"	22	36	$30.00
22" × 48"	22	48	$40.00
22" × 60"	22	60	$50.00
22" × 72"	22	72	$60.00
22" × 84"	22	84	$70.00
22" × 96"	22	96	$80.00
22" × 108"	22	108	$90.00
22" × 120"	22	120	$100.00

Custom sizes

You can configure custom width/height combinations — not just 22" wide. Update the sizes array in your tenant configuration on the backend.

---

Cart Line Item Properties

When the customer clicks "Save & Add to Cart," the following properties are attached to the Shopify cart line item:

Property	Example Value
Gang Sheet File	https://backend.com/api/download/abc123...
Sheet Size	22" × 48"
_file_url	(internal, hidden from customer)

These properties appear on your Shopify order detail page and packing slips.

---

Shopify Webhook

Configure a single webhook to enable order notification emails:

• Event: Order creation
• Format: JSON
• URL: https://your-backend-url.com/api/shopify/webhook/order-created

When the webhook fires after a customer checks out, the backend:

1. Records the order in the database.
2. Finds the gang sheet file associated with the order's variant.
3. Sends you an email with the order details and a direct download link.

Webhook Security (Optional)

For production, enable HMAC webhook verification:

1. In Shopify admin, note the Signing secret for your webhook.
2. Add it to your backend environment variables:

   SHOPIFY_WEBHOOK_SECRET=your-secret-here

3. The backend will verify the X-Shopify-Hmac-Sha256 header on every webhook request.

---

Adding More Sheet Sizes

To add a new size:

1. Add a Shopify variant to your gang sheet product with the new size as the option value.
2. Note the new variant ID.
3. Update the tenant config on the backend to include the new size with its variant ID mapping.
4. Update the button script on the product page if needed to handle the new size format.
5. Test by selecting the new size and launching the builder.