# Shopiators Public API (v1.0.0)

The Shopiators Public API is the official API for integrating applications, migration tools, technology partners and third-party services with Shopiators ecommerce stores.

The API provides programmatic access to supported Shopiators store resources and can be used for ecommerce integrations, migration workflows, catalog synchronization and supported data import/export workflows.

## Servers

- **https://api.shopiators.com/api/v1** - Production server

## Authentication

### bearerAuth
- **Type**: http
- **Scheme**: bearer
- **Format**: API_KEY
Enter your API key here (e.g. sk_live_...)

## Endpoints

### GET /products

**Summary**: List products

**Tags**: Products

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| page | query | integer | No |  |
| limit | query | integer | No |  |
| search | query | string | No |  |
| handle | query | string | No |  |
| status | query | string | No |  |
| sort | query | string | No |  |

#### Responses

- **200**: A list of products

---

### POST /products

**Summary**: Create product

Creates a new product in the store.

**Notes**:
- `handle` is auto-generated from title if not provided (guaranteed unique).
- `comparePrice` must be **≥** `price`, otherwise a validation error is returned.
- `images` accepts URLs or base64 data URIs — they will be uploaded to FTP automatically.
- `selectedCollections` must be valid ObjectIds belonging to the same store.
- Providing `options` (e.g. Size, Color) will auto-generate variants and attribute combinations.


**Tags**: Products

#### Request Body

**Content-Type**: `application/json`

```json
{
  "type": "object",
  "required": [
    "title"
  ],
  "properties": {
    "title": {
      "type": "string",
      "example": "Premium Cotton T-Shirt"
    },
    "handle": {
      "type": "string",
      "description": "URL slug. Must be unique per store. Auto-generated if omitted.",
      "example": "premium-cotton-t-shirt"
    },
    "description": {
      "type": "string",
      "example": "A comfortable 100% cotton t-shirt."
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "disabled"
      ],
      "example": "active"
    },
    "price": {
      "type": "number",
      "example": 15
    },
    "comparePrice": {
      "type": "number",
      "description": "Compare at / original price. Must be >= price.",
      "example": 20
    },
    "totalStock": {
      "type": "number",
      "example": 100
    },
    "images": {
      "type": "array",
      "description": "Array of image URLs or base64 data URIs",
      "items": {
        "type": "string"
      },
      "example": [
        "https://example.com/image1.jpg"
      ]
    },
    "sizeChart": {
      "type": "string",
      "description": "URL or base64 data URI of the size chart",
      "example": "https://example.com/sizechart.jpg"
    },
    "selectedCollections": {
      "type": "array",
      "description": "Array of Collection ObjectIds",
      "items": {
        "type": "string"
      },
      "example": []
    },
    "metaTitle": {
      "type": "string",
      "example": "Buy Premium Cotton T-Shirt Online"
    },
    "metaDescription": {
      "type": "string",
      "example": "100% Cotton T-Shirt in multiple sizes."
    },
    "options": {
      "type": "array",
      "description": "Product variant options. Each option generates variants automatically.",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "Size"
          },
          "values": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "Small",
              "Medium",
              "Large"
            ]
          }
        }
      }
    }
  }
}
```

#### Responses

- **201**: Created product
- **400**: Validation error

---

### GET /products/{id}

**Summary**: Get a product by ID

**Tags**: Products

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | Yes |  |

#### Responses

- **200**: Product details
- **404**: Product not found

---

### PATCH /products/{id}

**Summary**: Update product

All fields are optional. `comparePrice` must remain >= `price` if both are provided.
Providing a `handle` that already belongs to another product will return a 400 error.


**Tags**: Products

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | Yes |  |

#### Request Body

**Content-Type**: `application/json`

```json
{
  "type": "object",
  "properties": {
    "title": {
      "type": "string"
    },
    "handle": {
      "type": "string",
      "description": "Must be unique per store"
    },
    "description": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "disabled"
      ]
    },
    "price": {
      "type": "number"
    },
    "comparePrice": {
      "type": "number",
      "description": "Must be >= price"
    },
    "totalStock": {
      "type": "number"
    },
    "images": {
      "type": "array",
      "description": "Existing URLs (kept as-is) or base64 data URIs (re-uploaded)",
      "items": {
        "type": "string"
      }
    },
    "sizeChart": {
      "type": "string"
    },
    "selectedCollections": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "metaTitle": {
      "type": "string"
    },
    "metaDescription": {
      "type": "string"
    }
  }
}
```

