Checkout, cart modes and per-builder pricing
Connect your own PayPal app so shoppers can buy the ring they build right in the embed; every total is recomputed on the server and the payment lands in your PayPal account. Each builder's Pricing and checkout tab picks how a built ring reaches the cart: match a variant by SKU, mint one at the exact price, a Shopify draft order, hosted PayPal checkout, or an event your site handles.
3D Jewelry Designer10 min read
Checkout and payments
From the Pro plan, connect your PayPal in Dashboard → Embeds → Checkout and payments so shoppers can buy the ring they build right in the embed. In PayPal's developer dashboard, create an app under your business account and paste its Client ID and Secret; choose Live, or Sandbox to test with a sandbox buyer first. We check the keys with PayPal and keep the Secret encrypted. Every total is recomputed on the server (a client can never set its own price), the payment lands in your PayPal account, and we take no commission. PayPal checkout takes USD, EUR, GBP, AUD, CAD and SGD; a builder priced in another currency keeps your other cart modes. The enquiry path stays for bespoke work.
Cart and checkout modes
On each builder's Pricing and checkout tab, pick how a built ring reaches the cart: match an existing variant by SKU, mint a variant at the exact price, a Shopify draft order (invoice link), hosted PayPal checkout, or event (your site handles it).
On hosted checkout, the ring size the shopper picked is part of the item name they pay for ("size US 7"), and it is saved on the order and its lead. Back on the payment page returns the shopper to their ring on your page, with every choice in place, ready to change.
On Shopify, each ring in the cart can carry Edit and View in 3D links. See Edit a ring from the cart.
Minting a variant and creating a product write into your Shopify catalogue, so they need your yes first: see Products in your store.
If the chosen mode is not available (store not connected, missing permission) it
falls back down that list automatically, and the ring-builder.js SDK executes
whatever comes back, so the common Shopify install needs no variant id and no
custom cart code.
Test mode
Before you launch, turn on Test mode on the same tab and place a test order
on your store. Nothing is written to your store's products and the hosted
checkout is skipped: a ring your variants don't sell becomes a Shopify draft
order, which you can delete afterwards, and the builder shows a small "Test
mode" label. Turn it off to go live. Over the API this is
commerce.testMode in the builder's config.
Enquiry only, no cart
If you sell by appointment or make every ring to order, choose Send an enquiry under When the shopper is ready on the same tab. The builder's button then opens a short form: an email address, and if they like a name, a phone number and a question. The ring, its size, its diamond and the question reach you as an enquiry in Dashboard → Leads and by email. There is no cart and no checkout, so no store has to be connected. You can rename the button there too, for example "Book a consultation".
Over the API, set commerce.enquiryOnly (and, if you like,
commerce.enquiryLabel) in the builder's config. The cart routes answer
409 enquiry_only for such a builder.
Pricing manager
From the Pro plan, each ring builder has its own Pricing page (in Dashboard → Embeds, next to Analytics). Set that builder's own currency, markup, rounding and per-part prices over the platform's base catalog, plus its own centre-stone tiers (or connect a live diamond feed). Different builders can price differently, for example one storefront in USD and another in AUD.
One builder can also have a book for each currency you sell in. On a Shopify store the builder then shows each shopper the price from the book in their currency, and from the default book when you have none for it. Shopify prices a variant only in the store's own currency, so a ring priced in another goes to checkout as a draft order in the shopper's currency (or your hosted checkout), at exactly the price shown.
A builder can also switch cost-based pricing on or off and set its own price per gram and accent-stone tiers. See Weight, stones and cost-based pricing.
Price from weight in one card
At the top of Pricing → Ring prices, Price from weight sets up the builder's default price book to price every ring from its own measured weight. Fill in what you know and leave the rest blank:
- Gold, 24K and Platinum: the price of a gram of pure metal, plus an Alloy premium for alloying. Each karat and colour takes its share by fineness, so 18K gold is priced at three quarters of the gold price. A metal you gave a price per gram of its own under Advanced pricing keeps it.
- Making: per ring, and per gram of metal.
- Side stones: one price per carat and one setting charge per stone, for every accent stone whatever its size, so no ring is left unpriced. Side stones you already price by size stay as they are, and the card says so.
- Margin, added on top of metal, side stones and making, and the Rounding of the total.
- Markup on live diamonds: one markup on every centre diamond from a live feed. Blank keeps the standard markup, a larger share on smaller stones.
Beside the fields, A ring at these prices prices your default ring on our server as you type, in any of its metals: the metal with its weight and rate, the side stones, making, your margin, the centre stone the builder opens on with your markup, and the total. When these prices can't price that ring yet (no price for its metal, a stone size no tier covers, a ring not measured yet), it says why in words and shows the part prices the ring keeps instead. Use these prices saves it all and makes the book price by its formula. Everything else a price book can do stays below the card, under Advanced pricing. The launch checklist shows Prices come from the ring's weight until the book prices one way of your choosing, and links to the card.
A ring the formula can't price (a part not measured yet, a model that isn't
watertight, a setting whose centre stone is unclear) and that has no price of
its own is never sold at the making charge alone: the builder shows Price on
request and an Enquire about this ring button instead of Add to cart.
While the card prices by weight, it lists every such part with its reason. Give
it a price of its own under Advanced pricing → Your prices, or ask us to fix
its measurement. Over the API, the same list is
GET /api/public/ring-builder/pricing/weight-check?embedId=… (ringWeightCheck
in GraphQL, ringBuilder.weightCheck() in the SDK).
Your own diamond feed
From the Pro plan up, a builder's Pricing → Live diamonds can take its centre diamonds from your supplier, from our partner feed, or from both. Your markup tiers apply to every diamond either way.
Your supplier's feed is a web address (starting with https://) that answers
with your diamonds as JSON: a list, or a list under diamonds, data, items
or results. If it needs a key, add it: it is sent as a Bearer token, stored
encrypted, and never shown again. Test connection reads the feed there and
then, and tells you how many diamonds it recognised (with a few as a sample) or
why it could not read them.
Each diamond needs:
- an id (
id,stock_id,skuor its certificate number), so a quote can find the same stone again; - a carat (
caratorweight); - a price before your markup:
pricein whole units, orpriceCents.
These are read when present: shape, color, clarity, cut, polish,
symmetry, fluorescence, labGrown (true for lab-grown), the certificate's
lab (certLab or lab) and number (certNumber), measurements, currency,
image and video. A row without an id, a carat or a price is skipped.
The feed is read again every five minutes. When a shopper chooses one of your diamonds, the cart and checkout look it up again first, and if it has gone from your feed they refuse the stone rather than sell the ring at a lower price.
The same settings are on the API: GET and PATCH /api/public/ring-builder/embeds/{id}/stone-feed, and POST …/stone-feed/test
(or stoneFeed, setStoneFeed and testStoneFeed in GraphQL).
What shoppers can choose
In Pricing → Live diamonds, Stones you sell chooses natural, lab-grown or both. With both, Shoppers see first picks the side the diamond picker opens on, and shoppers switch between the two there. A store selling one kind only ever shows, quotes and sells that kind, whatever a request asks for.
The picker is the studio's diamond finder, in your builder's accent colour. It opens on the setting's shape and lists the stones as a grid or a list, a page at a time, with three recommended for the setting above them; a design made in set carats lists only stones at those weights. All filters opens every filter at once: shape (the shapes the design is made in), carat, colour, clarity, cut, price, polish, symmetry, fluorescence, grading lab and report number. Apply filter runs them, and each one stays above the list as a chip that removes it. A stone opens on its own: its picture or video, every grade, its measurements and a link to check its GIA or IGI report. Select diamond, then Apply diamond, puts it on the ring. Tick Compare on up to four stones (or Add to compare on a stone's page) to set them side by side. Applying a stone moves the setting on screen to that stone's shape and to the carat nearest it that the design is made in.
Turn on Quality tiers pick a real stone and choosing a tier such as Premium picks the best-value stone in stock that meets the tier's grades (its colour, clarity and cut or better, its certificate and its kind), at the setting's shape and carat. The shopper sees Picked for you with the stone and can Swap it from the picker. When no stone meets the tier, the tier is sold as before, and you find a stone to its grades after the order.
Over the API, the same settings are filters on the builder's stone feed
(lab, labDefault, liveTiers).
When a diamond sells
When the diamond a shopper chose has sold or left the feed, the builder takes it out of the ring and says so, rather than show a total without it. Under that note it offers up to three of the closest diamonds the feed still has: the same shape, with a carat and a price close to the one that sold, nearest first. One tap puts a match in the ring.
A shopper who comes back through a saved or shared link is told the same way when that ring's diamond has sold since the link was made, and when its price has changed, with the old price and today's side by side. The total always uses today's price.
Over the API, offer the same matches when a quote answers stoneUnavailable:
GET /api/public/ring-builder/embeds/{id}/diamonds/alternatives with the gone
stone's shape and carat (and its priceCents and id as exclude), or
diamondAlternatives in GraphQL.
Orders
Dashboard → Orders lists every ring and set paid in your builders' own checkout, newest first: the shopper's email, the total, and whether it is paid, awaiting payment or cancelled. Open one to see each piece with its size, its stone and what it cost after a set discount, and the lead it came from. A ring or a set sent to you without payment (an order request) is in Dashboard → Leads, under Order requests.
Over the API: GET /api/public/orders (and /api/public/orders/{id}) with
the orders:read scope, or orders and order in GraphQL.
Leads and a shopper's data
Saved designs, enquiries and add-to-carts arrive in Dashboard → Leads, priced the way the builder's cart prices them: your price book, the diamond the shopper chose and your engraving surcharge. Sort by Highest value to follow up the biggest rings first. Open a lead to see the ring, the diamond, the ring size and the engraving, with the price it was quoted at and what the same ring costs today. If its diamond has sold since, the lead says so. Copy link gives you the address that reopens that exact ring on your own product page, and Reply by email puts the link in a ready-to-send message. Leads saved before 10 October 2026 don't have a link and open the builder's default ring.
Order spec sheet turns a lead into one printable page for your workshop: your logo (or your account's name), pictures of the band and the setting, every choice by name, the diamond, ring size, engraving, the measured metal weight ("Not measured" when it wasn't), the customer and the quoted price, with a workshop note you type before printing. Print it, or save it as a PDF. A set's sheet (a ring with its matching bands) has a block for each piece, the ring first, each with its own choices, size, engraving, measured weight and price after the set discount, then the set's price.
The same is on the API: each lead has followUpUrl,
GET /api/public/ring-builder/quotes/{id}/price (or priceToday in GraphQL)
prices it again, and …/quotes/{id}/spec (or spec) returns the spec sheet
as data, with pieces for a set.
When a shopper asks you to delete their data, open their lead and choose Erase this shopper's data: every lead in your account with their email is deleted, and their email and engraving are removed from orders, while the order amounts stay for your records. Owners and admins can do it, and so can the API.
Related
- Connect Shopify and photograph your catalogue
Link your store by OAuth, match every variant to your ring catalogue, render a photograph for each combination, and write them back.
- Render on demand
Buy pictures and a turntable video of a design without a plan: choose the angles and the quality, pay once with PayPal, and get the full files by email.
- Add to cart and orders now count on 3D product pages
Embed analytics now count add-to-cart from your theme's own button and show the Shopify orders and revenue your 3D product pages sold.