Skip to main content

Jewelry Builder Integration Guide

This guide provides comprehensive instructions for integrating the Jewelry Builder into any third-party website or e-commerce platform. The Jewelry Builder allows your customers to design and customize jewelry directly on your site.

Terminology​

  • Jewelry Builder: A React-based application for custom jewelry design.
  • UUID: Unique identifier for each user-generated design, returned after finalization.
  • Redirect URL: The URL on your website to which users are redirected after design finalization. The UUID is appended as a query parameter.
  • Summary Page: A page on your website that displays the details of the selected design using the UUID, styled and presented according to your brand’s design, policies, and terms.

What You'll Receive​

  • Compiled React build assets (.js, .css, index.html).
  • API access, including endpoints for:
    • Fetching design configuration (by UUID).
    • Checking inventory availability.
    • Reserving inventory after checkout.
    • Placing a final purchase order.
  • API documentation and integration credentials.

Prerequisites​

  • Your website must support embedding JavaScript and React components.
  • Ability to modify scripts and containers to your website's pages.
  • A dedicated route (e.g., /build-your-own) for embedding the builder.

Integration Steps​

1. Authentication​

Authenticate using your client credentials to obtain a JWT access token for API requests.

After login, the system sets the token automatically and you can access all other APIs from here.

Loading API specification...

Request:

  • Headers:
Content-Type: application/json

Note: Include the token in the Authorization: Bearer <token> header for all protected endpoints.

2. Add a Builder Page​

Create a dedicated page/route on your site for the builder.

Example URL:

https://www.yourwebsite.com/build-your-own

3. Embed the Builder​

Add the following markup to your builder page:


<div id="caratwise-root" client-key="your_client_key" redirect-url="https://yourdomain.com/summary"></div>

<!-- Include Builder Assets -->
<link href="https://release.caratwise.com/caratwise/latest/assets/css/main.css?v=v0.2.7" rel="stylesheet" />
<script src="https://release.caratwise.com/caratwise/latest/assets/js/main.js?v=v0.2.7" defer type="module"></script>

Important:

  • In above urls v0.2.7 is a released build version. It will keep changing and you will receive update notification via email. Make sure to provide email to us.
  • The attribute redirect-url must include the full URL with your domain name where the user will be redirected after finalizing their design. Example: https://yourdomain.com/summary
  • Update client-key and redirect-url attribute with your values.
  • Ensure your website's CSS does not override builder styles.

4. Verify Builder Load​

Navigate to your builder page and confirm the builder loads within the <div id="caratwise-root">.

5. Finalize Design and Redirect​

When users complete their design, the builder redirects to your specified summary page with the UUID as a query parameter:

https://yourdomain.com/summary?uuid=ae23b4f1FS

6. Fetch Design Summary​

Retrieve complete, display-ready records for configured designs.
The response includes images, pricing, and human-readable labels that can be used to generate your product page for customers.

These endpoints ensure consistent presentation of design data across retailers and support localization via labels.

Single Designs​

Loading API specification...
  • Endpoint:
GET /api/retailer/v1/customer-design-uuid/{uuid}
  • Headers:
Authorization: Bearer <your_jwt_token>

Multiple Designs​

Loading API specification...
  • Endpoint:
POST /api/retailer/v1/customer-design-uuid/get-multiple-uuid
  • Headers:
Authorization: Bearer <your_jwt_token>
Content-Type: application/json
  • Request Body:
{
    "uuids": ["q1FxPSjzRv", "LtrnieDfaY", "dBf73J1jhG"]
}

Usage

  • Use single endpoint for individual designs.
  • Use multiple endpoint for batch requests (comparison pages, shopping carts).
  • Multiple endpoint handles invalid UUIDs gracefully without failing entire request.

Response Details:

Labels

  • The labels object is always included in the response.
  • It maps internal field keys (e.g., uuid, primary_component, secondary_component) to human-friendly display labels.
  • This ensures:
    • Consistency across clients.
    • Easier localization and updates without app changes.
    • Correct terminology aligned with business expectations.

For example:

  • key primary_component → display label Shank for ring.
  • key secondary_component → display label Head for ring.

Item Codes (item_code)

The item_code identifies each line item in the complete design.

Item CodeDescription
ring_with_certified_stoneEngagement ring with selected certified solitaire
left_bandLeft-side wedding band for the set
right_bandRight-side wedding band for the set

Why it matters:

  • Pricing, imagery, and attributes vary by item_code.
  • In order workflows / POs, item_code separates the main ring from auxiliary bands.
  • When presenting choices (e.g., build-a-set), item_code helps filter or group items.

7. Inventory Check Before Checkout​

Before initiating payment, confirm product availability:

Loading API specification...

  • Headers

    Content-Type: application/json
    Authorization: Bearer {access_token}

  • Response Structure:

    • success: Boolean indicating API call success.
    • data: Object containing inventory status for each UUID.
      • Each UUID key contains:
        1. status: String indicating availability ("available" or "not_available").
        2. message: String with additional details (empty for available items, error message for unavailable items).
        3. conflict_with: String with uuid. It will only be displayed when there is a duplicate diamond id present in any uuid.

  • Status Handling:

    • If status is "available", proceed to payment.
    • If status is "not_available", check the message field for specific reason:
      • "Inventory Not Available": Product is out of stock.
      • "UUID not found": Invalid product identifier.
      • Other messages may provide additional context.
    • When items are not available, prompt user to revise the design or remove unavailable items.

  • Error Messages:

    • "Inventory Not Available": Product is temporarily out of stock.
    • "UUID not found": The provided UUID doesn't exist in the system.
    • "Duplicate Diamond with UUID:uuid ": The provided UUID contain duplicate diamond ID.
    • Empty message: Item is available (no issues).

8. Edit & Re-Finalize Flow​

This step allows customers to update a previously configured design. If an inventory check determines that the requested design configuration is not available (e.g., diamond out of stock, component discontinued, metal not supported), the customer is redirected into the Edit Journey.

The Edit Journey can also be initiated if the customer simply wants to change any aspect of the design (stone, metal, size, engraving, etc.), even when inventory is available.

To initiate the Edit Journey, redirect the user to:

https://www.yourwebsite.com/build-your-own#/summary?uuid=<uuid>

Flow:​

  1. Inventory Check
    • If the requested configuration is unavailable, trigger the redirect to the Edit Journey.
  2. Edit Journey (Summary Screen)
    • The customer reviews the existing design.
    • Available modifications include:
      • Selecting a different stone.
      • Changing metal type or color.
      • Updating ring size.
      • Modifying other design attributes.
  3. Re-Finalize
    • After edits, Current UUID will get updated for the revised configuration.
    • The flow resumes from Step 5: Finalize Design and Redirect, now using the updated design details.

9. Create Order​