#### Responses

- **200**: Updated product
- **400**: Validation error
- **404**: Product not found

---

### DELETE /products/{id}

**Summary**: Delete product

Deletes a product along with its variants and attribute combinations (cascade delete).

**Tags**: Products

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | Yes |  |

#### Responses

- **200**: Product deleted
- **404**: Product not found

---

### GET /orders

**Summary**: List orders

**Tags**: Orders

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| page | query | integer | No |  |
| limit | query | integer | No |  |
| search | query | string | No |  |
| status | query | string | No |  |
| paymentStatus | query | string | No |  |
| sort | query | string | No |  |

#### Responses

- **200**: A list of orders

---

### POST /orders

**Summary**: Create an order

Creates a new order in the store. Useful for migration workflows or custom checkouts.

**Notes**:
- `customOrderId` will be auto-generated (e.g. `ORD-...`) if not provided.
- You must provide at least one item in `cartItems`.


**Tags**: Orders

#### Request Body

**Content-Type**: `application/json`

```json
{
  "type": "object",
  "required": [
    "cartItems",
    "subTotal",
    "totalAmount"
  ],
  "properties": {
    "customOrderId": {
      "type": "string",
      "description": "Unique identifier for the order. Auto-generated if omitted.",
      "example": "ORD-12345"
    },
    "cartItems": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "productId",
          "title",
          "price",
          "quantity"
        ],
        "properties": {
          "productId": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "price": {
            "type": "number"
          },
          "quantity": {
            "type": "number"
          },
          "sku": {
            "type": "string"
          }
        }
      }
    },
    "shippingAddress": {
      "$ref": "#/components/schemas/Address"
    },
    "billingAddress": {
      "$ref": "#/components/schemas/Address"
    },
    "contactEmail": {
      "type": "string",
      "example": "customer@example.com"
    },
    "orderStatus": {
      "type": "string",
      "example": "pending"
    },
    "paymentMethod": {
      "type": "string",
      "example": "credit_card"
    },
    "paymentStatus": {
      "type": "string",
      "example": "paid"
    },
    "subTotal": {
      "type": "number",
      "example": 50
    },
    "shippingCharge": {
      "type": "number",
      "example": 5
    },
    "taxAmount": {
      "type": "number",
      "example": 5.5
    },
    "totalAmount": {
      "type": "number",
      "example": 60.5
    },
    "currency": {
      "type": "string",
      "default": "USD"
    }
  }
}
```

#### Responses

- **201**: Created order
- **400**: Validation error

---

### GET /orders/{id}

**Summary**: Get an order by ID

**Tags**: Orders

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | Yes |  |

#### Responses

- **200**: Order details
- **404**: Order not found

---

### PATCH /orders/{id}

**Summary**: Update an order

Update the order status, payment status, tracking info, or handle refunds/returns.
Fields will be deeply merged where applicable (e.g., updating `refund.status` leaves the rest of the refund object intact).


**Tags**: Orders

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | Yes |  |

#### Request Body

**Content-Type**: `application/json`

```json
{
  "type": "object",
  "properties": {
    "orderStatus": {
      "type": "string",
      "example": "fulfilled"
    },
    "paymentStatus": {
      "type": "string",
      "example": "paid"
    },
    "trackingInfo": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "trackingNumber": {
            "type": "string"
          },
          "shippingCarrier": {
            "type": "string"
          },
          "trackingUrl": {
            "type": "string"
          }
        }
      }
    },
    "refund": {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "example": "Approved"
        },
        "adminRemark": {
          "type": "string"
        }
      }
    }
  }
}
```

#### Responses

- **200**: Updated order
- **400**: Validation error
- **404**: Order not found

---

### GET /customers

**Summary**: List customers

**Tags**: Customers

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| page | query | integer | No |  |
| limit | query | integer | No |  |
| search | query | string | No |  |

#### Responses

- **200**: A list of customers

---

### POST /customers

**Summary**: Create a customer

Create a new customer (user role) in the store. 
If an `address` block is provided, an Address record will be automatically created and linked to the new customer.


**Tags**: Customers

#### Request Body

**Content-Type**: `application/json`

