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.3.4-rc.0" rel="stylesheet" />
<script src="https://release.caratwise.com/staging/latest/assets/js/main.js?v=v1.3.4-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.3.4" rel="stylesheet" />
<script src="https://release.caratwise.com/production/latest/assets/js/main.js?v=v1.3.4" 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 Code	Description
`ring_with_certified_stone`	Engagement ring with selected certified solitaire
`left_band`	Left-side wedding band for the set
`right_band`	Right-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:

Inventory Check
- If the requested configuration is unavailable, trigger the redirect to the Edit Journey.
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.
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}
```
metadata, customer_name, email, and notes below are optional on every request, regardless of whether you check out with store_id or shipping_address — they are shown in both examples below for that reason, not because they are tied to one checkout type.

Request Body for In-Store Checkout

{
  "uuids": {
    "PEXJuDvFqr": [
      "ring_with_certified_stone",
      "left_band",
      "right_band"
    ],
    "hDEycEvgbe": [
      "ring_with_certified_stone"
    ]
  },
  "store_id": 1,
  "metadata": {
    "PEXJuDvFqr": { "platform": "pos", "order_id": "OR000010", "client": "XYZ Jeweller" },
    "hDEycEvgbe": { "platform": "pos", "order_id": "OR000011", "client": "XYZ Jeweller" }
  },
  "customer_name": "John Doe",
  "email": "john.doe@example.com",
  "notes": "Please gift wrap the items."
}

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"
  },
  "metadata": {
    "PEXJuDvFqr": { "platform": "web", "order_id": "OR000010", "client": "XYZ Jeweller" },
    "hDEycEvgbe": { "platform": "web", "order_id": "OR000011", "client": "XYZ Jeweller" }
  },
  "customer_name": "John Doe",
  "email": "john.doe@example.com",
  "notes": "Please gift wrap the items."
}

Request Query Parameters

Parameter	Type	Required	Description
`currency`	String	No	Pass the allowed currency in the query parameters for the order. If no currency is provided, the order will be placed in the base currency. If the currency is not one of the client's allowed currencies, the request fails (see the "Error Response - Currency Not Allowed" case below).

Request Body Parameters

Parameter	Type	Required	Description
`uuids`	Object	Yes	Object with product UUID as key and array of item codes as value
`store_id`	Integer	No*	Identifier for the store. Either `store_id` or `shipping_address` must be provided.
`shipping_address`	Object	No*	Shipping address Object. Either `store_id` or `shipping_address` must be provided.
`metadata`	Object	No	Object with product UUID as key and a flat string key-value object as value. Used to attach your own reference data (e.g. your internal order ID) to each created order. At most the first 5 key-value pairs per UUID are stored — any extra pairs are dropped.
`customer_name`	String	No	Name of the end customer placing the order. Included in the purchase-order/invoice notification email sent to your PO team.
`email`	String	No	Email address of the end customer. Stored on the created order.
`notes`	String	No	Free-text notes or special instructions for the order. Included in the purchase-order/invoice notification email sent to your PO team.

Item Codes

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

Item Code Type Description
ring_with_certified_stone String The main ring with certified stone
left_band String Left band component
right_band String Right band component
Restriction

Based on the configuration of a UUID, the following item combinations are valid:
- ring_with_certified_stone alone can always be ordered.
- left_band (alone, or together with the ring) can be ordered whenever the design has at least one band configured.
- right_band (alone, or together with the ring, or together with the ring and left_band) can only be ordered when the design has both bands configured — it fails if the design only has a single band, even when combined with the ring (see the "Error Response - Right Band Unavailable" case below).
- Both bands without the ring cannot be ordered.
- Whatever items are present in design UUID can only be ordered — requesting an item that isn't configured for that UUID (e.g. a band on a design with no bands) fails validation.
- If a design UUID requires a certified diamond to be selected first (ring_with_pending_stone design type) and none has been selected yet, the order is rejected — see the "Error Response - Diamond Not Selected" case below.

Item Code	Type	Description
`ring_with_certified_stone`	String	The main ring with certified stone
`left_band`	String	Left band component
`right_band`	String	Right band component

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. Each UUID in the request always results in its own, separate order — even when they are submitted together in a single request, they are not merged under one order_id:

{
  "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-O000196",
        "order_items": [
          {
            "item_code": "ring_with_certified_stone",
            "item_id": "CTC-I000781"
          }
        ]
      }
    }
  ]
}

Error Response - Item Not Available in Design

HTTP 422. 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."
}

Error Response - Invalid Band Combination

HTTP 422. 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."
}

Error Response - Right Band Unavailable

HTTP 422. When right_band is requested but the design only has one band configured (i.e. only left_band is available):
```
{
  "success": false,
  "message": "Cannot order right_band for UUID: {UUID}. This design only has one band (left_band)."
}
```

Error Response - Diamond Not Selected

HTTP 403. When one or more UUIDs point to a design that has no certified diamond selected yet (a "pending stone" design that isn't orderable as-is):

{
  "success": false,
  "error_code": "ring_pending_stone_not_orderable",
  "message": "Cannot place order: a diamond has not been selected for one or more items.",
  "blocked": ["PEXJuDvFqr"]
}

Error Response - Currency Not Allowed

HTTP 404. When the currency query parameter is not one of the currencies allowed for the client/channel:
```
{
  "success": false,
  "message": "Allowed Currency Not found"
}
```

Mixed Status Response - Detailed Per-UUID Status

HTTP 200, success: true. Returned instead of the normal success response when one or more requested UUIDs are unavailable, not found, or duplicated — no orders are created for any UUID in the request in this case, including the ones that were available:

{
  "success": true,
  "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

Field	Type	Description
`success`	Boolean	Indicates if the request was successful
`data`	Array[Object]	Array of objects, one per UUID, each with the UUID as key and its order details as value
`order_id`	String	Unique identifier for the created order. Each UUID gets its own `order_id`, even when multiple UUIDs are submitted in the same request
`order_items`	Array[Object]	List of individual items within the order
`item_code`	String	Code identifying the type of item (e.g., ring_with_certified_stone, left_band, right_band)
`item_id`	String	Unique identifier for the specific order item

Mixed Status Response Fields

Field	Type	Description
`success`	Boolean	`true` — the request was processed, but not all UUIDs could be ordered
`data`	Object	Object with UUID as key and status details as value
`status`	String	Status of the UUID (`"available"` or `"not_available"`)
`message`	String	Detail message for the UUID's status (empty string when available)
`conflict_with`	String	(Optional) UUID of the other design already using the same diamond, when `message` indicates a duplicate

Error Response Fields

Field	Type	Description
`success`	Boolean	Always `false` for error responses
`message`	String	Detailed error message explaining the issue
`error_code`	String	(Optional) Machine-readable error code, present on the "Diamond Not Selected" (`403`) response
`blocked`	Array[String]	(Optional) UUIDs that were blocked, present on the "Diamond Not Selected" (`403`) response

The HTTP status code itself indicates the error category (422 validation, 403 forbidden, 404 not found, 401 unauthorized) — response bodies do not carry a separate numeric code field.

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. Right Band Unavailable: right_band is requested but the design only has one band configured.
5. Diamond Not Selected: The design has no certified diamond selected yet and cannot be ordered as-is (403).
6. Duplicate Diamond: The same diamond is used by multiple UUIDs in the request.
7. UUID Not Found: The provided UUID doesn't exist in the system.
8. Currency Not Allowed: The requested currency isn't one of the client's allowed currencies (404).
9. Mixed Status: Some UUIDs are available while others have errors — no orders are created for the request in this case.
Notes
- The uuids parameter 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.
- left_band can be ordered (alone or with the ring) whenever the design has at least one band configured. right_band can only be ordered — alone or with the ring — when the design has both bands configured; if the design only has one band, requesting right_band always fails, even together with the ring.
- When success is true and data is an array, all requested UUIDs and items were processed successfully and orders were created — one order per UUID.
- When success is true and data is an object (keyed by UUID), one or more UUIDs could not be ordered; the response provides detailed per-UUID status information for debugging, and no orders are created for the request.
- When success is false, the request failed validation or was rejected outright (see the Error Response cases above).
- Each UUID always gets its own order_id — UUIDs submitted together in one request are never grouped under a shared order.

Process Flow
1. Validates the request body (uuids, and either store_id or shipping_address) and the requested currency, if provided, against the client's allowed currencies.
2. Blocks any UUID whose design has no certified diamond selected yet (ring_with_pending_stone) — returns 403 immediately if any are found.
3. Verifies that requested item codes are available in each UUID's configuration and checks item combination rules (band-only restrictions, ring/band combinations).
4. Checks inventory availability for each requested item/diamond, including duplicate-diamond detection across UUIDs.
5. If any UUID is unavailable, not found, or duplicated, no orders are created for the request — returns the mixed per-UUID status response instead.
6. If all validations and availability checks pass, for each UUID:
  - Books the diamond inventory (when diamond booking is enabled for the client/channel).
  - Creates a separate order record with its own order_id.
  - Sends a purchase-order/invoice notification email to the retailer's PO team (skipped in test mode).
7. Returns order details with item breakdown for every UUID.
8. If validation fails, returns a detailed error message with the appropriate HTTP status code (422 validation, 403 diamond not selected, 404 currency not allowed).

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
  
  Parameter Type Required Description
  po_no String Yes Purchase order number
  item_id String Yes Single order item ID (only one item allowed per PO)
  pdf File No Purchase 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.

Parameter	Type	Required	Description
`po_no`	String	Yes	Purchase order number
`item_id`	String	Yes	Single order item ID (only one item allowed per PO)
`pdf`	File	No	Purchase order template PDF

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

Field	Type	Description
`success`	Boolean	Always `true` for successful responses
`message`	String	Success confirmation message
`data`	Object	Contains purchase order data
`purchase_order`	Object	Purchase order details
`file_url`	String	URL to the purchase order PDF file

Error Response Fields

Field Type Description
success Boolean Always false for error responses
message String Detailed 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:

Parameter	Type	Required	Default	Description
`page`	Integer	No	`1`	Page number (min: 1)
`limit`	Integer	No	`10`	Items per page (min: 1, max: 100)
`sort_by`	String	No	`created_at`	Field to sort by. Allowed values: `created_at`, `saved_at`
`sort_order`	String	No	`desc`	Sort direction. Allowed values: `asc`, `desc`
`saved_at`	String	No	—	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",
      "band_one_metal": null,
      "dia_origin": "Natural",
      "bands": null,
      "ring_size": 6,
      "diamond_id": "GIA-1234567890",
      "diamond_details": {
        "clarity": "VS1",
        "color": "F",
        "cut": "Excellent",
        "dia_origin": "Natural",
        "dia_shape": "Round",
        "dia_size": 1.05,
        "image_link": "https://cdn.caratwise.com/diamonds/GIA-1234567890.png",
        "lab": "GIA",
        "polish": "Excellent",
        "scs": true,
        "video_link": "https://cdn.caratwise.com/diamonds/GIA-1234567890.mp4"
      },
      "category": "ring",
      "created_at": "2024-06-01 10:30",
      "updated_at": "2024-06-02 08:15",
      "diamond_url": "https://cdn.caratwise.com/diamonds/GIA-1234567890",
      "image_urls": {
        "ring": [
          {
            "image_url": "https://cdn.caratwise.com/designs/PEXJuDvFqr/top.png",
            "image_view": "top"
          }
        ]
      },
      "style_name": "Solitaire Engagement Ring",
      "price": {
        "diamond": 1800.00,
        "setting": 650.00,
        "left_band": 0,
        "right_band": 0,
        "total": 2450.00
      },
      "ring_country_code": "US",
      "store_name": "Caratwise Flagship Store",
      "channel_type": "Online"
    }
  ],
  "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:

Field	Type	Description
`uuid`	String	Unique identifier for the saved design
`name`	String	Customer name who saved the design
`notes`	String	Notes attached to the lead
`is_ordered`	Boolean	Whether this design has been ordered
`status`	String	`"Created"` or `"Ordered"`
`saved_at`	String	Timestamp when the design was saved (`YYYY-MM-DD HH:mm`)
`type`	String	Design type (e.g., `ring`)
`style_code`	String	Computed style code for the design
`parent_style_name`	String	Human-readable name of the base style
`ring_metal`	String	Metal type for the ring shank (nullable)
`head_metal`	String	Metal type for the ring head (nullable)
`band_one_metal`	String	Metal type for the additional band, when configured (nullable)
`dia_origin`	String	Diamond origin label e.g. `Natural`, `Lab` (nullable)
`bands`	Number	Number of bands in the design (nullable)
`ring_size`	Number	Selected ring size (nullable)
`diamond_id`	String	Certificate/ID of the selected diamond (nullable)
`diamond_details`	Object	Full attribute breakdown for the selected diamond (see below). Nullable
`category`	String	Design category (nullable)
`created_at`	String	Design creation timestamp (UTC, `YYYY-MM-DD HH:mm`, nullable)
`updated_at`	String	Design last update timestamp (UTC, `YYYY-MM-DD HH:mm`, nullable)
`diamond_url`	String	Direct link to the selected diamond's detail page (nullable)
`image_urls`	Object	Design preview images grouped by view (see below). Nullable
`style_name`	String	Display name of the style/design
`price`	Object	Live price breakdown for the design (see below). Nullable
`ring_country_code`	String	ISO-2 country code used for ring sizing and metal labels (nullable)
`store_name`	String	Name of the store location associated with the lead (nullable)
`channel_type`	String	Sales channel type. One of `Online`, `Offline` (nullable)
`page`	Number	Current page number
`limit`	Number	Items per page
`total`	Number	Total number of matching leads
`total_pages`	Number	Total number of pages

Diamond Details Fields (diamond_details)

Field	Type	Description
`clarity`	String	Clarity grade (nullable)
`color`	String	Color grade (nullable)
`cut`	String	Cut grade (nullable)
`dia_origin`	String	Diamond origin e.g. `Natural`, `Lab` (nullable)
`dia_shape`	String	Diamond shape e.g. `Round` (nullable)
`dia_size`	Number	Carat weight (nullable)
`image_link`	String	Image URL for the diamond (nullable)
`lab`	String	Certifying lab e.g. `GIA` (nullable)
`polish`	String	Polish grade (nullable)
`scs`	Boolean	Whether the diamond carries SCS-007 climate-neutral certification (nullable)
`video_link`	String	Video URL for the diamond (nullable)

Image URLs Fields (image_urls)

A map keyed by image group/view; each value is an array of image objects.

Field Type Description
image_url String URL of the image
image_view String View/angle label for the image (e.g. top)

Field	Type	Description
`image_url`	String	URL of the image
`image_view`	String	View/angle label for the image (e.g. `top`)

Price Fields (price)

Field	Type	Description
`diamond`	Number	Diamond price
`setting`	Number	Setting/ring price
`left_band`	Number	Left band price, when applicable
`right_band`	Number	Right band price, when applicable
`total`	Number	Total design price

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.
- price is computed live at request time from the design's current selections; if the calculation fails for a lead, a zero-value breakdown is returned for that lead instead of failing the whole request.
- store_name and channel_type are resolved from the store location associated with the lead, and are null when that association cannot be resolved.

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:

Parameter Type Required Description
id String Yes Order ID (the increment_id from the Create Order API, e.g. CTC-O000195)

Parameter	Type	Required	Description
`id`	String	Yes	Order 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

Field	Type	Description
`customer`	String	Name of the customer the order belongs to
`increment_id`	String	Human-readable order ID (e.g. `CTC-O000195`)
`created_at`	String	Order creation timestamp (ISO 8601)
`updated_at`	String	Last update timestamp (ISO 8601, nullable)
`status`	String	Order status. One of `pending`, `processing`, `complete`, `mixed`, `cancelled`, `archived`
`b2c_price`	Number	Total order price
`tax_amount`	Number	Total tax amount on the order
`tax_percent`	Number	Tax percentage applied to the order
`price_inc_tax`	Boolean	`true` when the price is inclusive of tax (i.e. `tax_percent > 0`)
`notes`	String	Notes attached to the order
`image_url`	Array[Object]	Order preview images. Each entry has `image_url` and `image_view`
`est_ship_date`	String	Estimated ship date
`order_items`	Array[Object]	List of items in the order (see below)
`shipping_addresses`	Object	Shipping address for the order (see below). Absent for in-store orders
`metadata`	Object	Additional arbitrary order metadata (optional)

Order Item Fields (order_items[])

Field	Type	Description
`created_at`	String	Item creation timestamp (ISO 8601)
`date_updated`	String	Item last update timestamp (ISO 8601)
`uuid`	String	UUID of the design this item was created from
`item_code`	String	Item 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`
`name`	String	Display name of the item
`item_image_url`	Array[Object]	Item preview images. Each entry has `image_url` and `image_view`
`item_b2c_price`	Number	Item price
`item_tax_amount`	Number	Tax amount on the item
`tax_percent`	Number	Tax percentage applied to the item
`price_inc_tax`	Boolean	`true` when the item price is inclusive of tax
`status`	String	Human-readable item status (see Item Status Values below)
`additional_properties`	Object	Design attributes (designer, shank type, style code, total carat weight, etc.)
`solitaire`	Object	Selected diamond details (see below). Present for items with a certified stone
`size`	String	Ring size label for the item's region
`circumference`	String	Ring circumference (mm) corresponding to the size
`size_country`	String	ISO-2 country code the ring size is based on
`ring_country_code`	String	ISO-2 country code used for ring sizing
`engraving`	Object	Engraving details (text, font, etc.), when configured
`components`	Object	Component materials — `primary_component` (shank) and `secondary_component` (head)
`component_amounts`	Object	Price/tax breakdown split between the diamond and the ring metal
`po_id`	String	Purchase order ID, when a PO exists for the item
`po_number`	String	Purchase order number, when a PO exists
`po_created_at`	String	Timestamp when the PO was created
`po_due_at`	String	Deadline by which the PO must be submitted
`po_due_at_overdue`	Boolean	`true` when the PO due date has already passed
`tracking_details`	Object	Shipment tracking (`tracking_number`, `carrier`). `null` until shipped

