Catalog API

토스 POS의 [상품] - [상품 · 할인] 내 [상품], [옵션], [카테고리] 메뉴를 통해 매장의 카탈로그를 관리할 수 있습니다. Catalog API를 통해 해당 정보를 조회할 수 있으며, 매장의 메뉴 구성과 상품 정보를 제공합니다.

Types

상품 (CatalogItem)

매장에 등록된 상품입니다. 소비자가 주문할 때 하나 또는 여러 상품을 주문에 포함하게 됩니다.

Name	Type	Required	Description	Example
`id`	`String`	✅	상품 ID	`"42"`
`merchantId`	`Long`	✅	매장 ID	`42`
`category`	`CatalogCategory`	✅	카테고리 상품은 반드시 하나의 카테고리에 속합니다.
`title`	`String`	✅	상품명	`"아메리카노"`
`code`	`String`		상품코드	`""`
`description`	`String`	✅	상품 설명	`""`
`imageUrl`	`String`		상품 이미지 URL	`""`
`labels`	`String[]`		상품 라벨 목록	`["신규"]`
`price`	`CatalogItemPrice`	✅	가격
`createdAt`	`timestamp`	✅	생성 시각	`"2025-09-01T00:00:00Z"`
`updatedAt`	`timestamp`	✅	수정 시각	`"2025-09-01T00:00:00Z"`

상품 가격 (CatalogItemPrice)

Name	Type	Required	Description	Example
`title`	`String`	✅	가격명	`"기본"`
`priceType`	`CatalogItemPriceType`	✅	가격 종류	`"FIXED"`
`priceUnit`	`Long`	✅	가격 단위	`1`
`priceValue`	`Long`	✅	가격	`3000`
`barcode`	`String`		바코드	`""`

상품 가격 종류 (CatalogItemPriceType)

Value	Description
`"FIXED"`	정가
`"VARIABLE"`	시가
`"UNIT"`	단위가격
`"UNDEFINED"`

카테고리 (CatalogCategory)

여러 상품을 그룹화하는 카테고리입니다. 토스 POS, 또는 고객에게 상품이 전시되는 키오스크 등의 채널에서 카테고리를 통해 상품을 탐색할 수 있습니다.

매장의 상품은 반드시 하나의 카테고리에 속합니다.

Name	Type	Required	Description	Example
`id`	`String`	✅	카테고리 ID	`"42"`
`merchantId`	`Long`	✅	매장 ID	`42`
`title`	`String`	✅	카테고리명	`"커피"`
`code`	`String`		카테고리 코드	`""`
`createdAt`	`timestamp`	✅	생성 시각	`"2025-09-01T00:00:00Z"`
`updatedAt`	`timestamp`	✅	수정 시각	`"2025-09-01T00:00:00Z"`

Methods

상품 단건 조회

Property	Value
Method	GET
Path	`/api-public/openapi/v1/merchants/{merchantId}/catalog/items/{itemId}`
Response Type	`CatalogItem`
Description	매장의 상품 하나를 조회합니다.

요청 파라미터

Parameter	Location	Type	Required	Description
`merchantId`	Path	`Long`	✅	매장 ID
`itemId`	Path	`String`	✅	상품 ID

상품 복수건 조회

Property	Value
Method	GET
Path	`/api-public/openapi/v1/merchants/{merchantId}/catalog/items/by-ids`
Response Type	`CatalogItem[]`
Description	ID를 통해 매장의 상품 여러 건을 조회합니다. 최대 25건까지 조회 가능합니다.

요청 파라미터

Parameter	Location	Type	Required	Description
`merchantId`	Path	`Long`	✅	매장 ID
`ids`	Query	`String[]`	✅	상품 ID 목록

상품 목록 조회

Property	Value
Method	GET
Path	`/api-public/openapi/v1/merchants/{merchantId}/catalog/items`
Response Type	`CatalogItem[]`
Description	매장의 상품 목록을 상품 ID 순으로 조회합니다.

요청 파라미터

Parameter	Location	Type	Required	Default	Description
`merchantId`	Path	`Long`	✅	-	매장 ID
`page`	Query	`Int`		`1`	조회할 페이지
`size`	Query	`Int`		`100`	페이지 크기

상품 검색

Property	Value
Method	GET
Path	`/api-public/openapi/v1/merchants/{merchantId}/catalog/items/search`
Response Type	`CatalogItem[]`
Description	조건에 맞는 상품을 검색합니다.

요청 파라미터

