Shopify Integration

JewelTrak connects to Shopify so you can run JewelTrak as your back office and Shopify as your online storefront — without typing inventory into both systems. The integration is bidirectional:

• JewelTrak → Shopify: jewelry items push as Shopify products with photos, specs, prices, and stock; QOH stays in sync as you sell, memo, return, scrap, or count.
• Shopify → JewelTrak: incoming Shopify orders create JewelTrak invoices; manual stock edits in Shopify admin update JewelTrak QOH; canceling a Shopify order voids the JewelTrak invoice.

Connection is per JewelTrak store. If you have multiple stores you can connect each to its own Shopify shop, or only connect the stores where online sales actually happen.

Setup (one time)

The connection starts in Shopify, not in JewelTrak. You’ll need a JewelTrak login that can manage users (usually the owner or an administrator).

1. Ask JewelTrak for your store’s install link. The Request your Shopify install link button on Settings → Stores → [your store], in the Shopify card, opens an email to JewelTrak that already names your shop, your store and you. Fill in your store’s myshopify address (in your Shopify admin, open Settings, then Domains; it ends in .myshopify.com) and send it. The JewelTrak app isn’t in the Shopify App Store; each shop gets its own private link.
2. Open the link while signed in to your Shopify admin, and approve the permissions Shopify shows you.
3. Shopify sends you to JewelTrak. Sign in if you aren’t already.
4. If your business has more than one JewelTrak store, choose the store this Shopify shop belongs to and click Connect. With one store, this step is skipped.
5. You land on that store’s settings, and the Shopify card shows Connected with the date.

That’s the whole setup. Webhooks are registered automatically on connect. The link Shopify sends you back with is good for 30 minutes; if it expires, open JewelTrak again from Apps in your Shopify admin.

Re-authorize after a scope expansion

JewelTrak occasionally adds capabilities that require new Shopify permissions (most recently: fulfillment push-back). When that happens, existing connections keep working for older features but new features will fail with a permission error. The fix is one click:

1. Settings → Stores → [your store] → Disconnect Shopify.
2. In your Shopify admin, open Apps → JewelTrak. Shopify sends you back to JewelTrak, which reconnects the same store; approve the new permissions if Shopify asks.

Your Shopify shop is unchanged — you’re just re-granting permission with the wider scope.

Publishing products

Each jewelry item has a Sales Channels tab on its detail page. Inside it, the Shopify sub-tab lets you:

• Edit storefront overrides — title, body HTML, vendor, tags, MSRP (compare-at price), SEO title and description, status (active / draft / archived), shipping required, taxable. Every field is optional; blank fields fall back to the JewelTrak defaults (Description, Category, etc.).
• Push to Shopify — creates the Shopify product the first time, updates it on subsequent pushes. Photos, specs (metal, weight, dimensions, designer, etc.), and the SKU all flow over. The item needs a Store (the store’s Shopify connection is the one used); without one the button is greyed out with a link to the General tab to set it.
• Re-push — useful after editing photos, descriptions, or pricing.

Bulk publish

On the Jewelry list page, tick the items you want to publish, open the Action menu, and pick Publish to Shopify. A preflight modal shows:

