# Expert Guide: Seamlessly Integrate Third-Party Supplier API with Shopify Short version: What you want *is* doable on Shopify, but it’s not a simple “turn on a setting.” You’ll basically need a **custom app + custom product flow** that talks to the diamond API, then pushes the chosen diamond into Shopify as a line item (with correct price/inventory) before checkout. I’ll break it down in a practical way so you can decide architecture. --- ## 0\. First, reality check: what Shopify can / can’t do * Shopify **does not let you** just pass any random price into checkout from the frontend. * Every checkout line item must map to: * a **product variant** (with a defined price), or * a **custom line item** created via Admin API (e.g., in a draft order). * **Real-time calls to 3rd-party APIs inside “Shopify Functions” are not allowed** (Functions can’t call external APIs). So the usual solution: 👉 **Call your diamond API in your own app / frontend → then create/update a “diamond product/variant” in Shopify (or draft order) → then send user into checkout.** --- ## 1\. UX flow design for “Ring → Diamond → Checkout” ### Step 1. Choose Ring (Shopify-native product) * Each ring style is a **normal Shopify product** (with variants as needed: metal, size, style, etc.). * When user selects the ring, store the selection in: * Cart line item properties, or * Your own frontend state (if you go semi-headless). ### Step 2. Choose Diamond (powered by 3rd-party API) You don’t want to import millions of diamonds into Shopify. Instead: **Option A: Embedded diamond search widget (most common)** * Build a **custom app** that injects a React widget (App Block) on the “Choose Diamond” page. * This widget: * Calls the 3rd-party diamond API (search, filter, sort). * Displays diamonds list, details (4C, cert, images). * On “Select this diamond”: * Calls your app backend. * Your backend: 1. Validates availability + price with the diamond API. 2. Creates / updates a **temporary Shopify product or variant** representing that specific diamond (e.g., `Diamond #GIA12345 for Ring X`). 3. Returns the Shopify product/variant ID to the frontend. **Option B: Fully headless store (Hydrogen / custom frontend)** * Frontend is Hydrogen / Next.js, talking to: * Shopify Storefront API for cart/checkout. * Your diamond API directly. * When user chooses a diamond: * Backend service creates/updates a variant in Shopify with the diamond’s price. * Frontend adds that variant to cart with the ring product. * This is more flexible but more dev work. --- ## 2\. How to represent “Ring + Diamond” technically You have a few patterns: ### Pattern 1. Two line items in cart * Line item 1: **Ring** product (static). * Line item 2: **Diamond** product (dynamic, created by app). * You link them via line item properties, e.g.: * `paired_with_line_item_id`, `diamond_id`, `gia_number`, etc. * Pros: * Simple, transparent in backend. * Easy to adjust diamond pricing independent of ring. * Cons: * Customer sees two items in cart (you can style it like a “set” though). ### Pattern 2. One bundle product * Your app creates a **bundle product** representing “Ring X + Diamond Y”. * That single item has total price (ring + diamond). * In Admin, you store metadata (ring ID, diamond ID) to know how to fulfill. * Pros: * Cart looks cleaner (1 product). * Cons: * More complex logic for inventory & product management. For a first version, I’d recommend **Pattern 1 (two line items)** and use frontend design to make it look like one combined set. --- ## 3\. Keeping diamond inventory & price in sync Key requirements: 1. **Check availability** when user selects a diamond and again before checkout. 2. Keep Shopify’s diamond variant price aligned with the 3rd-party API (for record and refunds). Typical approach: * Your app stores a local record: `diamond_id, gia_number, current_price, currency, supplier_status, last_synced_at`. * When user clicks “Select diamond”: 1. Backend calls diamond API → confirm `available` and `current_price`. 2. If available: * Create/update Shopify product/variant: * Title: `Round Brilliant GIA 1234567890, 1.02ct, D, VS1` * SKU: the diamond ID from API. * Price: use API price (plus your margin). * Inventory: set to 1 (track inventory). * Tag: e.g. `diamond_dynamic`, `non-browsable` (hide from general catalog). 3. Return variant ID to frontend → add to cart. * Optionally, run a scheduled job: * Sync any diamonds currently in **carts, open orders, or “watchlist”** to ensure price wasn’t changed dramatically. --- ## 4\. What you need to build (at a high level) ### A. A **custom Shopify app** (Node/Express, Rails, or whatever you like) Main responsibilities: 1. **Connect to diamond API** * API keys, auth. * Endpoints: search, details, pricing, availability. 2. **Admin interface (optional but useful)** * Configure API keys. * Define pricing rules (markup, currency conversion). * Control which ring products can use the diamond selector. 3. **Backend endpoints for the storefront widget** * `GET /api/diamonds/search` – called by frontend with filters. * `GET /api/diamonds/:id` – show details. * `POST /api/diamonds/select` – validate and create/update Shopify product/variant. * Returns: Shopify `productId`, `variantId`, price, etc. 4. **Shopify Admin API integration** * Create / update diamond products / variants. * Set images, metafields (for spec, cert link, etc.). * Optionally hide these products from collections & search. --- ### B. Storefront integration (Online Store 2.0 theme or Headless) If you stay on a normal Online Store theme: 1. Create a **“Choose diamond” page template**: * Insert an App Block from your custom app (React widget). * Widget UI: * Filters (shape, carat, color, clarity, price range). * Table/grid of diamonds. * “View details” & “Select this diamond” button. 2. Flow: * User chooses ring (product page) → click “Next: Choose diamond” → go to the diamond page with ring info (e.g. URL param or session). * On diamond select: * Call `POST /api/diamonds/select`. * On success: * Add line items to cart: * Ring product. * Diamond variant (from app). * Redirect to `/cart` or directly to `/checkout`. 3. Use Shopify’s `cart.js` or Storefront API to add the items. If you go **headless**, same logic but you control everything in your own frontend app. --- ## 5\. checkout & post-purchase considerations * **No external API calls inside checkout**: So **all diamond price & availability checks must be done before** redirecting to `/checkout`. * On order creation: * Store diamond metafields on: * Order line item (diamond specs). * Order metafields (associated diamond ID, supplier code). * This will be important for: * Fulfillment. * After-sales service. * Replacements. * If the diamond becomes unavailable between “add to cart” and “checkout”: * You can: * Handle at the cart page: revalidate on cart load, and show “this diamond is no longer available, please choose another one.” --- ## 6\. Do you need Shopify Plus? * **Not mandatory** for this flow. * Plus mainly matters if you want: * Deep **checkout UI customization** (Checkout UI Extensions). * **Functions** for automatic discounting, complex shipping, etc. Your core ring → diamond → checkout flow can work **on normal Shopify**, implemented as: * Custom app + storefront App Block. * Or headless frontend + Storefront API. --- ## 7\. Suggested MVP architecture for your project Given your typical stack (you often use custom dev, n8n, etc.), I’d recommend: 1. **Stay on Online Store 2.0 (not fully headless) for speed.** 2. Build a **private Shopify app**: * Node/Express + PostgreSQL. * Diamond API integration + Admin API integration. 3. On theme: * Product page for ring uses a button **“選擇鑽石，完成搭配”** → send ring info to /choose-diamond page. * `/choose-diamond` uses your App Block widget to search diamonds. 4. On diamond select: * App validates via API, creates (or updates) a diamond variant, then: * Frontend calls `/cart/add.js` with: * Ring product variant. * Diamond variant. * Redirect to cart or checkout. That’s the cleanest v1 that: * Keeps everything inside Shopify. * Lets you scale or change the diamond supplier later. * Fits Shopify’s constraints (no arbitrary pricing at checkout). --- If you tell me: * Which diamond provider/API you’re using (RapNet? IDI? custom wholesaler?), * And whether you’re okay with normal theme vs headless, I can draft a more concrete **technical blueprint**: tables, API endpoints, and a sample flow (including example code for creating diamond variants and adding them to cart).