Solitaire Fields (order_items[].solitaire)

Field	Type	Description
`name`	String	Display name of the diamond
`status`	String	Availability status of the diamond
`item_image_url`	String	Image URL for the diamond
`origin`	String	Diamond origin (e.g. `Natural`, `Lab`)
`carat`	Number	Carat weight
`color`	String	Color grade
`clarity`	String	Clarity grade
`cut`	String	Cut grade
`certification`	String	Certifying lab (e.g. `GIA`)
`certificate_masked_url`	String	Link to the (masked) diamond certificate
`item_b2c_price`	Number	Diamond price
`tax_amount`	Number	Tax amount on the diamond
`tax_percent`	Number	Tax percentage applied to the diamond
`price_inc_tax`	Boolean	`true` when the diamond price is inclusive of tax

Shipping Address Fields (shipping_addresses)

Field	Type	Description
`first_name`	String	Recipient first name
`last_name`	String	Recipient last name
`email`	String	Recipient email
`phone_number`	String	Recipient phone number
`address_line_1`	String	Address line 1
`address_line_2`	String	Address line 2
`address_line_3`	String	Address line 3
`city`	String	City
`state`	String	State / province
`postal_code`	String	Postal / ZIP code
`country`	String	Country
`is_store_address`	Boolean	`true` 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 Status	Meaning
`new`	Order item created, awaiting processing
`po_overdue`	Purchase order is overdue
`po_uploaded`	Purchase order has been uploaded
`po_accepted`	Purchase order has been accepted
`in_manufacturing`	Item is being manufactured
`in_qa`	Item is undergoing quality assurance
`qa_pass`	Item has passed final quality assurance
`shipped`	Item 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

