`ALPHA` 카탈로그 - 콤보(세트상품)

콤보 기능이 보이지 않아요

ALPHA 콤보(세트) 기능은 현재 일부 매장에만 지원 중인 기능입니다.

Types

`ALPHA` 콤보(세트상품) (CatalogCombo)

콤보(세트상품)는 여러 상품을 한 번에 할인된 가격으로 묶어 판매할 수 있는 상품종입니다. 예를 들어 '음료+디저트 세트' 콤보에 '음료'와 '디저트' 상품군을 두고, 고객은 상품군에서 각각 하나씩 상품을 골라 주문합니다.

Name	Type	Required	Description	Example
`id`	`String`	✅	콤보 ID	`"42"`
`merchantId`	`Long`	✅	매장 ID	`42`
`title`	`String`	✅	콤보명	`"음료+디저트 세트"`
`code`	`String`		콤보 코드	`""`
`enabled`	`Boolean`	✅	콤보 활성화 및 노출 여부	`true`
`order`	`Int`	✅	정렬 순서	`1`
`description`	`String`	✅	콤보 설명	`""`
`imageUrl`	`String`		콤보 이미지 URL	`""`
`labels`	`String[]`		콤보 라벨 목록	`["신규"]`
`basePriceValue`	`Long`	✅	콤보 판매 가격	`9000`
`originalPriceValue`	`Long`		콤보 원래 가격 콤보를 구성하는 상품의 원래 가격 합계	`10000`
`targetGroups`	`CatalogComboTargetGroup[]`	✅	콤보 구성 상품군 목록
`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"
    }
}

ALPHA 카탈로그 - 콤보(세트상품) ​

Types ​

ALPHA 콤보(세트상품) (CatalogCombo) ​

ALPHA 콤보 구성 상품군 (CatalogComboTargetGroup) ​

ALPHA 콤보 구성 (CatalogComboTarget) ​

Methods ​

ALPHA 콤보 단건 조회 ​

ALPHA 콤보 복수건 조회 ​

ALPHA 콤보 목록 조회 ​

Events ​

ALPHA 콤보 생성됨 (catalog.combo.created.v1) ​

ALPHA 콤보 수정됨 (catalog.combo.updated.v1) ​

ALPHA 콤보 삭제됨 (catalog.combo.deleted.v1) ​

`ALPHA` 카탈로그 - 콤보(세트상품)

Types

`ALPHA` 콤보(세트상품) (CatalogCombo)

`ALPHA` 콤보 구성 상품군 (CatalogComboTargetGroup)

`ALPHA` 콤보 구성 (CatalogComboTarget)

Methods

`ALPHA` 콤보 단건 조회

`ALPHA` 콤보 복수건 조회

`ALPHA` 콤보 목록 조회

Events

`ALPHA` 콤보 생성됨 (`catalog.combo.created.v1`)

`ALPHA` 콤보 수정됨 (`catalog.combo.updated.v1`)

`ALPHA` 콤보 삭제됨 (`catalog.combo.deleted.v1`)