```json
{
  "type": "object",
  "required": [
    "userName",
    "password"
  ],
  "properties": {
    "userName": {
      "type": "string"
    },
    "email": {
      "type": "string"
    },
    "password": {
      "type": "string"
    },
    "firstName": {
      "type": "string"
    },
    "lastName": {
      "type": "string"
    },
    "phoneNumber": {
      "type": "string"
    },
    "address": {
      "$ref": "#/components/schemas/AddressPayload"
    }
  }
}
```

#### Responses

- **201**: Created customer
- **400**: Validation error

---

### GET /customers/{id}

**Summary**: Get a customer by ID

**Tags**: Customers

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | Yes |  |

#### Responses

- **200**: Customer details
- **404**: Customer not found

---

### PATCH /customers/{id}

**Summary**: Update a customer

**Tags**: Customers

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | Yes |  |

#### Request Body

**Content-Type**: `application/json`

```json
{
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string"
    },
    "lastName": {
      "type": "string"
    }
  }
}
```

#### Responses

- **200**: Updated customer
- **400**: Validation error
- **404**: Customer not found

---

### GET /customers/{customerId}/addresses

**Summary**: List addresses for a customer

**Tags**: Customers

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| customerId | path | string | Yes |  |

#### Responses

- **200**: A list of customer addresses

---

### POST /customers/{customerId}/addresses

**Summary**: Add an address to a customer

**Tags**: Customers

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| customerId | path | string | Yes |  |

#### Request Body

**Content-Type**: `application/json`

```json
{
  "$ref": "#/components/schemas/AddressPayload"
}
```

#### Responses

- **201**: Created address

---

### GET /collections

**Summary**: List collections

**Tags**: Collections

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| page | query | integer | No |  |
| limit | query | integer | No |  |
| search | query | string | No |  |
| sort | query | string | No |  |

#### Responses

- **200**: A list of collections

---

### POST /collections

**Summary**: Create collection

**Tags**: Collections

#### Request Body

**Content-Type**: `application/json`

```json
{
  "type": "object",
  "required": [
    "title"
  ],
  "properties": {
    "title": {
      "type": "string",
      "example": "Summer Sale"
    },
    "handle": {
      "type": "string",
      "example": "summer-sale"
    },
    "description": {
      "type": "string",
      "example": "Best deals of the summer."
    },
    "image": {
      "type": "string",
      "example": "https://images.example.com/banner.jpg"
    },
    "collectionType": {
      "type": "string",
      "enum": [
        "manual",
        "smart"
      ],
      "example": "manual"
    },
    "selectedProducts": {
      "type": "array",
      "description": "Array of Product ObjectIds (for manual collections)",
      "items": {
        "type": "string"
      },
      "example": []
    },
    "parentCollection": {
      "type": "string",
      "description": "ObjectId of parent collection"
    },
    "matchType": {
      "type": "string",
      "enum": [
        "all condition",
        "any condition"
      ],
      "description": "For smart collections"
    },
    "conditions": {
      "type": "array",
      "description": "Smart collection filter rules",
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "example": "title"
          },
          "operator": {
            "type": "string",
            "example": "contains"
          },
          "value": {
            "type": "string",
            "example": "shirt"
          }
        }
      }
    },
    "metaTitle": {
      "type": "string"
    },
    "metaDescription": {
      "type": "string"
    },
    "metaKeywords": {
      "type": "string"
    }
  }
}
```

#### Responses

- **201**: Created collection
- **400**: Validation error

---

### GET /collections/{id}

**Summary**: Get a collection by ID

**Tags**: Collections

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | Yes |  |

#### Responses

- **200**: Collection details
- **404**: Collection not found

---

### PATCH /collections/{id}

**Summary**: Update collection

**Tags**: Collections

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | Yes |  |

#### Request Body

**Content-Type**: `application/json`

```json
{
  "type": "object",
  "properties": {
    "title": {
      "type": "string"
    },
    "handle": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "image": {
      "type": "string"
    },
    "collectionType": {
      "type": "string",
      "enum": [
        "manual",
        "smart"
      ]
    },
    "selectedProducts": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "parentCollection": {
      "type": "string"
    },
    "matchType": {
      "type": "string",
      "enum": [
        "all condition",
        "any condition"
      ]
    },
    "conditions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string"
          },
          "operator": {
            "type": "string"
          },
          "value": {
            "type": "string"
          }
        }
      }
    },
    "metaTitle": {
      "type": "string"
    },
    "metaDescription": {
      "type": "string"
    },
    "metaKeywords": {
      "type": "string"
    }
  }
}
```

