Set up the Caratwise Ring Builder on a Thinkspace website

Before you begin

Confirm that:

• The Caratwise builder, summary, API proxy, preferences, and webhooks are deployed to the retailer's MT runtime. Admin records alone do not deploy the integration.
• Caratwise supplied the retailer's client key and secret key.
• Caratwise confirmed whether the account is for staging or production.
• The final builder URL is known, such as /caratwise-ring-builder/.
• Support confirmed whether the website uses Shopping Cart.
• For an inquiry-only website, support selected the existing email form that should appear on the summary Page.

1. Configure Catalog Preferences

Open Preferences > Catalog, find Caratwise Jewelry Builder Integration, and enter:

Save the preferences. The Caratwise login token is cached per website for up to 55 minutes. If credentials change and an immediate retest is required, ask engineering to invalidate only that site's Caratwise token cache. Do not flush shared Redis data.

2. Create the TSJ custom-item cart API key

1. Sign in to Thinkspace admin for the retailer website.
2. Confirm that a dedicated, least-privilege storefront API user exists. Do not select a staff or administrator user.
3. Open Auth Token > Tokens. If it is not shown in navigation, open /admin/authtoken/token/ on the retailer's domain.
4. Select Add Token.
5. Select the dedicated storefront API user.
6. Save. Thinkspace generates the API key automatically.
7. Copy the generated key from the Tokens list and store it using the approved credential-handling process until it is entered in the summary Page options.

Each user can have only one token. If the user already has one, use the existing approved key or follow the established rotation process. Deleting or replacing a token immediately breaks every Page or integration still using the old value.

Paste only the generated key into api_token. Do not add Token, quotation marks, or extra spaces. The template adds the authorization prefix.

3. Create the Page Templates

Open Pages > Page Templates. Create both records below if they do not already exist.

Caratwise Ring Builder

Caratwise Ring Summary

Use the relative paths exactly as shown. Do not include a theme templates directory or a leading slash.

Note: The Page Templates list's template-update action does not create these custom records. Add them manually.

Define the Builder options

Open Caratwise Ring Builder, select Edit Options, and add the following case-sensitive options:

Define the Summary options

Open Caratwise Ring Summary, select Edit Options, and add:

4. Create the Builder and Summary Pages

Builder Page

Open Pages > Pages, select Add Page, and use:

Open the Builder Page's Edit Options cog and set:

• summary_url: Complete canonical URL, for example https://www.example.com/caratwise-ring-builder/summary/.
• currency: Normally USD.
• ring_size_country: Normally US.
• is_production: No for staging; Yes only after production credentials are ready.
• asset_version: Blank unless Caratwise or engineering supplies a value.
• client_key: Normally blank so Catalog Preferences supplies it.

Summary Page

Open the Summary Page's Edit Options cog and set:

• builder_url: /caratwise-ring-builder/.
• api_token: Blank for inquiry-only websites; the key from step 2 for cart-enabled websites.

Keep both Pages public. Do not add the Summary Page to navigation; Caratwise sends customers there with a design UUID such as ?uuid=hmwc61tmyd.

5. Configure inquiry-only websites

The Summary Page can reuse an existing form such as Contact Us. A separate Caratwise form is not required.

1. Open the existing form under Email Forms/Forms.
2. Add a field with type Site/Item URL, name item_url, label Design URL, Required off, and Hide on.
3. Open Pages > Pages and select the Summary Page's Edit Contents action.
4. Find the caratwise-inquiry widget dock.
5. Add a Form widget and select the existing Contact Us or inquiry form.
6. Save and preview with a valid design UUID.

The submitted field clearly identifies the design:

Open Preferences > Commerce, turn off Enable Shopping Cart, and leave the Summary Page's api_token blank. If the inquiry dock is empty, the Page displays a Contact Us link as a fallback.

6. Configure shopping-cart websites

Open Preferences > Commerce and configure:

• Enable Shopping Cart: On.
• Recipient(s): Addresses that should receive webhook-failure notifications.
• Advanced > Pre Webhook: caratwise_pre_checkout.
• Advanced > Post Webhook: caratwise_post_checkout.

Confirm the Summary Page's api_token contains only the custom-item cart API key created in step 2.

7. Add navigation

Add only the Builder Page to the appropriate menu or call-to-action. Do not link the Summary Page directly because it requires a UUID supplied by Caratwise. Suggested labels include Design Your Ring, Build Your Engagement Ring, and Create Your Ring.

8. Test before launch

Test with staging credentials and assets first.

1. Open the Builder while logged out and confirm it loads full width without browser-console errors.
2. Complete a design and confirm Caratwise redirects to the Summary Page with ?uuid=....
3. Open the Summary URL while logged out or in a private window.
4. Confirm the image gallery, price, availability, metal, size, diamond, setting, and certificate details appear when supplied.
5. Select Edit Design and confirm the same design opens in the Builder.
6. For inquiry sites, submit the inline form and confirm the notification includes Caratwise Design <uuid> and a working URL.
7. For cart sites, test Add to Cart while logged out and confirm the correct name, image, price, and UUID reach the cart.
8. For cart sites, complete a staging checkout and confirm the inventory check and Caratwise order creation succeed.
9. Confirm the Caratwise order response is stored on the Thinkspace order.

After staging passes, switch the Catalog API URL, Caratwise credentials, and Builder is_production option together. Retest the complete production flow.

Troubleshooting