User visits the builder page and customizes a product.
After finalizing, user is redirected to the summary page with UUID.
Summary page fetches and displays design details.
Inventory is checked.
- If in stock, user proceeds to payment.
- If out of stock, prompt to revise design.
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.
After payment, an order is placed.
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

Terminology​

What You'll Receive​

Prerequisites​

Flow chart​

Integration Steps​

1. Embed the Builder​

2. Verify Builder Load​

3. Finalize Design and Redirect​

4. API Authentication​

5. Add a Builder Page​

6. Fetch Design Summary​

Single Designs​

Multiple Designs​

7. Inventory Check Before Checkout​

8. Edit & Re-Finalize Flow​

Flow:​

9. Create Order​

10. Get Retailer Profile​

11. Send Purchase Order to Confirm order on Caratwise​

12. Get Leads (Saved Designs)​

13. Get Order Details​

Flow Overview​

API Endpoints​

Testing/Staging Environment​

Production​

API Reference​

Authentication​

Fetch Design by UUID​

Inventory Check​

Create Order​

Place Purchase Order​

Get Leads​

Get Order Details​

Support​

Terminology

What You'll Receive

Prerequisites

Flow chart

Integration Steps

1. Embed the Builder

2. Verify Builder Load

3. Finalize Design and Redirect

4. API Authentication

5. Add a Builder Page

6. Fetch Design Summary

Single Designs

Multiple Designs

7. Inventory Check Before Checkout

8. Edit & Re-Finalize Flow

Flow:

9. Create Order

10. Get Retailer Profile

11. Send Purchase Order to Confirm order on Caratwise

12. Get Leads (Saved Designs)

13. Get Order Details

Flow Overview

API Endpoints

Testing/Staging Environment

Production

API Reference

Authentication

Fetch Design by UUID

Inventory Check

Create Order

Place Purchase Order

Get Leads

Get Order Details

Support