Register Product

This guide explains how to create and manage products (Sales) based on components.

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 for instructions on how to issue it.

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

Create Product

POST /api/v1/sales

1

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)
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

2

Send Request

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" }
      }
    ]
  }
}

3

Check Response

{
  "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"
  }
}

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

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

Get Single Product

GET /api/v1/sales/{id}

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

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

{
  "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

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

Delete Option

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

{
  "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.

{
  "saleIds": ["sale_ghi789"]
}

Merge Products

POST /api/v1/sales/merge

Combines multiple individual products into a single consolidated product.

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