#### Responses

- **200**: Updated collection
- **404**: Collection not found

---

### DELETE /collections/{id}

**Summary**: Delete collection

**Tags**: Collections

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | Yes |  |

#### Responses

- **200**: Collection deleted
- **404**: Collection not found

---

### POST /auth

**Summary**: Authenticate merchant

Authenticate a store admin using storeSlug, email, and password to receive a JWT access token.

**Tags**: Auth

#### Request Body

**Content-Type**: `application/json`

```json
{
  "type": "object",
  "required": [
    "storeSlug",
    "email",
    "password"
  ],
  "properties": {
    "storeSlug": {
      "type": "string"
    },
    "email": {
      "type": "string"
    },
    "password": {
      "type": "string"
    }
  }
}
```

#### Responses

- **200**: Successfully authenticated
- **401**: Invalid credentials
- **429**: Too many requests

---

### GET /attributes

**Summary**: List attributes

**Tags**: Attributes

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| page | query | integer | No |  |
| limit | query | integer | No |  |
| search | query | string | No |  |
| sort | query | string | No |  |

#### Responses

- **200**: A list of attributes

---

### POST /attributes

**Summary**: Create attribute

Creates a new attribute. The `values` array accepts plain strings (e.g. "Red", "Blue").
If an AttributeValue with that name already exists for this attribute, its ID will be reused.
Otherwise a new AttributeValue will be created automatically.


**Tags**: Attributes

#### Request Body

**Content-Type**: `application/json`

```json
{
  "type": "object",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "example": "Color"
    },
    "attributeset": {
      "type": "string",
      "description": "ObjectId of an existing AttributeSet",
      "example": "64f1e2b3c9e77b001f8e4abc"
    },
    "values": {
      "type": "array",
      "description": "Array of value names (strings). IDs will be resolved/created automatically.",
      "items": {
        "type": "string"
      },
      "example": [
        "Red",
        "Blue",
        "Green"
      ]
    }
  }
}
```

#### Responses

- **201**: Created attribute
- **400**: Validation error

---

### GET /attributes/{id}

**Summary**: Get an attribute by ID

**Tags**: Attributes

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | Yes |  |

#### Responses

- **200**: Attribute details
- **404**: Attribute not found

---

### PATCH /attributes/{id}

**Summary**: Update attribute

Updates an attribute. The `values` array accepts plain strings — same upsert logic as create applies.


**Tags**: Attributes

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | Yes |  |

#### Request Body

**Content-Type**: `application/json`

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "example": "Size"
    },
    "attributeset": {
      "type": "string",
      "example": "64f1e2b3c9e77b001f8e4abc"
    },
    "values": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "example": [
        "Small",
        "Medium",
        "Large"
      ]
    }
  }
}
```

#### Responses

- **200**: Updated attribute
- **404**: Attribute not found

---

### DELETE /attributes/{id}

**Summary**: Delete attribute

**Tags**: Attributes

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | Yes |  |

#### Responses

- **200**: Attribute deleted
- **404**: Attribute not found

---

### GET /attribute-sets

**Summary**: List attribute sets

**Tags**: Attribute Sets

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| page | query | integer | No |  |
| limit | query | integer | No |  |
| search | query | string | No |  |
| status | query | string | No |  |
| sort | query | string | No |  |

#### Responses

- **200**: A list of attribute sets

---

### POST /attribute-sets

**Summary**: Create attribute set

**Tags**: Attribute Sets

#### Request Body

**Content-Type**: `application/json`

```json
{
  "type": "object",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "example": "Clothing Attributes"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "inactive"
      ],
      "example": "active"
    }
  }
}
```

#### Responses

- **201**: Created attribute set
- **400**: Validation error

---

### GET /attribute-sets/{id}

**Summary**: Get an attribute set by ID

**Tags**: Attribute Sets

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | Yes |  |

#### Responses

- **200**: Attribute set details
- **404**: Attribute set not found

---

### PATCH /attribute-sets/{id}

**Summary**: Update attribute set

**Tags**: Attribute Sets

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | Yes |  |

#### Request Body

**Content-Type**: `application/json`

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "example": "Updated Attribute Set Name"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "inactive"
      ]
    }
  }
}
```

