> For the complete documentation index, see [llms.txt](https://docs.archisketch.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.archisketch.com/guide/dev-en/api-sdk/api-integration/3d-product-integration/product.md).

# Register Product

A product is a commercial unit configured using components. Use the component ID created in the previous step to generate a selling product.

You must include the `X-API-KEY` in the header of all API requests. Refer to the ["How to Use the API"](/guide/dev-en/api-sdk/how-to-use.md) guide for instructions on how to issue it.

```http
X-API-KEY: {x-api-key}
```

## Create Product

**POST** `/api/v1/sales`

{% stepper %}
{% step %}

### Prepare Required Information

To create a product, you need the basic product details and the component ID generated in the previous step.

**Main Request Fields**:

| Field        | Type    | Required | Description                                             |
| ------------ | ------- | -------- | ------------------------------------------------------- |
| info         | object  | ✅        | Basic product details ([see table below](#undefined-8)) |
| isPersonal   | boolean | ✅        | Personal library flag                                   |
| images       | array   | ✅        | List of image IDs (can be an empty array `[]`)          |
| previewImage | string  |          | Representative/Thumbnail image ID                       |
| category     | object  |          | Category information                                    |
| components   | object  |          | Constituent components (including component ID)         |

**Product Basic Info** (`info`):

| Field           | Type   | Required | Description          |
| --------------- | ------ | -------- | -------------------- |
| name            | string | ✅        | Product name         |
| translatedNames | array  | ✅        | Multilingual names   |
| description     | array  | ✅        | Product descriptions |
| tags            | array  | ✅        | Tag keywords         |
| brandCode       | string |          | Brand code           |
| code            | string |          | Product code         |
| website         | string |          | Website URL          |
| {% endstep %}   |        |          |                      |

{% step %}

### Send Request

```json
POST /api/v1/sales
X-API-KEY: {x-api-key}

{
  "info": {
    "name": "Sofa",
    "translatedNames": [
      { "code": "en", "value": "Sofa" },
      { "code": "ko", "value": "소파" }
    ],
    "description": [
      { "code": "en", "value": "A comfortable 3-seater sofa." },
      { "code": "ko", "value": "편안한 3인용 소파입니다." }
    ],
    "tags": ["sofa", "livingroom"],
    "brandCode": "BRAND_001"
  },
  "images": ["img_001"],
  "isPersonal": false,
  "components": {
    "options": [
      {
        "componentId": "cmp_def456",
        "optionValue1": "Default",
        "price": { "value": 350000, "unit": "KRW" }
      }
    ]
  }
}
```

{% endstep %}

{% step %}

### Check Response

```json
{
  "result": "SUCCESS",
  "data": {
    "id": "sale_ghi789",
    "enterpriseId": "ENT_ABC123",
    "userId": "usr_xyz",
    "name": "Sofa",
    "translatedNames": [
      { "code": "en", "value": "Sofa" },
      { "code": "ko", "value": "소파" }
    ],
    "description": [
      { "code": "ko", "value": "편안한 3인용 소파입니다." }
    ],
    "tags": ["sofa", "livingroom"],
    "brandCode": null,
    "code": null,
    "website": null,
    "minPrice": { "value": 0, "unit": "KRW" },
    "categories": [],
    "previewImage": {
      "id": "img_001",
      "name": "sofa_preview",
      "url": "https://..."
    },
    "images": [],
    "components": {
      "optionKeys": ["Option"],
      "records": [
        {
          "id": "rec_001",
          "order": 0,
          "price": { "value": 0, "unit": "KRW" },
          "options": [{ "key": "Option", "value": "Default" }],
          "previewImage": null
        }
      ]
    },
    "createdAt": "2026-04-04T10:02:00Z",
    "updatedAt": "2026-04-04T10:02:00Z"
  }
}
```

{% endstep %}
{% endstepper %}

## Get Product List

**GET** `/api/v1/sales`

| Parameter   | Type    | Required | Description                 |
| ----------- | ------- | -------- | --------------------------- |
| offset      | integer | ✅        | Page number (starts from 0) |
| limit       | integer | ✅        | Page size (1–100)           |
| userId      | string  |          | User ID filter              |
| name        | string  |          | Name search keyword         |
| code        | string  |          | Product code                |
| sku         | string  |          | SKU                         |
| brandCode   | string  |          | Brand code                  |
| categoryIds | array   |          | List of category IDs        |
| sortType    | string  |          | Sorting criteria            |

```http
GET /api/v1/sales?offset=0&limit=20&name=소파
X-API-KEY: {x-api-key}
```

## Get Single Product

**GET** `/api/v1/sales/{id}`

```http
GET /api/v1/sales/sale_ghi789
X-API-KEY: {x-api-key}
```

## Update Product

### Full Update

**PUT** `/api/v1/sales/{id}`

The Request Body structure is identical to that of the product creation endpoint.

#### Update Basic Info Only

**PATCH** `/api/v1/sales/{id}/info`

```json
PATCH /api/v1/sales/sale_ghi789/info
X-API-KEY: {x-api-key}

{
  "name": "Sofa (Updated)",
  "translatedNames": [{ "code": "en", "value": "Sofa (Updated)" }],
  "description": [{ "code": "en", "value": "This is an updated description." }],
  "tags": ["sofa", "livingroom", "3-seater"]
}
```

## Manage Product Options

You can configure multiple components into a single product by adding options such as colors and sizes.

#### Add Options

**POST** `/api/v1/sales/{id}/options`

```json
{
  "optionKey1": "Color",
  "options": [
    { "componentId": "cmp_def456", "optionValue1": "Beige" },
    { "componentId": "cmp_def789", "optionValue1": "Gray" }
  ]
}
```

### Update Options

**PATCH** `/api/v1/sales/{id}/options`

The Request Body structure is identical to that of the Add Options endpoint.

#### Update Option Price

**PATCH** `/api/v1/sales/{id}/options/{componentId}/price`

```json
{
  "price": {
    "value": 350000,
    "unit": "KRW"
  }
}
```

### Delete Option

**DELETE** `/api/v1/sales/{id}/options`

```json
{
  "ids": ["rec_001"],
  "deleteSaleIfEmpty": false
}
```

Setting `deleteSaleIfEmpty` to `true` will completely delete the product (Sale) once all of its options are deleted.

## Decompose / Merge Products

### Decompose Product

**POST** `/api/v1/sales/decompose`

Separates a single combined product into its individual component units.

```json
{
  "saleIds": ["sale_ghi789"]
}
```

### Merge Products

**POST** `/api/v1/sales/merge`

Combines multiple individual products into a single consolidated product.

```json
{
  "name": "Unified Sofa Product",
  "optionKey": "Color",
  "salesToMerge": [
    { "saleId": "sale_ghi789" },
    { "saleId": "sale_jkl012" }
  ]
}
```