• How many items can be pushed (have a store assigned, store is connected to Shopify)
• How many will be new Shopify products vs. updates to existing ones
• Per-item skip reasons for anything that can’t be pushed (e.g. “No store assigned” or “Store #2 is not connected to Shopify”)

Item-level failures don’t fail the batch — each item is pushed independently and the modal reports a per-item summary at the end.

The action only appears for organizations with the Shopify channel enabled.

Bidirectional QOH sync

JewelTrak is the system of record for inventory; Shopify mirrors it. Every QOH movement in JewelTrak pushes the new count to Shopify within a second or two:

• POS sale (invoice line item)
• Memo issue / memo return
• Vendor return tag / scrap tag
• Voiding a return receipt or scrap batch (re-credits)
• Inventory count adjustment (variance reconciled to a counted total)
• Manual QOH edit on the inventory detail page

The push is best-effort and fire-and-forget: a Shopify outage will never block the JewelTrak operation that triggered it. If a push fails, the item drifts out of sync until the next push or a manual recovery.

When the merchant edits stock in Shopify

Manual stock edits in the Shopify admin (Inventory page, bulk editor, Shopify POS, etc.) fire an inventory_levels/update webhook. JewelTrak finds the matching item by its Shopify inventory_item_id and updates JewelTrak QOH to whatever Shopify reports. An audit-log entry records the change with Shopify as the user.

Items pushed before this feature was wired in won’t have the inventory_item_id captured yet. Re-push them once (per item or via bulk publish) and inbound sync will work going forward.

Recovering from drift

If you suspect counts have drifted (e.g. a long Shopify outage during sales):

• Per item — open the inventory detail, Sales Channels → Shopify → Re-push to Shopify. This rebuilds the product and pushes current QOH.
• In bulk — select the affected rows on the Jewelry list and use Publish to Shopify again. Updates take the place of creates.
• Reconciler — Utilities → Quantity Reconciliation catches counter drift across the JewelTrak side; not Shopify-aware, but useful as an upstream sanity check.

Inbound orders

Every Shopify order fires an orders/create webhook. JewelTrak:

1. Matches the customer by email (case-insensitive). If no contact matches, a new Retail contact is auto-created with a note tagging the source: “Auto-created from Shopify order #1234”.
2. Matches each line item by SKU back to a JewelTrak StockID (zero-padded numeric SKU like 001234). Matched lines link as jewelry; unmatched SKUs land as miscellaneous lines so the invoice still totals correctly.
3. Creates an Open invoice with the Shopify order ID stored for traceability. Decrements QOH for matched jewelry lines.
4. Idempotent — if the same Shopify order somehow webhooks twice (Shopify retries on non-2xx), the second hit ack-and-skips.

The new invoice appears in your normal Open Invoices list. Apply payment, finalize, ship — same as any other invoice.

When the customer cancels

A Shopify-side order cancellation fires orders/cancelled. JewelTrak voids the matching JewelTrak invoice automatically (the void path restores QOH for any jewelry lines that were on it). Audit log records Shopify as the user.

Outbound fulfillment

When a JewelTrak invoice that originated from Shopify is finalized — explicitly via the Finalize button or automatically when the customer’s payment closes the balance — JewelTrak posts a fulfillment to Shopify. This:

• Marks the order as Fulfilled in the Shopify admin
• Closes the merchant’s open fulfillment_orders for that order
• Does not notify the customer (JewelTrak already handles invoice email through its own templates — Shopify’s auto-email would duplicate)

The push is best-effort and idempotent: if a fulfillment_order is already closed, the call no-ops.

If your storefront uses Shopify Fulfillment Network or a third-party fulfillment service, this push only marks merchant-managed fulfillment_orders. Third-party fulfillment continues to work the way you’ve configured it in Shopify.

What flows over (and what doesn’t)

Direction	What syncs
Out	Product fields (title, body, vendor, tags, MSRP, status, taxable, shipping required, SEO)
Out	Variant SKU + barcode (zero-padded StockID), price, cost, quantity, weight (grams)
Out	All photos for the item (in PicNo order — primary first)
Out	QOH on every JewelTrak counter movement
Out	Fulfillment status when invoice finalizes
In	Order header + line items → JewelTrak invoice
In	Customer (email match or auto-create)
In	QOH change from Shopify-side stock edit
In	Order cancellation → JewelTrak invoice void
Not yet	Watches and stones (Phase 2 — currently jewelry only)
Not yet	Stone metafields (carat, color, clarity, GIA cert) — Phase 2
Not yet	Per-channel pricing rules — Phase 2

Disconnecting

Settings → Stores → [your store] → Disconnect Shopify clears the access token and removes the shop-domain → JewelTrak-store mapping. Webhooks stop processing immediately. Existing Shopify products created by JewelTrak are not deleted from Shopify — they remain in the merchant’s Shopify catalog and you can keep editing them inside Shopify directly.

If you reconnect later, the same Shopify products will re-sync (matched by ShopifyProductId stored on each JewelTrak inventory row).

Troubleshooting

• “Store #N is not connected to Shopify” in the bulk publish modal — the item’s StoreID points to a JewelTrak store that hasn’t connected to Shopify. Either set a different StoreID on the item or connect that store under Settings → Stores.
• Bulk publish skipped my items with “No store assigned” — open the item, set its Store, and try again.
• Fulfillment push silently doesn’t fire — usually means the connection was made before the fulfillment scope was added. Disconnect, then open Apps → JewelTrak in your Shopify admin to re-authorize with the new scope.
• Inventory edit in Shopify didn’t update JewelTrak — the item was likely pushed before the inventory_item_id was being captured. Re-push the item (or use bulk publish on it) and try again.
• Webhook not firing at all — webhooks are registered at OAuth time. If for any reason a webhook is missing, disconnect and reconnect from Apps → JewelTrak in your Shopify admin; registration is idempotent and re-running it will install any newly-required topics.
• “Shopify needs reconnecting” banner (Listings page) or a “Reconnect needed” badge (Integrations hub card) — JewelTrak detected an authentication failure (expired or revoked credentials) on a push or reconcile, so every push will keep failing until the connection is restored. For Shopify, reconnect by opening Apps → JewelTrak in your Shopify admin, which sends you back to JewelTrak to re-authorize. The flag clears automatically on the next successful push, remove, or reconcile — you don’t need to dismiss it. This works the same across every channel (eBay, RapNet, your website).