#### Responses

- **200**: Updated attribute set
- **404**: Attribute set not found

---

### DELETE /attribute-sets/{id}

**Summary**: Delete attribute set

**Tags**: Attribute Sets

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | Yes |  |

#### Responses

- **200**: Attribute set deleted
- **404**: Attribute set not found

---

### GET /addresses/{id}

**Summary**: Get an address by ID

**Tags**: Addresses

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | Yes |  |

#### Responses

- **200**: Address details
- **404**: Address not found

---

### PATCH /addresses/{id}

**Summary**: Update an address

**Tags**: Addresses

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | Yes |  |

#### Request Body

**Content-Type**: `application/json`

```json
{
  "type": "object",
  "properties": {
    "house": {
      "type": "string"
    },
    "street": {
      "type": "string"
    },
    "city": {
      "type": "string"
    },
    "isDefault": {
      "type": "boolean"
    }
  }
}
```

#### Responses

- **200**: Updated address
- **400**: Validation error
- **404**: Address not found

---

### DELETE /addresses/{id}

**Summary**: Delete an address

**Tags**: Addresses

#### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| id | path | string | Yes |  |

#### Responses

- **200**: Deleted successfully
- **404**: Address not found

---

## Data Models (Schemas)

### AttributeSet

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "example": "64f1e2b3c9e77b001f8e4abc"
    },
    "name": {
      "type": "string",
      "example": "Clothing Attributes"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "inactive"
      ],
      "example": "active"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time"
    }
  }
}
```

### AttributeValue

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "example": "64f1e2b3c9e77b001f8e4def"
    },
    "attribute": {
      "type": "string",
      "description": "ObjectId reference to parent Attribute",
      "example": "64f1e2b3c9e77b001f8e4aaa"
    },
    "name": {
      "type": "string",
      "example": "Red"
    },
    "value": {
      "type": "string",
      "example": "Red"
    },
    "hex": {
      "type": "string",
      "description": "Optional hex code for color swatches",
      "example": "#FF0000"
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "inactive"
      ],
      "example": "active"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    }
  }
}
```

### Attribute

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "example": "64f1e2b3c9e77b001f8e4aaa"
    },
    "name": {
      "type": "string",
      "example": "Color"
    },
    "attributeset": {
      "type": "string",
      "description": "ObjectId reference to an AttributeSet",
      "example": "64f1e2b3c9e77b001f8e4abc"
    },
    "values": {
      "type": "array",
      "description": "Array of AttributeValue ObjectIds",
      "items": {
        "type": "string"
      },
      "example": [
        "64f1e2b3c9e77b001f8e4def"
      ]
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time"
    }
  }
}
```

### Variant

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "example": "64f1e2b3c9e77b001f8e4bbb"
    },
    "productId": {
      "type": "string",
      "description": "ObjectId reference to parent Product",
      "example": "64f1e2b3c9e77b001f8e4ccc"
    },
    "attributes": {
      "type": "object",
      "description": "Key-value map of attribute name to value (e.g. { \"Color\": \"Red\", \"Size\": \"M\" })",
      "additionalProperties": {
        "type": "string"
      },
      "example": {
        "Color": "Red",
        "Size": "M"
      }
    },
    "price": {
      "type": "number",
      "example": 15
    },
    "salePrice": {
      "type": "number",
      "example": 12
    },
    "stock": {
      "type": "number",
      "example": 100
    },
    "sku": {
      "type": "string",
      "example": "TSHIRT-RED-M"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    }
  }
}
```