Loading API specification...

  • Purpose

    • Check inventory availability for the specified products and items.
    • Validate item combinations based on product configuration.
    • Book the inventory if available.
    • Create an order with the booked products and items.

  • Headers

    Content-Type: application/json
    Authorization: Bearer {access_token}

  • Request Body for In-Store Checkout

    {
      "uuids": {
        "PEXJuDvFqr": [
          "ring_with_certified_stone",
          "left_band",
          "right_band"
        ],
        "hDEycEvgbe": [
          "ring_with_certified_stone"
        ]
      },
      "store_id": 1
    }

  • Request Body with Shipping Address for Online Website Checkout

    {
      "uuids": {
        "PEXJuDvFqr": [
          "ring_with_certified_stone",
          "left_band",
          "right_band"
        ],
        "hDEycEvgbe": [
          "ring_with_certified_stone"
        ]
      },
      "shipping_address": {
        "first_name": "John",
        "last_name": "Doe",
        "address_line1": "Plot 12, Sector 5",
        "address_line2": "Near Industrial Hub",
        "city": "Bangalore",
        "state": "Karnataka",
        "postal_code": "560100",
        "country": "India",
        "phone_number": "+91-9123456780",
        "email": "warehouse@abcretail.com"
      }
    }

  • Request Body Parameters

    ParameterTypeRequiredDescription
    uuidsObjectYesObject with product UUID as key and array of item codes as value
    store_idIntegerNo*Identifier for the store. Required if shipping_address not provided.
    shipping_addressObjectNo*Shipping address Object. Required if store_id not provided.

  • Item Codes

    The following item codes can be included in the order for each UUID:

    Item CodeTypeDescription
    ring_with_certified_stoneStringThe main ring with certified stone
    left_bandStringLeft band component
    right_bandStringRight band component

  • Restriction

    Based on the configuration of a UUID, the following item combinations are valid:

    • Ring, Ring + left band, Ring + right band, All 3 items, Left band alone, Right band alone can only be order.
    • Both bands without ring cannot be ordered.
    • Whatever items are present in design UUID can only be ordered.

  • Response Formats

    • Success Response - Single UUID

      When all products and items are available and successfully ordered:

      {
        "success": true,
        "data": [
          {
            "PEXJuDvFqr": {
              "order_id": "CTC-O000195",
              "order_items": [
                {
                  "item_code": "ring_with_certified_stone",
                  "item_id": "CTC-I000780"
                },
                {
                  "item_code": "left_band",
                  "item_id": "CTC-I000779"
                },
                {
                  "item_code": "right_band",
                  "item_id": "CTC-I000778"
                }
              ]
            }
          } 
        ]
      }

    • Success Response - Multiple UUIDs

      When multiple products are available and successfully ordered:

      {
        "success": true,
        "data": [
          {
            "PEXJuDvFqr": {
              "order_id": "CTC-O000195",
              "order_items": [
                {
                  "item_code": "ring_with_certified_stone",
                  "item_id": "CTC-I000780"
                },
                {
                  "item_code": "left_band",
                  "item_id": "CTC-I000779"
                },
                {
                  "item_code": "right_band",
                  "item_id": "CTC-I000778"
                }
              ]
            },
            "hDEycEvgbe": {
              "order_id": "CTC-O000195",
              "order_items": [
                {
                  "item_code": "ring_with_certified_stone",
                  "item_id": "CTC-I000781"
                }
              ]
            }
          } 
        ]
      }

    • Error Response - Item Not Available in Design

      When an item is requested that is not configured for the UUID:

      {
        "success": false,
        "message": "Cannot order right_band for UUID: {UUID}. This design does not have any bands configured.",
        "code": 422
      }

    • Error Response - Invalid Band Combination

      When both left and right bands are ordered without the ring:

      {
        "success": false,
        "message": "Cannot order both left_band and right_band without ring_with_certified_stone for UUID: {UUID}. Bands-only orders with multiple bands are not allowed.",
        "code": 422
      }

    • Error Response - Mixed Status with Detailed Messages

      When some products are unavailable, duplicated, or have other issues:

      {
        "success": false,
        "data": {
          "Fpr4B4gjy5": {
            "status": "not_available",
            "message": "Inventory Not Available"
          },
          "GPQ2ANLK76": {
            "status": "available",
            "message": ""
          },
          "LtrnieDfaY": {
            "status": "not_available",
            "message": "Duplicate Diamond with UUID: GPQ2ANLK76",
            "conflict_with": "GPQ2ANLK76"
          },
          "FxxDqcfmcf": {
            "status": "not_available",
            "message": "UUID not found"
          }
        }
      }

    • Response Field Descriptions

      • Success Response Fields
      FieldTypeDescription
      successBooleanIndicates if the request was successful
      dataArray[Object]Array of objects with UUID as key and order details as value
      order_idStringUnique identifier for the created order
      order_itemsArray[Object]List of individual items within the order
      item_codeStringCode identifying the type of item (e.g., ring_with_certified_stone, left_band, right_band)
      item_idStringUnique identifier for the specific order item
      • Error Response Fields
      FieldTypeDescription
      successBooleanAlways false for error responses
      messageStringDetailed error message explaining the issue
      codeIntegerHTTP error code (422 for validation errors)
      dataObject(Optional) Object with UUID as key and status details as value for mixed status responses
      statusString(Optional in mixed responses) Status of the UUID ("available" or "not_available")
      conflict_withString(Optional) UUID that conflicts with the current one in case of duplicates

    • Possible Error Scenarios

      1. Inventory Not Available: The requested product or item is out of stock.
      2. Item Not Available in Design: The requested item is not configured for the given UUID.
      3. Invalid Band Combination: Both bands are ordered without the ring component.
      4. Duplicate Diamond: The same diamond UUID appears multiple times in the request or conflicts with another UUID.
      5. UUID Not Found: The provided UUID doesn't exist in the system.
      6. Mixed Status: Some UUIDs are successful while others have errors.

    • Notes

      • The uuids parameter now accepts an object structure where each UUID is mapped to an array of requested item codes.
      • Item validation is based on the actual configuration of each UUID. Only items that exist in the design can be ordered.
      • Bands can only be ordered independently if the UUID contains a single band, or they must be ordered with the ring component.
      • When success is true, all requested UUIDs and items were processed successfully and orders were created.
      • When success is false, the response provides detailed status information for debugging and user feedback.
      • Multiple UUIDs can be grouped under the same order_id when processed together.

  • Process Flow

    1. Validates the provided UUIDs and item codes.
    2. Verifies that requested items are available in each UUID's configuration.
    3. Checks item combination rules (e.g., prevents ordering both bands without ring).
    4. Checks inventory availability for each requested item.
    5. If all validations pass:
      • Books the inventory for the requested items.
      • Creates an order record.
      • Returns order details with item breakdown.
    6. If validation fails or inventory is unavailable, returns detailed error message with appropriate HTTP code (422 for validation errors).

