Appearance
카탈로그 - 콤보(세트상품) 
콤보 기능이 보이지 않아요
ALPHA 콤보(세트) 기능은 현재 일부 매장에만 지원 중인 기능이에요.
Types
ALPHA 콤보(세트상품) (CatalogCombo)
콤보(세트상품)는 여러 상품을 한 번에 할인된 가격으로 묶어 판매할 수 있는 상품종입니다. 예를 들어 '음료+디저트 세트' 콤보에 '음료'와 '디저트' 상품군을 두고, 고객은 상품군에서 각각 하나씩 상품을 골라 주문합니다.
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
id | String | ✅ | 콤보 ID | "42" |
merchantId | Long | ✅ | 매장 ID | 42 |
title | String | ✅ | 콤보명 | "음료+디저트 세트" |
code | String | 콤보 코드 | "" | |
enabled | Boolean | ✅ | 콤보 활성화 및 노출 여부 유의: 토스 POS에서 설정하는 '고객용 채널 노출' 여부를 나타내는 설정이 아니에요. | true |
order | Int | ✅ | 정렬 순서 | 1 |
description | String | ✅ | 콤보 설명 | "" |
imageUrl | String | 콤보 이미지 URL | "" | |
labels | String[] | 콤보 라벨 목록 | ["신규"] | |
basePriceValue | Long | ✅ | 콤보 판매 가격 | 9000 |
originalPriceValue | Long | 콤보 원래 가격 콤보를 구성하는 상품의 원래 가격 합계 | 10000 | |
targetGroups | CatalogComboTargetGroup[] | ✅ | 콤보 구성 상품군 목록 | |
attributes | [String: Any] | 기타 속성 | {"key": "value"} | |
createdAt | timestamp | ✅ | 생성 시각 | "2025-09-01T00:00:00Z" |
updatedAt | timestamp | ✅ | 수정 시각 | "2025-09-01T00:00:00Z" |
ALPHA 콤보 구성 상품군 (CatalogComboTargetGroup)
콤보를 구성하는 상품군입니다. 예를 들어 '음료+디저트 세트'에서 '음료', '디저트'가 바로 상품군입니다. 콤보 등록 시 각 상품군에서 고를 수 있는 상품 목록을 지정해 두어야 합니다.
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
id | String | ✅ | 상품군 ID | "42" |
merchantId | Long | ✅ | 매장 ID | 42 |
title | String | ✅ | 상품군명 | "음료" |
description | String | ✅ | 상품군 설명 | "" |
order | Int | ✅ | 상품군 배치 순서 | 1 |
minQuantity | Int | ✅ | 선택 가능한 최소 상품 개수 | 1 |
maxQuantity | Int | ✅ | 선택 가능한 최대 상품 개수 | 3 |
targets | CatalogComboTarget[] | ✅ | 상품군에 포함된 상품 목록 |
ALPHA 콤보 구성 (CatalogComboTarget)
콤보 구성입니다. 예를 들어 '음료+디저트 세트'에서 '음료' 상품군에 속한 '아메리카노', '카페라떼'와 같은 상품이 바로 콤보 구성입니다. 고객은 상품군에서 각각 구성 상품을 골라 주문합니다.
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
id | String | ✅ | 구성 ID | "42" |
merchantId | Long | ✅ | 매장 ID | 42 |
groupId | String | ✅ | 구성 상품군 ID | "42" |
item | CatalogItem | ✅ | 구성 상품 | |
order | Int | ✅ | 구성 배치 순서 | 1 |
default | Boolean | ✅ | 기본 선택 여부 | false |
additionalPriceValue | Long | ✅ | 선택 시 발생하는 추가 가격 | 500 |
Methods
ALPHA 콤보 단건 조회
| Property | Value |
|---|---|
| Method | GET |
| Path | /api-public/openapi/v1/merchants/{merchantId}/catalog/combos/{comboId} |
| Response Type | CatalogCombo |
| Description | 매장의 콤보 하나를 조회합니다. |
요청 파라미터
| Parameter | Location | Type | Required | Description |
|---|---|---|---|---|
merchantId | Path | Long | ✅ | 매장 ID |
comboId | Path | String | ✅ | 콤보 ID |
ALPHA 콤보 복수건 조회
| Property | Value |
|---|---|
| Method | GET |
| Path | /api-public/openapi/v1/merchants/{merchantId}/catalog/combos/by-ids |
| Response Type | CatalogCombo[] |
| Description | ID를 통해 매장의 콤보 여러 건을 조회합니다. 최대 25건까지 조회 가능합니다. |
요청 파라미터
| Parameter | Location | Type | Required | Description |
|---|---|---|---|---|
merchantId | Path | Long | ✅ | 매장 ID |
ids | Query | String[] | ✅ | 콤보 ID 목록 |
ALPHA 콤보 목록 조회
| Property | Value |
|---|---|
| Method | GET |
| Path | /api-public/openapi/v1/merchants/{merchantId}/catalog/combos |
| Response Type | CatalogCombo[] |
| Description | 매장의 콤보 목록을 조회합니다. |
요청 파라미터
| Parameter | Location | Type | Required | Default | Description |
|---|---|---|---|---|---|
merchantId | Path | Long | ✅ | - | 매장 ID |
page | Query | Int | 1 | 조회할 페이지 | |
size | Query | Int | 100 | 페이지 크기 |
Events
ALPHA 콤보 생성됨 (catalog.combo.created.v1)
| Property | Value |
|---|---|
| Event Type | catalog.combo.created.v1 |
| Description | 콤보가 생성되었습니다. |
이벤트 Payload
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
combo | CatalogCombo | ✅ | 생성된 콤보 정보 |
이벤트 Body 예시
json
{
"id": "000000000000000000000000",
"type": "catalog.combo.created.v1",
"createdAt": "2026-01-01T00:00:00.000Z",
"merchantId": 42,
"app": "my-awesome-app",
"data": {
"combo": {
"id": "42",
"merchantId": 42,
"title": "음료+디저트 세트",
"code": "COMBO_CODE",
"enabled": true,
"order": 1,
"description": "음료+디저트 세트 설명",
"imageUrl": "https://example.com/image.png",
"labels": ["할인"],
"basePriceValue": 9000,
"originalPriceValue": 10000,
"targetGroups": [
{
"id": "42",
"merchantId": 42,
"title": "음료",
"description": "음료를 선택해주세요.",
"order": 1,
"minQuantity": 1,
"maxQuantity": 1,
"targets": [
{
"id": "42",
"merchantId": 42,
"groupId": "42",
"item": {
"id": "42",
"merchantId": 42,
"category": {
"id": "42",
"merchantId": 42,
"title": "커피",
"code": "COFFEE",
"enabled": true,
"order": 1,
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-01T00:00:00Z"
},
"title": "아메리카노",
"code": "ITEM_CODE",
"state": "ON_SALE",
"enabled": true,
"order": 1,
"description": "아메리카노 설명",
"imageUrl": "https://example.com/image.png",
"labels": ["신규"],
"price": {
"title": "기본",
"priceType": "FIXED",
"priceUnit": 1,
"priceValue": 5000,
"barcode": "1234567890"
},
"diningOptions": ["HERE", "TOGO"],
"options": [],
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-01T00:00:00Z"
},
"order": 1,
"default": true,
"additionalPriceValue": 0
}
]
},
{
"id": "43",
"merchantId": 42,
"title": "디저트",
"description": "디저트를 선택해주세요.",
"order": 2,
"minQuantity": 1,
"maxQuantity": 1,
"targets": [
{
"id": "43",
"merchantId": 42,
"groupId": "43",
"item": {
"id": "44",
"merchantId": 42,
"category": {
"id": "43",
"merchantId": 42,
"title": "디저트",
"code": "DESSERT",
"enabled": true,
"order": 2,
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-01T00:00:00Z"
},
"title": "쿠키",
"code": "ITEM_CODE",
"state": "ON_SALE",
"enabled": true,
"order": 1,
"description": "쿠키 설명",
"imageUrl": "https://example.com/image.png",
"labels": ["신규"],
"price": {
"title": "기본",
"priceType": "FIXED",
"priceUnit": 1,
"priceValue": 5000,
"barcode": "1234567890"
},
"diningOptions": ["HERE", "TOGO"],
"options": [],
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-01T00:00:00Z"
},
"order": 1,
"default": false,
"additionalPriceValue": 0
}
]
}
],
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-01T00:00:00Z"
}
}
}ALPHA 콤보 수정됨 (catalog.combo.updated.v1)
| Property | Value |
|---|---|
| Event Type | catalog.combo.updated.v1 |
| Description | 콤보가 수정되었습니다. 유의: 콤보 구성에서 선택 가능한 상품 목록에 변동이 있는 경우에는 이 이벤트가 발생하지만, 상품 자체의 속성 변경으로는 이 이벤트가 발생하지 않습니다. (대신 상품 수정 이벤트 catalog.item.updated.v1가 발생합니다.) |
이벤트 Payload
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
combo | CatalogCombo | ✅ | 수정된 콤보 정보 |
이벤트 Body 예시
json
{
"id": "000000000000000000000000",
"type": "catalog.combo.updated.v1",
"createdAt": "2026-01-01T00:00:00.000Z",
"merchantId": 42,
"app": "my-awesome-app",
"data": {
"combo": {
"id": "42",
"merchantId": 42,
"title": "음료+디저트 세트",
"code": "COMBO_CODE",
"enabled": true,
"order": 1,
"description": "음료+디저트 세트 설명",
"imageUrl": "https://example.com/image.png",
"labels": ["할인"],
"basePriceValue": 9000,
"originalPriceValue": 10000,
"targetGroups": [
{
"id": "42",
"merchantId": 42,
"title": "음료",
"description": "음료를 선택해주세요.",
"order": 1,
"minQuantity": 1,
"maxQuantity": 1,
"targets": [
{
"id": "42",
"merchantId": 42,
"groupId": "42",
"item": {
"id": "42",
"merchantId": 42,
"category": {
"id": "42",
"merchantId": 42,
"title": "커피",
"code": "COFFEE",
"enabled": true,
"order": 1,
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-01T00:00:00Z"
},
"title": "아메리카노",
"code": "ITEM_CODE",
"state": "ON_SALE",
"enabled": true,
"order": 1,
"description": "아메리카노 설명",
"imageUrl": "https://example.com/image.png",
"labels": ["신규"],
"price": {
"title": "기본",
"priceType": "FIXED",
"priceUnit": 1,
"priceValue": 5000,
"barcode": "1234567890"
},
"diningOptions": ["HERE", "TOGO"],
"options": [],
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-01T00:00:00Z"
},
"order": 1,
"default": true,
"additionalPriceValue": 0
}
]
},
{
"id": "43",
"merchantId": 42,
"title": "디저트",
"description": "디저트를 선택해주세요.",
"order": 2,
"minQuantity": 1,
"maxQuantity": 1,
"targets": [
{
"id": "43",
"merchantId": 42,
"groupId": "43",
"item": {
"id": "44",
"merchantId": 42,
"category": {
"id": "43",
"merchantId": 42,
"title": "디저트",
"code": "DESSERT",
"enabled": true,
"order": 2,
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-01T00:00:00Z"
},
"title": "쿠키",
"code": "ITEM_CODE",
"state": "ON_SALE",
"enabled": true,
"order": 1,
"description": "쿠키 설명",
"imageUrl": "https://example.com/image.png",
"labels": ["신규"],
"price": {
"title": "기본",
"priceType": "FIXED",
"priceUnit": 1,
"priceValue": 5000,
"barcode": "1234567890"
},
"diningOptions": ["HERE", "TOGO"],
"options": [],
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-01T00:00:00Z"
},
"order": 1,
"default": false,
"additionalPriceValue": 0
}
]
}
],
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-01-01T00:00:00Z"
}
}
}ALPHA 콤보 삭제됨 (catalog.combo.deleted.v1)
| Property | Value |
|---|---|
| Event Type | catalog.combo.deleted.v1 |
| Description | 콤보가 삭제되었습니다. |
이벤트 Payload
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
comboId | String | ✅ | 삭제된 콤보 ID | "42" |
이벤트 Body 예시
json
{
"id": "000000000000000000000000",
"type": "catalog.combo.deleted.v1",
"createdAt": "2026-01-01T00:00:00.000Z",
"merchantId": 42,
"app": "my-awesome-app",
"data": {
"comboId": "42"
}
}