### Product

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "example": "64f1e2b3c9e77b001f8e4ccc"
    },
    "title": {
      "type": "string",
      "example": "Premium Cotton T-Shirt"
    },
    "handle": {
      "type": "string",
      "description": "URL-friendly slug (auto-generated if not provided)",
      "example": "premium-cotton-t-shirt"
    },
    "description": {
      "type": "string",
      "example": "A comfortable 100% cotton t-shirt."
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "disabled"
      ],
      "example": "active"
    },
    "badge": {
      "type": "string",
      "example": "New"
    },
    "price": {
      "type": "number",
      "example": 15
    },
    "salePrice": {
      "type": "number",
      "description": "Strike-through/original price (mapped from comparePrice on input)",
      "example": 20
    },
    "comparePrice": {
      "type": "number",
      "description": "Compare at price (must be >= price)",
      "example": 20
    },
    "totalStock": {
      "type": "number",
      "example": 200
    },
    "image": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "example": [
        "https://images.example.com/shirt.jpg"
      ]
    },
    "sizeChart": {
      "type": "string",
      "description": "URL or base64 data URI of size chart",
      "example": "https://images.example.com/sizechart.jpg"
    },
    "selectedCollection": {
      "type": "array",
      "description": "Array of Collection ObjectIds this product belongs to",
      "items": {
        "type": "string"
      },
      "example": [
        "64f1e2b3c9e77b001f8e4ddd"
      ]
    },
    "attributeSet": {
      "type": "string",
      "description": "ObjectId reference to an AttributeSet",
      "example": "64f1e2b3c9e77b001f8e4abc"
    },
    "options": {
      "type": "array",
      "description": "Product variant options (e.g. Size, Color)",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "Size"
          },
          "values": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "Small",
              "Medium",
              "Large"
            ]
          }
        }
      }
    },
    "variants": {
      "type": "array",
      "description": "Array of populated Variant objects",
      "items": {
        "$ref": "#/components/schemas/Variant"
      }
    },
    "metaTitle": {
      "type": "string",
      "example": "Buy Premium Cotton T-Shirt Online"
    },
    "metaDescription": {
      "type": "string",
      "example": "100% Cotton T-Shirt in multiple sizes."
    },
    "metaKeywords": {
      "type": "string",
      "example": "t-shirt, cotton, clothing"
    },
    "returnConfig": {
      "type": "object",
      "properties": {
        "useGlobalConfig": {
          "type": "boolean",
          "example": true
        },
        "returnable": {
          "type": "boolean"
        },
        "exchangeable": {
          "type": "boolean"
        },
        "customReturnWindow": {
          "type": "number",
          "description": "Days; overrides store setting when useGlobalConfig is false"
        }
      }
    },
    "averageRating": {
      "type": "number",
      "example": 4.5
    },
    "totalReviews": {
      "type": "number",
      "example": 120
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time"
    }
  }
}
```

### Collection

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "example": "64f1e2b3c9e77b001f8e4ddd"
    },
    "title": {
      "type": "string",
      "example": "Summer Sale"
    },
    "handle": {
      "type": "string",
      "description": "URL-friendly slug",
      "example": "summer-sale"
    },
    "description": {
      "type": "string",
      "example": "Best deals of the summer season."
    },
    "image": {
      "type": "string",
      "example": "https://images.example.com/summer-sale.jpg"
    },
    "collectionType": {
      "type": "string",
      "enum": [
        "manual",
        "smart"
      ],
      "example": "manual"
    },
    "selectedProducts": {
      "type": "array",
      "description": "Array of Product ObjectIds (for manual collections)",
      "items": {
        "type": "string"
      },
      "example": [
        "64f1e2b3c9e77b001f8e4ccc"
      ]
    },
    "parentCollection": {
      "type": "string",
      "description": "ObjectId of parent collection",
      "example": "64f1e2b3c9e77b001f8e4eee"
    },
    "childCollection": {
      "type": "array",
      "description": "Array of child Collection ObjectIds",
      "items": {
        "type": "string"
      }
    },
    "matchType": {
      "type": "string",
      "enum": [
        "all condition",
        "any condition"
      ],
      "description": "Used for smart collections",
      "example": "all condition"
    },
    "conditions": {
      "type": "array",
      "description": "Smart collection filter rules",
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "example": "title"
          },
          "operator": {
            "type": "string",
            "example": "contains"
          },
          "value": {
            "type": "string",
            "example": "shirt"
          }
        }
      }
    },
    "metaTitle": {
      "type": "string",
      "example": "Summer Sale Collection"
    },
    "metaDescription": {
      "type": "string",
      "example": "Shop our best summer deals."
    },
    "metaKeywords": {
      "type": "string"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time"
    }
  }
}
```

### Pagination

```json
{
  "type": "object",
  "properties": {
    "page": {
      "type": "integer",
      "example": 1
    },
    "limit": {
      "type": "integer",
      "example": 25
    },
    "total": {
      "type": "integer",
      "example": 100
    },
    "totalPages": {
      "type": "integer",
      "example": 4
    }
  }
}
```