Parameter	Location	Type	Required	Description
`merchantId`	Path	`Long`	✅	매장 ID
`categoryIds`	Query	`String[]`		카테고리 ID 목록 이 파라미터를 지정하면 검색 결과는 해당 카테고리에 속한 상품만 반환됩니다.
`page`	Query	`Int`		`1`
`size`	Query	`Int`		`100`

카테고리 단건 조회

Property	Value
Method	GET
Path	`/api-public/openapi/v1/merchants/{merchantId}/catalog/categories/{categoryId}`
Response Type	`CatalogCategory`
Description	매장의 카테고리 하나를 조회합니다.

요청 파라미터

Parameter	Location	Type	Required	Description
`merchantId`	Path	`Long`	✅	매장 ID
`categoryId`	Path	`String`	✅	카테고리 ID

카테고리 복수건 조회

Property	Value
Method	GET
Path	`/api-public/openapi/v1/merchants/{merchantId}/catalog/categories/by-ids`
Response Type	`CatalogCategory[]`
Description	ID를 통해 매장의 카테고리 여러 건을 조회합니다. 최대 25건까지 조회 가능합니다.

요청 파라미터

Parameter	Location	Type	Required	Description
`merchantId`	Path	`Long`	✅	매장 ID
`ids`	Query	`String[]`	✅	카테고리 ID 목록

카테고리 목록 조회

Property	Value
Method	GET
Path	`/api-public/openapi/v1/merchants/{merchantId}/catalog/categories`
Response Type	`CatalogCategory[]`
Description	매장의 카테고리 목록을 조회합니다.

요청 파라미터

Parameter	Location	Type	Required	Default	Description
`merchantId`	Path	`Long`	✅	-	매장 ID
`page`	Query	`Int`		`1`	조회할 페이지
`size`	Query	`Int`		`100`	페이지 크기

Events

상품 생성됨 (`catalog.item.created.v1`)

Property	Value
Event Type	`catalog.item.created.v1`
Description	상품이 생성되었습니다.

이벤트 Payload

Name	Type	Required	Description	Example
`item`	`CatalogItem`	✅	생성된 상품 정보

이벤트 Body 예시

json

{
    "id": "000000000000000000000000",
    "type": "catalog.item.created.v1",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "merchantId": 42,
    "app": "my-awesome-app",
    "data": {
        "item": {
            "id": "42",
            "merchantId": 42,
            "category": {
                "id": "42",
                "merchantId": 42,
                "title": "커피",
                "code": "CATEGORY_CODE",
                "createdAt": "2026-01-01T00:00:00Z",
                "updatedAt": "2026-01-01T00:00:00Z"
            },
            "title": "아메리카노",
            "code": "ITEM_CODE",
            "description": "아메리카노 설명",
            "imageUrl": "https://example.com/image.png",
            "labels": ["신규"],
            "price": {
                "title": "기본",
                "priceType": "FIXED",
                "priceUnit": 1,
                "priceValue": 3000,
                "barcode": "1234567890"
            },
            "createdAt": "2026-01-01T00:00:00Z",
            "updatedAt": "2026-01-01T00:00:00Z"
        }
    }
}

상품 수정됨 (`catalog.item.updated.v1`)

Property	Value
Event Type	`catalog.item.updated.v1`
Description	상품이 수정되었습니다.

이벤트 Payload

Name	Type	Required	Description	Example
`item`	`CatalogItem`	✅	수정된 상품 정보

이벤트 Body 예시

json

{
    "id": "000000000000000000000000",
    "type": "catalog.item.updated.v1",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "merchantId": 42,
    "app": "my-awesome-app",
    "data": {
        "item": {
            "id": "42",
            "merchantId": 42,
            "category": {
                "id": "42",
                "merchantId": 42,
                "title": "커피",
                "code": "CATEGORY_CODE",
                "createdAt": "2026-01-01T00:00:00Z",
                "updatedAt": "2026-01-01T00:00:00Z"
            },
            "title": "아메리카노",
            "code": "ITEM_CODE",
            "description": "아메리카노 설명",
            "imageUrl": "https://example.com/image.png",
            "labels": ["신규"],
            "price": {
                "title": "기본",
                "priceType": "FIXED",
                "priceUnit": 1,
                "priceValue": 3000,
                "barcode": "1234567890"
            },
            "createdAt": "2026-01-01T00:00:00Z",
            "updatedAt": "2026-01-01T00:00:00Z"
        }
    }
}

