Merchant API

매장의 기본 정보를 조회하는 API예요. 매장명, 사업자등록번호 등 매장의 기본 정보를 확인할 수 있어요.

Types

매장 (Merchant)

매장은 주문, 결제, 상품, 고객 관리 등 토스플레이스가 제공하는 서비스가 이루어지는 환경이에요. 매장은 보통 오프라인에서 하나의 사업장을 나타내며, 토스플레이스 Open API를 활용하여 매장이 보유한 데이터에 접근할 수 있어요.

매장에서 앱을 설치하면, 앱에 등록된 key pair (access key와 secret key) 를 이용하여 매장의 데이터에 접근하는 Open API를 호출할 수 있어요. 앱을 설치하지 않은 매장에 대해서는 API를 호출할 수 없어요.

Name	Type	Required	Description	Example
id	Long	✅	매장 ID	42
name	String	✅	매장명	"플레이스 베이커리"
businessNumber	String	✅	사업자등록번호	"0000000000"
ownerName	String		사업주명	"김토스"
displayName	String	✅	매장 표시명 검색, 지도 등 고객 노출 지면에 표시되는 이름	"플레이스 베이커리"
phoneNumber	String		매장 전화번호	"01012345678"
address	String		주소	"서울특별시 서초구 강남대로 459 (서초동)"
latitude	Double		위도	37.5031925
longitude	Double		경도	127.0247527
operatingHours	OperatingHour[]		영업 시간
attributes	[String: Any]		기타 속성	{"key": "value"}

매장 영업 시간 (OperatingHour)

Name	Type	Required	Description	Example
dayOfWeek	String	✅	요일 ("MONDAY" ~ "SUNDAY")	"MONDAY"
openAt	LocalTime	✅	영업 시작 시간	"10:00:00"
closeAt	LocalTime	✅	영업 종료 시간	"22:00:00" (익일 시간의 경우 "01:00:00"과 같이 표시)

Methods

매장 정보 조회

Property	Value
Method	GET
Path	/api-public/openapi/v1/merchants/{merchantId}
Response Type	Merchant
Description	ID에 해당하는 매장 정보를 조회해요.

요청 파라미터

Parameter	Location	Type	Required	Default	Description
merchantId	Path	Long	✅	-	매장 ID

Events

매장 정보 변경됨 (merchant.merchant.updated.v1)

Property	Value
Event Type	merchant.merchant.updated.v1
Description	매장 정보가 변경되었어요.

이벤트 Payload

Name	Type	Required	Description	Example
merchant	Merchant	✅	매장 정보

이벤트 Body 예시

{
    "id": "000000000000000000000000",
    "type": "merchant.merchant.updated.v1",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "merchantId": 42,
    "app": "my-awesome-app",
    "data": {
        "merchant": {
            "id": 42,
            "name": "플레이스 베이커리",
            "businessNumber": "0000000000",
            "ownerName": "김토스",
            "displayName": "플레이스 베이커리",
            "address": "서울특별시 서초구 강남대로 459 (서초동)",
            "latitude": 37.5031925,
            "longitude": 127.0247527,
            "operatingHours": [
                {
                    "dayOfWeek": "MONDAY",
                    "openAt": "10:00:00",
                    "closeAt": "22:00:00"
                }
                {
                    "dayOfWeek": "TUESDAY",
                    "openAt": "10:00:00",
                    "closeAt": "22:00:00"
                }
                {
                    "dayOfWeek": "WEDNESDAY",
                    "openAt": "10:00:00",
                    "closeAt": "22:00:00"
                }
                {
                    "dayOfWeek": "THURSDAY",
                    "openAt": "10:00:00",
                    "closeAt": "22:00:00"
                }
                {
                    "dayOfWeek": "FRIDAY",
                    "openAt": "10:00:00",
                    "closeAt": "22:00:00"
                },
                {
                    "dayOfWeek": "SATURDAY",
                    "openAt": "10:00:00",
                    "closeAt": "22:00:00"
                },
                {
                    "dayOfWeek": "SUNDAY",
                    "openAt": "10:00:00",
                    "closeAt": "22:00:00"
                }
            ]
        }
    }
}