10. Finalize Purchase Order​

Loading API specification...

  • Purpose

    • Finalizes the purchase order after payment confirmation.
    • Must be completed within 24 hours of payment.
    • Creates a purchase order for a single order item only.

  • Headers

    Authorization: Bearer {access_token}

  • Request Body (Form-Data)

    po_no:PO-2025-028
    amount:21847
    po_date:2025-08-25
    order_id:CTC-O000204
    order_item_ids:CTC-I000999
    reference_no:REF-98765
    note:Urgent delivery required before due date.
    bill_to:{"company_name":"ABC Retail Pvt. Ltd.","address_line1":"45 Park Street","address_line2":"Suite 10","city":"Kolkata","state":"West Bengal","postal_code":"700016","country":"India","phone_number":"+91-9876543210","email":"accounts@abcretail.com"}
    destination:{"address_line1":"Plot 12, Sector 5","address_line2":"Near Industrial Hub","city":"Bangalore","state":"Karnataka","postal_code":"560100","country":"India","phone_number":"+91-9123456780","email":"warehouse@abcretail.com"}
    pdf: @"/path/to/purchase-order-template.pdf"

    • Request Parameters

      ParameterTypeRequiredDescription
      po_noStringYesPurchase order number
      amountString/NumberYesTotal amount for the purchase order
      po_dateStringYesPurchase order date (YYYY-MM-DD)
      order_idStringYesReference to the created order
      order_item_idsStringYesSingle order item ID (only one item allowed per PO)
      reference_noStringNoExternal reference number
      noteStringNoAdditional notes or instructions
      bill_toJSON StringYesBilling address information
      destinationJSON StringYesShipping/destination address
      pdfFileYesPurchase order template PDF

  • Important Note

    • Only one order item is allowed per purchase order. If multiple items need to be processed, separate purchase orders must be created for each item.

  • Address Format

    • Bill To Address

      {
        "company_name": "ABC Retail Pvt. Ltd.",
        "address_line1": "45 Park Street",
        "address_line2": "Suite 10",
        "city": "Kolkata",
        "state": "West Bengal",
        "postal_code": "700016",
        "country": "India",
        "phone_number": "+91-9876543210",
        "email": "accounts@abcretail.com"
      }

    • Destination Address

      {
        "address_line1": "Plot 12, Sector 5",
        "address_line2": "Near Industrial Hub",
        "city": "Bangalore",
        "state": "Karnataka",
        "postal_code": "560100",
        "country": "India",
        "phone_number": "+91-9123456780",
        "email": "warehouse@abcretail.com"
      }

  • Response Formats

    • Success Response

      When the purchase order is created successfully:

      {
        "success": true,
        "message": "Purchase Order created successfully.",
        "data": {
          "due_date": "2025-09-09"
        }
      }

    • Error Responses

      • Amount Mismatch Error

        When the provided amount doesn't match the order amount:

        {
          "success": false,
          "message": "Amount does not match the order amount."
        }

      • Multiple Items Error

        When more than one order item ID is provided:

        {
        "success": false,
        "message": "Invalid PO: there must have only 1 item present."
        }

      • Duplicate Purchase Order Error

        When a purchase order with the same PO number already exists:

        {
          "success": false,
          "message": "PO already exists."
        }

      • No Order Items Error

        When no valid order items are found for the provided IDs:

        {
          "success": false,
          "message": "No order items found."
        }

    • Response Field Descriptions

      • Success Response Fields
      FieldTypeDescription
      successBooleanAlways true for successful responses
      messageStringSuccess confirmation message
      dataObjectContains additional response data
      due_dateStringExpected delivery/completion date (YYYY-MM-DD format)
      • Error Response Fields
      FieldTypeDescription
      successBooleanAlways false for error responses
      messageStringDetailed error message explaining the issue

  • Common Error Scenarios

    1. Amount Validation: The API validates that the provided amount matches the calculated order amount.
    2. Single Item Restriction: Only one order item ID is allowed per purchase order.
    3. Duplicate Prevention: The API prevents creating duplicate purchase orders with the same PO number.
    4. Data Validation: Ensures that the referenced order items exist and are valid.

  • Notes

    • Purchase orders must be finalized within 24 hours of payment confirmation.
    • Each purchase order can only contain one order item.
    • For multiple items, create separate purchase orders for each item.
    • The due_date in the response indicates when the order is expected to be fulfilled.

Flow Overview​

  1. User visits the builder page and customizes a product.
  2. After finalizing, user is redirected to the summary page with UUID.
  3. Summary page fetches and displays design details.
  4. Inventory is checked.
    • If in stock, user proceeds to payment.
    • If out of stock, prompt to revise design.
  5. Edit & Re-Finalize Flow:
    • User is redirected to #/summary?uuid=<uuid> to begin the edit journey.
    • They can modify any aspect of the design (stone, metal, size, etc.).
    • Once finalized, the UUID will get updated to reflect the revised specifications.
    • Flow resumes from Step 2 (Summary Page) with the updated design.
  6. After payment, an order is placed.
  7. The Final purchase order is placed within 24 hours.

Support​

If you need assistance with integration:

Primary Contact
Email: mitul@dholakia.ai
Phone: +91-7574087515

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

API Reference​

Authentication​

  • POST /api/retailer/v1/login — Get access token.

Fetch Design by UUID​

  • GET /api/retailer/v1/customer-design-uuid/{uuid}

Inventory Check​

  • POST /api/inventory-check

Create Order​

  • POST /api/retailer/v2/order

Place Purchase Order​

  • POST /api/retailer/v1/purchase-order