상품 삭제됨 (`catalog.item.deleted.v1`)

Property	Value
Event Type	`catalog.item.deleted.v1`
Description	상품이 삭제되었습니다.

이벤트 Payload

Name	Type	Required	Description	Example
`itemId`	`String`	✅	삭제된 상품 ID	`"42"`

이벤트 Body 예시

json

{
    "id": "000000000000000000000000",
    "type": "catalog.item.deleted.v1",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "merchantId": 42,
    "app": "my-awesome-app",
    "data": {
        "itemId": "42"
    }
}

카테고리 생성됨 (`catalog.category.created.v1`)

Property	Value
Event Type	`catalog.category.created.v1`
Description	카테고리가 생성되었습니다.

이벤트 Payload

Name	Type	Required	Description	Example
`category`	`CatalogCategory`	✅	생성된 카테고리 정보

이벤트 Body 예시

json

{
    "id": "000000000000000000000000",
    "type": "catalog.category.created.v1",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "merchantId": 42,
    "app": "my-awesome-app",
    "data": {
        "category": {
            "id": "42",
            "merchantId": 42,
            "title": "커피",
            "code": "CATEGORY_CODE",
            "createdAt": "2026-01-01T00:00:00Z",
            "updatedAt": "2026-01-01T00:00:00Z"
        }
    }
}

카테고리 수정됨 (`catalog.category.updated.v1`)

Property	Value
Event Type	`catalog.category.updated.v1`
Description	카테고리가 수정되었습니다.

이벤트 Payload

Name	Type	Required	Description	Example
`category`	`CatalogCategory`	✅	수정된 카테고리 정보

이벤트 Body 예시

json

{
    "id": "000000000000000000000000",
    "type": "catalog.category.updated.v1",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "merchantId": 42,
    "app": "my-awesome-app",
    "data": {
        "category": {
            "id": "42",
            "merchantId": 42,
            "title": "커피",
            "code": "CATEGORY_CODE",
            "createdAt": "2026-01-01T00:00:00Z",
            "updatedAt": "2026-01-01T00:00:00Z"
        }
    }
}

카테고리 삭제됨 (`catalog.category.deleted.v1`)

Property	Value
Event Type	`catalog.category.deleted.v1`
Description	카테고리가 삭제되었습니다.

이벤트 Payload

Name	Type	Required	Description	Example
`categoryId`	`String`	✅	삭제된 카테고리 ID	`"42"`

이벤트 Body 예시

json

{
    "id": "000000000000000000000000",
    "type": "catalog.category.deleted.v1",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "merchantId": 42,
    "app": "my-awesome-app",
    "data": {
        "categoryId": "42"
    }
}

상품 추가 · 수정

지원 예정 안내

상품 및 재고를 추가, 수정하는 API는 2026년 하반기 중 지원 예정입니다.

Catalog API ​

Types ​

상품 (CatalogItem) ​

상품 가격 (CatalogItemPrice) ​

상품 가격 종류 (CatalogItemPriceType) ​

카테고리 (CatalogCategory) ​

Methods ​

상품 단건 조회 ​

상품 복수건 조회 ​

상품 목록 조회 ​

상품 검색 ​

카테고리 단건 조회 ​

카테고리 복수건 조회 ​

카테고리 목록 조회 ​

Events ​

상품 생성됨 (catalog.item.created.v1) ​

상품 수정됨 (catalog.item.updated.v1) ​

상품 삭제됨 (catalog.item.deleted.v1) ​

카테고리 생성됨 (catalog.category.created.v1) ​

카테고리 수정됨 (catalog.category.updated.v1) ​

카테고리 삭제됨 (catalog.category.deleted.v1) ​

상품 추가 · 수정 ​

Catalog API

Types

상품 (CatalogItem)

상품 가격 (CatalogItemPrice)

상품 가격 종류 (CatalogItemPriceType)

카테고리 (CatalogCategory)

Methods

상품 단건 조회

상품 복수건 조회

상품 목록 조회

상품 검색

카테고리 단건 조회

카테고리 복수건 조회

카테고리 목록 조회

Events

상품 생성됨 (`catalog.item.created.v1`)

상품 수정됨 (`catalog.item.updated.v1`)

상품 삭제됨 (`catalog.item.deleted.v1`)

카테고리 생성됨 (`catalog.category.created.v1`)

카테고리 수정됨 (`catalog.category.updated.v1`)

카테고리 삭제됨 (`catalog.category.deleted.v1`)

상품 추가 · 수정