> ## Documentation Index
> Fetch the complete documentation index at: https://help.fanaura.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Shopify Integration
> Connect your Shopify store to Fanaura to sync merch products, track fan purchases, and create data-collecting smart links for your merchandise.
Merch is a major revenue stream for artists, and connecting your Shopify store to Fanaura unlocks powerful capabilities: product syncing, purchase tracking, fan attribution, and smart links that collect fan data before directing shoppers to your store.
## What This Integration Does
When you connect Shopify, Fanaura can:
* **Sync your products**: Product titles, descriptions, images, prices, variants, and inventory levels are pulled from Shopify into Fanaura.
* **Track purchases**: When a fan buys merch, the purchase is attributed to their fan profile in Fanaura.
* **Enable merch smart links**: Create landing pages that showcase your merch and collect fan data (email, name, location) before sending fans to Shopify checkout.
* **Feed engagement scoring**: Merch purchases contribute to a fan's engagement score and VIP tier progression.
## Before You Start
You will need a Shopify store (any plan -- Basic Shopify and up), products published in your store, and admin access to your Shopify store (or owner permission to install apps).
## How to Connect Shopify
Go to **Integrations** in the left sidebar (or Settings > Integrations).
Locate the **Shopify** card on the Integrations page.
Click **Connect Shopify Store**.
Enter your **Shopify store URL** (e.g., `your-store.myshopify.com`).
You will be redirected to Shopify. Review the permissions Fanaura is requesting and click **Install App**.
You will be redirected back to Fanaura. Your products begin syncing automatically.
The authorization process uses Shopify's secure OAuth flow. Fanaura requests only the permissions it needs to read products and process orders.
## The Fanaura Sales Channel
When you connect Shopify, Fanaura creates a **sales channel** in your Shopify store. This is important to understand:
**Only products published to the Fanaura sales channel appear in Fanaura.** This gives you control over which products are available for smart links and tracking.
To publish products to the Fanaura sales channel:
1. In your Shopify admin, go to **Products**.
2. Click on a product.
3. In the **Sales channels and apps** section, check the box for **Fanaura**.
4. Save.
If you want all your products available in Fanaura, publish them all to the sales channel. If you only want specific products (like a new album tee), publish just those.
This is a great way to control what appears on your Fanaura smart links without affecting your main Shopify store.
## What Syncs
Once connected, the following product data syncs from Shopify to Fanaura:
| Data | Description |
| ----------------- | ------------------------------------------------------------------- |
| **Product title** | The name of the product |
| **Description** | Product description/body |
| **Images** | All product images |
| **Price** | Current price (and compare-at price if set) |
| **Variants** | Size, color, or other options with individual pricing and inventory |
| **Inventory** | Stock levels for each variant |
| **Product type** | Category or type tag from Shopify |
| **Status** | Active, draft, or archived |
Syncing happens automatically when you first connect. After that, products update when changes are made in Shopify.
## Manual merch (hyperlink-only)
From **Assets**, you can add merch items **without** connecting Shopify: upload an image, set a title, optional description, and paste an **https** product URL (for example your Shopify storefront or another store). Fans use the same hub and per-item smart link URLs; the primary button opens your external page.
**Purchase tracking** in Fanaura (orders attributed to fans, webhooks, revenue in the dashboard) applies to products **synced** through the Shopify sales channel only. Manual link items still collect **views and clicks** on the smart link like other merch pages.
## Order Tracking
When a fan purchases merch through a Fanaura smart link:
The fan clicks through your smart link to Shopify checkout.
They complete the purchase in Shopify.
Shopify sends an order webhook to Fanaura.
Fanaura attributes the purchase to the fan's profile. The purchase appears in the fan's activity timeline.
The fan earns reward tokens for the purchase (default: 100 tokens).
### What Gets Tracked
* Order total
* Products purchased (title, variant, quantity)
* Purchase date
* Fan attribution (which fan made the purchase)
This data feeds into your fan engagement scoring, VIP tier progression, and campaign targeting. You can create flow conditions like "If fan has purchased merch, send thank-you email."
## Merch Smart Links
One of the most powerful features of the Shopify integration is creating merch smart links.
### How Merch Smart Links Work
1. You create a merch asset in Fanaura (pulling from your synced Shopify products).
2. Fanaura generates a smart link for that product (or collection).
3. When fans visit the smart link, they see your merch with a data collection wrapper.
4. Fans enter their email (and optionally name, location) to proceed.
5. They are directed to your Shopify store to complete the purchase.
6. Their click and any subsequent purchase are tracked and attributed.
### Why This Matters
Without Fanaura, a fan visits your Shopify store and you have no idea who they are unless they buy. With Fanaura's smart links, you capture their data even if they just browse. And if they do buy, you know exactly who they are and can follow up with targeted marketing.
## Managing Synced Products
Your synced products appear in the **Assets** page under the **Merch** category. From there you can:
* View all synced products with images, prices, and variant counts
* Create smart links for individual products
* Include products in launches and campaigns
* See which products are getting the most clicks and purchases
Products are managed in Shopify -- Fanaura is read-only for product data. If you need to change a price, update a description, or add a variant, make the change in Shopify and it will sync to Fanaura.
## Re-Syncing Products
If your products seem out of date or you have added new items:
Go to the Integrations page.
Locate the Shopify integration card.
Click **Re-sync Products** (or "Sync Now"). Fanaura pulls the latest data from your Shopify store.
New products appear, updated products refresh, and archived products are marked accordingly.
## Disconnecting Shopify
If you need to disconnect your Shopify store:
1. Go to the Integrations page.
2. Click on the Shopify integration.
3. Click **Disconnect** and confirm.
**What happens**:
* Products remain in Fanaura but will no longer update.
* Existing smart links continue to work (fans can still visit them) but new purchase data will not sync.
* You can reconnect at any time, and syncing will resume.
## Troubleshooting
* **Check the sales channel**: Make sure products are published to the Fanaura sales channel in Shopify.
* **Re-sync**: Click the Re-sync button on the Integrations page.
* **Check product status**: Only active products sync. Draft or archived products are excluded.
* **Verify webhook**: The order webhook should be configured automatically. If orders are not appearing, try disconnecting and reconnecting.
* **Check fan attribution**: Purchases are only attributed if the fan came through a Fanaura smart link. Direct Shopify purchases without a Fanaura referral are not tracked.
If you see duplicate products after syncing, this is a known issue being investigated. Products have a unique constraint on `shopify_store_id` + `shopify_product_id`, but edge cases can occur. Contact support if you see duplicates.
Initial sync can take a few minutes for stores with many products. Large stores (500+ products) may take up to 10 minutes. You will see a progress indicator during the sync.
## Best Practices
**Publish selectively.** You do not have to publish every Shopify product to the Fanaura sales channel. Curate what appears in Fanaura to keep your merch presentation clean and relevant.
**Create smart links for new drops.** Every time you drop new merch, create a Fanaura smart link for it. You get fan data and purchase tracking automatically.
**Use merch in flows.** After a fan presaves your music, follow up with a flow that introduces your merch: "Thanks for the presave! Check out the limited-edition tee for the new album."
**Track purchase patterns.** Use fan profiles to see which fans are repeat buyers. These are your most valuable supporters -- treat them accordingly.
**Combine with VIP tiers.** Merch purchases earn 100 tokens by default. Fans who buy regularly will climb the VIP ladder quickly, and you can reward them with exclusive merch discounts at higher tiers.
***
## Temporary path: link-only merch (no API)
Everything **above** this section still describes the **full Shopify integration** (OAuth, sales channel, product sync, and order webhooks). That documentation is unchanged.
Sometimes the full Shopify app integration is not available (for example during App Store review or token limits). In those periods, Fanaura can support a **simplified “merch asset”** on **production** that behaves more like **music or tour assets**: add an item, show **image + title + Add to cart** (outbound link), and still **log clicks** and **fan identity** through the existing fan wrapper and tracked-link patterns.
**Staging / review:** The environment used for Shopify App Store review (`live.fanaura.com` / `shopify-review`) should stay **frozen** so reviewers always see the full embedded app flow. Link-only merch is intended as a **production** (`app.fanaura.com`) capability layered alongside or instead of sync for specific artists—not as a replacement for the review build.
### What “no API” can still do
| Capability | Link-only mode |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Fan sees merch on smart link / hub | Yes — driven from Fanaura DB fields (image URL, title, checkout URL). |
| Add to cart | Yes — button opens your **Shopify cart or product URL** (same as hyperlinking). |
| Wrapper / sign-in | Yes — same patterns as today: fan session before or after click, depending on product rules. |
| **Which** merch a fan clicked | Yes — server-side **redirect + `fan_interactions`** (or your existing `tracked_links` flow) before sending the browser to Shopify. |
| Automatic inventory, variant matrix, order sync | **No** — without Admin API + webhooks, Fanaura does not stay authoritative for stock or purchases. You can still **manually** update image/title/link when something changes. |
### Options and scenarios
**A — Manual “ingestion lite” (simplest, most reliable)**\
Same mental model as **Add track**: wizard steps like (1) name, (2) image URL or upload to storage, (3) **checkout URL** (product or pre-selected variant). Optional **one line of subtitle** (“Unisex tee — black”). Variants: either **one link per variant** (each row is its own “asset”) or **single link** to the product page where Shopify handles size/color. No parsing, no breakage from theme changes.
**B — Paste Shopify product URL (semi-automatic)**\
Artist pastes `https://yourstore.com/products/handle`. A **server** endpoint fetches the **public** page and tries to extract **title**, **image**, and **canonical product URL** (e.g. Open Graph / JSON-LD). **Caveats:** themes differ, some stores use bot protection, and **price / variant list** is often wrong or missing without an API. Treat this as **prefill only** — user always confirms before save. A more stable variant is Shopify’s **oEmbed** product response when available (still public HTTP, not the Admin API).
**C — Hybrid**\
Paste URL to prefill, then **lock in** a single **Add to cart** link the artist copies from Shopify admin (cart permalink or variant-specific URL) so the button always lands where they intend.
### Recommendation
For **maximum simplicity** and **least maintenance**: **A or C** — thin rows in Fanaura, **one primary outbound URL** per merch asset, **tracked redirect** for analytics. Use **B** only as a convenience layer on top, with clear “verify fields” copy.
### Tracking (works without Shopify API)
Use a **Fanaura redirect URL** that (1) records `fan_id` / session, `asset_id`, `interaction_type` (e.g. merch click), then (2) **302** to Shopify. Purchase attribution without webhooks remains incomplete, but **interest and click funnels** match what you described for “version two.”