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.

Flow chart​

Integration Steps​

1. Embed the Builder​

Add the following markup to your builder page:

For STAGING environment

<!-- Main container to render ring builder inside -->
<div id="caratwise-root" client-key="your_client_key" redirect-url="https://yourdomain.com/summary" currency="USD" ring-size-country="US"></div>

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

For PRODUCTION environment

<!-- Main container to render ring builder inside -->
<div id="caratwise-root" client-key="your_client_key" redirect-url="https://yourdomain.com/summary" currency="USD" ring-size-country="US"></div>

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

Important:

  • In the above code snippets v1.0.8-rc.1 and v1.0.81 is a released build version in staging and production. It will keep changing on regular basis. To receive update notification via email make sure to subscribe that email with us. We have give webhook call as well.
  • The attribute redirect-url is optional and controls the final step of the builder:
    • If provided: Must be the full URL (including your domain) where the user will be redirected after finalizing their design. This enables the add-to-cart and checkout flow via your summary page. Example: https://yourdomain.com/summary
    • If omitted: The Finalise button will not be shown on the last step of the builder. Users will only see the Inquire Design button.
  • Update client-key and redirect-url attribute with your values.
  • Set currency attribute according to your need. To know supported currency and enable currency you have to contact us.
  • Set ring-size-country to get ring size options based on your region. It supports ISO-2 country code format.
  • Ensure your website's CSS does not override builder styles.

2. Verify Builder Load​

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

3. 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

4. API 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.

5. Add a Builder Page​

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

Example URL:

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

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 Query Parameters

    ParameterTypeRequiredDescription
    currencyStringNoPass the allowed currency in the query parameters for the order. If no currency is provided, the order will be placed in the base currency.

  • 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. Get Retailer Profile​

Fetch retailer profile to find allowed payment method and other settings.

Loading API specification...

Request:

  • Endpoint:
GET /api/retailer/v1/client-profile
  • Headers:
Authorization: Bearer <your_jwt_token>

Important:

  • When payment terms in response is purchase_order you can initiate purchase order API call, otherwise not needed.

11. Send Purchase Order to Confirm order on Caratwise​

Loading API specification...

  • Purpose

    • Applicable to only those retailers who have purchase_order payment term available in 2. Get Retailer Profile.
    • 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}
    Accept-Language: en-GB,en-US;q=0.9,en;q=0.8
    accept: application/json

  • Request Body (Form-Data)

    po_no: 349
    item_id: CRW-D001813
    pdf: @"/path/to/purchase-order-template.pdf"

    • Request Parameters

      ParameterTypeRequiredDescription
      po_noStringYesPurchase order number
      item_idStringYesSingle order item ID (only one item allowed per PO)
      pdfFileNoPurchase 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.

  • Response Formats

    • Success Response

      When the purchase order is created successfully:

      {
        "success": true,
        "message": "Purchase Order created successfully.",
        "data": {
          "purchase_order": {
            "file_url": "https://example.com/purchase-orders/CRW-D001813.pdf"
          }
        }
      }

      When the purchase order is created successfully without file:

      {
        "success": true,
        "message": "Purchase Order created successfully.",
        "data": {
          "purchase_order": {
            "file_url": null
          }
        }
      }

  • Error Responses

    • Purchase Order Already exists Error

      When a purchase order already exists for give item:

      {
        "success": false,
        "message": "po_already_exists"
      }

    • Duplicate Purchase Order Number Error

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

      {
      "success": false,
      "message": "po_number_already_exists"
      }

    • Purchase Order Overdue Error

      When an item is in overdue status:

      {
      "success": false,
      "message": "po_overdue"
      }

    • Purchase Order for canceled order item Error

      When an item is in canceled status:

      {
      "success": false,
      "message": "order_item_is_cancelled"
      }

    • No Order Items Error

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

      {
        "success": false,
        "message": "order_item_not_found"
      }

    • Validation Error

      When required parameters are missing or invalid:

      {
        "success": false,
        "message": "body must have required property 'field_name'"
      }

  • Response Field Descriptions

    • Success Response Fields

      FieldTypeDescription
      successBooleanAlways true for successful responses
      messageStringSuccess confirmation message
      dataObjectContains purchase order data
      purchase_orderObjectPurchase order details
      file_urlStringURL to the purchase order PDF file

    • Error Response Fields

      FieldTypeDescription
      successBooleanAlways false for error responses
      messageStringDetailed error message explaining the issue

  • Common Error Scenarios

    1. PO Already Exists Restriction: The API prevents creating a purchase order for an order item if a PO already exists.
    2. Order Item status overdue or canceled Restriction: The API prevents to create an PO for order item which is overdue or canceled.
    3. Duplicate Prevention: The API prevents creating duplicate purchase orders with the same PO number.
    4. Data Validation: Ensures that the referenced order item exists and is valid.
    5. Missing Parameters: All required fields must be provided.

  • Notes

    • Purchase orders must be finalized within 24 hours of payment confirmation.
    • For multiple items, create separate purchase orders for each item.
    • The file_url in the response provides a direct link to the generated purchase order PDF.
    • The API has been simplified to require only three essential parameters: po_no, item_id, and pdf.

