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; cancelling 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)

Before merchants can connect, the platform admin (us) registers a Shopify Partner app and provides API credentials. From the merchant side:

1. Settings → Stores → [your store] — scroll to the Shopify card.
2. Enter your Shopify shop domain (e.g. your-shop.myshopify.com — Shopify always assigns a myshopify.com domain even if your storefront uses a custom one).
3. Click Connect Shopify. You’ll be redirected to Shopify’s authorization screen, where you grant the JewelTrak app access. Approve and you’re sent back — the card now shows Connected with the date.

That’s the whole setup. Webhooks are registered automatically on connect.

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. Click Connect Shopify again and re-approve.

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.
• 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 and reconnect 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; registration is idempotent and re-running it will install any newly-required topics.