### Error

```json
{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean",
      "example": false
    },
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "example": "VALIDATION_ERROR"
        },
        "message": {
          "type": "string",
          "example": "price should be less than compare at price"
        },
        "details": {
          "type": "array",
          "items": {
            "type": "object"
          }
        }
      }
    }
  }
}
```

### Customer

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "example": "64f1e2b3c9e77b001f8e4ccc"
    },
    "userName": {
      "type": "string",
      "example": "johndoe123"
    },
    "email": {
      "type": "string",
      "example": "john@example.com"
    },
    "firstName": {
      "type": "string",
      "example": "John"
    },
    "lastName": {
      "type": "string",
      "example": "Doe"
    },
    "businessName": {
      "type": "string",
      "example": "Doe Industries"
    },
    "phoneNumber": {
      "type": "string",
      "example": "+1234567890"
    },
    "role": {
      "type": "string",
      "example": "user"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time"
    }
  }
}
```

### AddressPayload

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "example": "64f1e2b3c9e77b001f8e4cdd"
    },
    "name": {
      "type": "string",
      "example": "Home Address"
    },
    "email": {
      "type": "string",
      "example": "john@example.com"
    },
    "house": {
      "type": "string",
      "example": "Apt 4B"
    },
    "street": {
      "type": "string",
      "example": "123 Main St"
    },
    "landmark": {
      "type": "string",
      "example": "Near Central Park"
    },
    "city": {
      "type": "string",
      "example": "New York"
    },
    "stateName": {
      "type": "string",
      "example": "New York"
    },
    "countryName": {
      "type": "string",
      "example": "United States"
    },
    "pincode": {
      "type": "string",
      "example": "10001"
    },
    "phone": {
      "type": "string",
      "example": "+1234567890"
    },
    "addressType": {
      "type": "string",
      "enum": [
        "Home",
        "Work",
        "Other"
      ],
      "example": "Home"
    },
    "isDefault": {
      "type": "boolean",
      "example": true
    }
  }
}
```

### Address

```json
{
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string",
      "example": "John"
    },
    "lastName": {
      "type": "string",
      "example": "Doe"
    },
    "address1": {
      "type": "string",
      "example": "123 Main St"
    },
    "address2": {
      "type": "string",
      "example": "Apt 4B"
    },
    "city": {
      "type": "string",
      "example": "New York"
    },
    "state": {
      "type": "string",
      "example": "NY"
    },
    "zip": {
      "type": "string",
      "example": "10001"
    },
    "country": {
      "type": "string",
      "example": "USA"
    },
    "phone": {
      "type": "string",
      "example": "+1234567890"
    }
  }
}
```

### Order

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "example": "64f1e2b3c9e77b001f8e4ccc"
    },
    "customOrderId": {
      "type": "string",
      "example": "ORD-1698765432-ABC"
    },
    "userId": {
      "type": "string"
    },
    "cartItems": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "productId": {
            "type": "string"
          },
          "title": {
            "type": "string",
            "example": "Premium T-Shirt"
          },
          "price": {
            "type": "number",
            "example": 25
          },
          "quantity": {
            "type": "number",
            "example": 2
          },
          "sku": {
            "type": "string",
            "example": "TSHIRT-01"
          }
        }
      }
    },
    "shippingAddress": {
      "$ref": "#/components/schemas/Address"
    },
    "billingAddress": {
      "$ref": "#/components/schemas/Address"
    },
    "contactEmail": {
      "type": "string",
      "example": "customer@example.com"
    },
    "orderStatus": {
      "type": "string",
      "example": "pending"
    },
    "paymentMethod": {
      "type": "string",
      "example": "credit_card"
    },
    "paymentStatus": {
      "type": "string",
      "example": "paid"
    },
    "subTotal": {
      "type": "number",
      "example": 50
    },
    "shippingCharge": {
      "type": "number",
      "example": 5
    },
    "taxAmount": {
      "type": "number",
      "example": 5.5
    },
    "totalAmount": {
      "type": "number",
      "example": 60.5
    },
    "currency": {
      "type": "string",
      "example": "USD"
    },
    "trackingInfo": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "trackingNumber": {
            "type": "string"
          },
          "shippingCarrier": {
            "type": "string"
          },
          "trackingUrl": {
            "type": "string"
          }
        }
      }
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time"
    }
  }
}
```