12. Get Leads (Saved Designs)​

Retrieve a paginated list of customer-saved designs (leads) for the authenticated retailer. Use this to build a leads dashboard, track pipeline, or monitor which designs have been ordered.

Loading API specification...
  • Endpoint:
GET /api/retailer/v1/leads
  • Headers:
Authorization: Bearer <your_jwt_token>

  • Query Parameters:

    ParameterTypeRequiredDefaultDescription
    pageIntegerNo1Page number (min: 1)
    limitIntegerNo10Items per page (min: 1, max: 100)
    sort_byStringNocreated_atField to sort by. Allowed values: created_at, saved_at
    sort_orderStringNodescSort direction. Allowed values: asc, desc
    saved_atStringNo—Filter by saved date range. Format: from:YYYY-MM-DD,to:YYYY-MM-DD

  • Success Response:

    {
      "success": true,
      "message": "Saved designs retrieved successfully",
      "data": [
        {
          "uuid": "PEXJuDvFqr",
          "name": "John Doe",
          "notes": "Customer prefers rose gold",
          "is_ordered": false,
          "status": "Created",
          "saved_at": "2024-06-01 10:30",
          "type": "ring",
          "style_code": "RP001H001",
          "parent_style_name": "Solitaire Engagement Ring",
          "ring_metal": "14K Rose Gold",
          "head_metal": "18K White Gold",
          "dia_origin": "Natural",
          "bands": null,
          "diamond_id": "GIA-1234567890"
        }
      ],
      "pagination": {
        "page": 1,
        "limit": 10,
        "total": 42,
        "total_pages": 5
      }
    }

  • Response when no leads found:

    {
      "success": true,
      "message": "No saved designs found",
      "data": [],
      "pagination": {
        "page": 1,
        "limit": 10,
        "total": 0,
        "total_pages": 0
      }
    }

  • Response Field Descriptions:

    FieldTypeDescription
    uuidStringUnique identifier for the saved design
    nameStringCustomer name who saved the design
    notesStringNotes attached to the lead
    is_orderedBooleanWhether this design has been ordered
    statusString"Created" or "Ordered"
    saved_atStringTimestamp when the design was saved (YYYY-MM-DD HH:mm)
    typeStringDesign type (e.g., ring)
    style_codeStringComputed style code for the design
    parent_style_nameStringHuman-readable name of the base style
    ring_metalStringMetal type for the ring shank (nullable)
    head_metalStringMetal type for the ring head (nullable)
    dia_originStringDiamond origin label e.g. Natural, Lab (nullable)
    bandsNumberNumber of bands in the design (nullable)
    diamond_idStringCertificate/ID of the selected diamond (nullable)
    pageNumberCurrent page number
    limitNumberItems per page
    totalNumberTotal number of matching leads
    total_pagesNumberTotal number of pages

  • Notes:

    • Results are scoped to the authenticated retailer — each retailer sees only their own leads.
    • Use saved_at filter to narrow results to a specific date range, e.g. from:2024-01-01,to:2024-06-30.
    • A lead with is_ordered: true means the design was converted to an order via the Create Order API.

13. Get Order Details​

Retrieve the complete, display-ready details of a single order using its order ID (the increment_id returned by the Create Order API). The response includes order-level pricing, images, shipping address, and a breakdown of every order item along with its solitaire, components, engraving, purchase order, and tracking information. Use this to build an order detail / order status page for your customers or staff.

Loading API specification...
  • Endpoint:
GET /api/retailer/v1/order/view/{id}
  • Headers:
Authorization: Bearer <your_jwt_token>

  • Path Parameters:

    ParameterTypeRequiredDescription
    idStringYesOrder ID (the increment_id from the Create Order API, e.g. CTC-O000195)

  • Success Response:

    {
      "success": true,
      "message": "Order Details Fetch Successfully",
      "data": {
        "customer": "John Doe",
        "increment_id": "CTC-O000195",
        "created_at": "2024-06-01T10:30:00.000Z",
        "updated_at": "2024-06-02T08:15:00.000Z",
        "status": "processing",
        "b2c_price": 2450.00,
        "tax_amount": 122.50,
        "tax_percent": 5,
        "price_inc_tax": true,
        "notes": "Customer prefers rose gold",
        "image_url": [
          {
            "image_url": "https://cdn.caratwise.com/orders/CTC-O000195/top.png",
            "image_view": "top"
          }
        ],
        "est_ship_date": "2024-06-20",
        "order_items": [
          {
            "created_at": "2024-06-01T10:30:00.000Z",
            "date_updated": "2024-06-02T08:15:00.000Z",
            "uuid": "PEXJuDvFqr",
            "item_code": "ring_with_certified_stone",
            "name": "Solitaire Engagement Ring",
            "item_image_url": [
              {
                "image_url": "https://cdn.caratwise.com/items/CTC-I000780/top.png",
                "image_view": "top"
              }
            ],
            "item_b2c_price": 2450.00,
            "item_tax_amount": 122.50,
            "tax_percent": 5,
            "price_inc_tax": true,
            "status": "in_manufacturing",
            "additional_properties": {
              "designer": "Caratwise",
              "shank_type": "solitaire",
              "style_code": "RP001H001",
              "parent_style_code": "RP001",
              "total_carat_weight": 1.05,
              "ring_country_code": "US"
            },
            "solitaire": {
              "name": "Round Brilliant 1.00ct",
              "status": "available",
              "item_image_url": "https://cdn.caratwise.com/diamonds/GIA-1234567890.png",
              "origin": "Natural",
              "carat": 1.0,
              "color": "F",
              "clarity": "VS1",
              "cut": "Excellent",
              "certification": "GIA",
              "certificate_masked_url": "https://cdn.caratwise.com/certs/GIA-1234567890.pdf",
              "item_b2c_price": 1800.00,
              "tax_amount": 90.00,
              "tax_percent": 5,
              "price_inc_tax": true
            },
            "size": "6",
            "circumference": "51.9",
            "size_country": "US",
            "ring_country_code": "US",
            "engraving": {
              "text": "Forever",
              "font": "script"
            },
            "components": {
              "primary_component": {
                "name": "Shank",
                "color": "Rose",
                "material": "14K Rose Gold"
              },
              "secondary_component": {
                "name": "Head",
                "color": "White",
                "material": "18K White Gold"
              }
            },
            "component_amounts": {
              "diamond_b2c_price": 1800.00,
              "only_ring_b2c_price": 650.00,
              "diamond_tax_amount": 90.00,
              "only_ring_tax_amount": 32.50,
              "tax_percent": 5,
              "price_inc_tax": true
            },
            "po_id": "CTC-P000045",
            "po_number": "349",
            "po_created_at": "2024-06-01T12:00:00.000Z",
            "po_due_at": "2024-06-02T12:00:00.000Z",
            "po_due_at_overdue": false,
            "tracking_details": {
              "tracking_number": "1Z999AA10123456784",
              "carrier": "UPS"
            }
          }
        ],
        "shipping_addresses": {
          "first_name": "John",
          "last_name": "Doe",
          "email": "john@example.com",
          "phone_number": "+91-9123456780",
          "address_line_1": "Plot 12, Sector 5",
          "address_line_2": "Near Industrial Hub",
          "address_line_3": "",
          "city": "Bangalore",
          "state": "Karnataka",
          "postal_code": "560100",
          "country": "India",
          "is_store_address": false
        },
        "metadata": {}
      }
    }

  • Error Responses:

    • Order Not Found (404)

      When no order matching the given ID exists for the authenticated retailer:

      {
        "success": false,
        "message": "Order Details Not Found",
        "data": []
      }

    • Invalid Request (400)

      When the id path parameter is missing or invalid:

      {
        "error": { "issues": [], "name": "ZodError" }
      }

    • Unauthorized (401)

      When the Authorization bearer token is missing, invalid, or expired:

      {
        "success": false,
        "message": "Unauthorized"
      }

    • Server Error (500)

      When an unexpected error occurs while fetching the order:

      {
        "success": false,
        "message": "Internal Server Error"
      }

  • Response Field Descriptions:

    • Order-level Fields

      FieldTypeDescription
      customerStringName of the customer the order belongs to
      increment_idStringHuman-readable order ID (e.g. CTC-O000195)
      created_atStringOrder creation timestamp (ISO 8601)
      updated_atStringLast update timestamp (ISO 8601, nullable)
      statusStringOrder status. One of pending, processing, complete, mixed, cancelled, archived
      b2c_priceNumberTotal order price
      tax_amountNumberTotal tax amount on the order
      tax_percentNumberTax percentage applied to the order
      price_inc_taxBooleantrue when the price is inclusive of tax (i.e. tax_percent > 0)
      notesStringNotes attached to the order
      image_urlArray[Object]Order preview images. Each entry has image_url and image_view
      est_ship_dateStringEstimated ship date
      order_itemsArray[Object]List of items in the order (see below)
      shipping_addressesObjectShipping address for the order (see below). Absent for in-store orders
      metadataObjectAdditional arbitrary order metadata (optional)

    • Order Item Fields (order_items[])

      FieldTypeDescription
      created_atStringItem creation timestamp (ISO 8601)
      date_updatedStringItem last update timestamp (ISO 8601)
      uuidStringUUID of the design this item was created from
      item_codeStringItem type. One of ring_with_certified_stone, ring_with_preset_center_stone, ring_mounting, ring, eternity_band, left_band, right_band, solitaire, ring_semi_mount
      nameStringDisplay name of the item
      item_image_urlArray[Object]Item preview images. Each entry has image_url and image_view
      item_b2c_priceNumberItem price
      item_tax_amountNumberTax amount on the item
      tax_percentNumberTax percentage applied to the item
      price_inc_taxBooleantrue when the item price is inclusive of tax
      statusStringHuman-readable item status (see Item Status Values below)
      additional_propertiesObjectDesign attributes (designer, shank type, style code, total carat weight, etc.)
      solitaireObjectSelected diamond details (see below). Present for items with a certified stone
      sizeStringRing size label for the item's region
      circumferenceStringRing circumference (mm) corresponding to the size
      size_countryStringISO-2 country code the ring size is based on
      ring_country_codeStringISO-2 country code used for ring sizing
      engravingObjectEngraving details (text, font, etc.), when configured
      componentsObjectComponent materials — primary_component (shank) and secondary_component (head)
      component_amountsObjectPrice/tax breakdown split between the diamond and the ring metal
      po_idStringPurchase order ID, when a PO exists for the item
      po_numberStringPurchase order number, when a PO exists
      po_created_atStringTimestamp when the PO was created
      po_due_atStringDeadline by which the PO must be submitted
      po_due_at_overdueBooleantrue when the PO due date has already passed
      tracking_detailsObjectShipment tracking (tracking_number, carrier). null until shipped

    • Solitaire Fields (order_items[].solitaire)

      FieldTypeDescription
      nameStringDisplay name of the diamond
      statusStringAvailability status of the diamond
      item_image_urlStringImage URL for the diamond
      originStringDiamond origin (e.g. Natural, Lab)
      caratNumberCarat weight
      colorStringColor grade
      clarityStringClarity grade
      cutStringCut grade
      certificationStringCertifying lab (e.g. GIA)
      certificate_masked_urlStringLink to the (masked) diamond certificate
      item_b2c_priceNumberDiamond price
      tax_amountNumberTax amount on the diamond
      tax_percentNumberTax percentage applied to the diamond
      price_inc_taxBooleantrue when the diamond price is inclusive of tax

    • Shipping Address Fields (shipping_addresses)

      FieldTypeDescription
      first_nameStringRecipient first name
      last_nameStringRecipient last name
      emailStringRecipient email
      phone_numberStringRecipient phone number
      address_line_1StringAddress line 1
      address_line_2StringAddress line 2
      address_line_3StringAddress line 3
      cityStringCity
      stateStringState / province
      postal_codeStringPostal / ZIP code
      countryStringCountry
      is_store_addressBooleantrue when the order ships to a store (in-store checkout)

  • Item Status Values

    The status field on each order item is returned as a normalized, customer-friendly value. Internal statuses are mapped as follows:

    Returned StatusMeaning
    newOrder item created, awaiting processing
    po_overduePurchase order is overdue
    po_uploadedPurchase order has been uploaded
    po_acceptedPurchase order has been accepted
    in_manufacturingItem is being manufactured
    in_qaItem is undergoing quality assurance
    qa_passItem has passed final quality assurance
    shippedItem has been shipped to the retailer

  • Notes:

    • Results are scoped to the authenticated retailer — an order can only be viewed by the retailer, channel, and client it belongs to.
    • The {id} path parameter is the order's increment_id (e.g. CTC-O000195), not the internal numeric ID.
    • Pricing fields (price_inc_tax) are computed from the applicable tax_percent; a value greater than 0 means the price is tax-inclusive.
    • solitaire, engraving, components, po_*, and tracking_details are only populated when relevant to the item (e.g. tracking_details stays null until the item ships).
    • A 404 is returned when no order matching the given ID exists for the authenticated retailer.

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 created within 24 hours using the simplified API with po_no, item_id, and pdf parameters.

API Endpoints​

Testing/Staging Environment​

  • https://staging-storeapi.caratwise.com

Production​

  • https://storeapi.caratwise.com

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/retailer/v1/inventory-check

Create Order​

  • POST /api/retailer/v2/order

Place Purchase Order​

  • POST /api/retailer/v1/purchase_order

Get Leads​

  • GET /api/retailer/v1/leads

Get Order Details​

  • GET /api/retailer/v1/order/view/{id}

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