Skip to main content

Magento 2 Integration Guide

Overview​

The Caratwise Jewelry Builder module embeds a powerful jewelry customization experience directly into your Magento 2 store. It empowers customers to design, configure, and purchase personalized jewelry products, with seamless backend integration to Caratwise APIs.

🔧 Features​

  • Automatically creates the CW attribute set and products upon installation.
  • Supports custom URL paths for the builder page.
  • Renders the Caratwise Jewelry Builder interface.
  • Enables users to design unique products.
  • Provides a detailed summary page similar to Magento’s standard product page.
  • Allows customized products to be added to the Magento cart from summary page.
  • Interfaces with Caratwise APIs to:
    • Fetch product data
    • Check product availability

📦 Installation​

  • Download the latest module.

  • Move the module code to the app/code/Caratwise/JewelryBuilder/ directory.

  • Run the following commands to install the module at magento root:

    bin/magento module:enable Caratwise_JewelryBuilder
    bin/magento setup:upgrade
    bin/magento setup:di:compile
    bin/magento setup:static-content:deploy

⚙️ Configuration​

Navigate to:
Admin Panel → Stores → Configuration → Caratwise → Jewelry Builder

1. General Settings​

FieldDescription
EnableEnable or disable the module’s functionality.
API EndpointBase URL of Caratwise API (retrieve from Dashboard → Channel Settings).
Client KeyUsed to load the builder on the frontend.
Secret KeyUsed for authenticated API communications with Caratwise.
Test ConnectionButton to verify the API credentials and connection.
Master URL KeySets the custom route for the builder (e.g., /design-your-own).
Builder ScriptPaste the embed script from Caratwise Docs.

2. Builder Landing Page Configuration​

FieldDescription
EnabledToggle the landing page on or off.
Builder Page TitleTitle displayed in the browser tab.
Meta Title / Keywords / DescriptionSEO metadata for the landing page.
RobotsConfigure search engine indexing behavior.

3. Builder Route Configuration​

Configure routes for specific builder types:

Engagement Ring Builder​

FieldDescription
URI PrefixExample: /engagement-ring
RobotsConfigure SEO settings.

⚠️ Only use lowercase letters, numbers, dashes (-), and underscores (_) in URI prefixes.

4. Debug Settings​

FieldDescription
Enable DebugLog all API activity and errors to var/log/caratwise.log. Useful for troubleshooting.

5. Content Security Policies (CSP)​

FieldDescription
CSP WhitelistAdd all external domains used by the builder to prevent script/content blocking.

💡 Workflow​

Load the Builder Page​

The builder will be rendered at the path defined in Master URL Key.

For example:

https://yourdomain.com/design-your-own

Cart Integration Flow​

  • After customization, a product will be created.
  • The customer can see a product page with full configuration details before add to cart.
  • The product is added to the cart from product page.
  • Customer can proceed for checkout from the cart page.

API Used​

EventAction (API Called)
Fetch product informationProduct Information
On product validationAvailability Check

🧪 Debugging​

Enable Debug Mode in configuration to track errors and API interactions:

var/log/caratwise.log

Full Functional Demo​

Frontend​

Admin​

Support​

If you need assistance with integration:

Contact
Email: ankur@dholakia.ai
Phone: +91-9925228844