콘솔의 카탈로그 메뉴는 Pro Plan 이상을 이용하는 프로덕트에만 제공됩니다.
데이터 소스 선택하기
카탈로그를 만들 때 데이터 관리 방식에 맞는 소스를 선택합니다.- Google 스프레드시트: 운영자가 시트에서 데이터를 관리하고, 노티플라이가 전체 범위를 정해진 일정에 맞춰 동기화합니다. 모든 필드는 문자열로 저장됩니다.
- API: 서버에서 Catalog REST API로 스키마와 아이템을 직접 관리합니다.
string,number,boolean,time,geo,object,array타입을 사용할 수 있습니다.
Google 스프레드시트 연결하기
1. 시트 준비하기
첫 번째로 값이 있는 행을 헤더로 사용합니다.- 첫 번째 열 이름은 반드시
id여야 합니다. - 헤더는 비어 있거나 중복될 수 없으며 최대 250자입니다.
id와 헤더 이름은 영문 대소문자, 숫자, 하이픈(-), 밑줄(_)만 사용할 수 있습니다.- 아이템의
id는 최대 250자이며 카탈로그 안에서 고유해야 합니다. 상품 정보가 바뀌어도 유지되는 내부 식별자를 사용하는 것이 좋습니다. - 데이터가 있는 행에서
id가 비어 있거나 중복되면 동기화에 실패합니다. - 완전히 빈 행은 건너뜁니다. 헤더보다 값이 많은 행은 동기화 오류로 처리합니다.
- Google 스프레드시트에 표시되는 값이 문자열로 저장됩니다. 가격과 날짜의 표시 형식을 먼저 확인하고, 숫자 비교나 배열 필드가 필요하면 API 카탈로그를 사용하세요.
2. 카탈로그 만들기
- 콘솔에서 데이터 > 카탈로그를 엽니다.
- 카탈로그 만들기를 누르고 데이터 소스로 Google Sheets를 선택합니다.
- 카탈로그 이름을 입력합니다. 프로젝트 안에서 고유한 이름을 사용하고, 메시지의 Liquid에서 그대로 참조할 수 있도록
products처럼 짧고 의미가 분명한 이름을 권장합니다. 이름은 250자 이하의 영문·숫자·한글·하이픈·밑줄을 사용할 수 있습니다. - 스프레드시트 ID를 입력합니다. 특정 탭이나 범위만 가져오려면 시트 탭 이름 또는 A1 범위를 입력합니다. 둘 다 입력할 때는 같은 탭을 가리켜야 합니다. 둘 다 비우면 첫 번째 탭 전체를 읽습니다.
- Google Sheets의 공유 메뉴에서
catalog-reader@notifly.tech에 뷰어 권한을 부여합니다. 편집 권한은 필요하지 않습니다. - 동기화 일정과 기준 시간대를 선택한 뒤 카탈로그를 만듭니다. 생성하면 첫 동기화가 바로 시작됩니다.

/d/와 /edit 사이 값입니다.
https://docs.google.com/spreadsheets/d/1AbCdEfGhIjKlMnOpQrStUvWxYz/edit의 스프레드시트 ID는 1AbCdEfGhIjKlMnOpQrStUvWxYz입니다. A1 범위는 A1:Z50000 또는 Products!A1:Z50000처럼 입력합니다.
3. 동기화 일정 정하기
반복하지 않거나, 15분·30분 간격, 매시간, 매일, 매주, 매월 중 하나를 선택할 수 있습니다. 일정은 선택한 시간대의 시각을 기준으로 실행됩니다. 시각의 분은00·15·30·45 중에서 선택하며, 매월 일정은 1일부터 28일까지 지원합니다.
- 생성 직후 첫 동기화 및 지금 동기화는 정기 일정에 영향을 미치지 않습니다.
- 데이터 소스를 수정하면 상태가
동기화 대기로 바뀝니다. 다음 정기 동기화 또는 지금 동기화 후 새 설정이 적용됩니다. - 변경된 내용이 없으면 동기화 기록은
변경 없음으로 남습니다. - 동기화가 실패하면 마지막으로 성공한 버전을 계속 사용합니다. 권한, 헤더, 행 형식을 수정한 뒤 다시 동기화하세요.
- 비활성화한 카탈로그는 자동·수동 동기화와 메시지 조회에서 제외됩니다.
4. 결과 확인하고 정리하기
동기화가 끝나면 카탈로그 상세에서 다음 순서로 확인합니다.- 상태와 활성 행 수를 확인합니다.
- 내용 미리보기에서 ID와 주요 필드가 원본 시트와 같은지 페이지별로 확인합니다.
- 동기화 기록에서 실행 방식, 시작·완료 시각, 행 수, 크기, 성공·변경 없음·실패 상태를 확인합니다.
- 실패했다면 공유 권한, 첫 번째
id열, 빈·중복 헤더, 잘못된 행을 확인하고 고친 뒤 지금 동기화를 다시 실행합니다.

5. 연결 정보와 이름 수정하기
카탈로그 상세 화면에서 수정을 누르면 이름, 스프레드시트 ID, 시트 탭, A1 범위, 동기화 일정을 바꿀 수 있습니다.- 데이터 원본이나 범위를 바꿨다면 저장한 뒤 동기화 결과를 다시 확인하세요.
- 카탈로그 이름을 바꾸면 기존 캠페인과 유저 여정의
catalog_items·catalog_selection_items태그도 새 이름으로 수정해야 합니다. - 데이터소스의 행이나 값을 바꿔도 캠페인과 유저 여정이 자동으로 시작되지는 않습니다. 카탈로그를 이용한 유저 여정 혹은 캠페인을 세팅해야 합니다.
6. 비활성화하거나 삭제하기
Google 스프레드시트 카탈로그의 비활성화와 영구 삭제는 다릅니다.- 비활성화: Liquid 조회와 자동·수동 동기화를 중지하지만 카탈로그 데이터와 동기화 기록은 유지합니다. 비활성화 후 콘솔에서는 영구 삭제만 진행할 수 있으므로 먼저 참조 중인 메시지가 없는지 확인하세요.
- 영구 삭제: 아이템과 동기화 기록을 데이터베이스에서 삭제하며 복구할 수 없습니다.
API 카탈로그 만들기
API 카탈로그는 콘솔에서 데이터 소스로 API를 선택해id:string 필드만 있는 빈 카탈로그를 만든 뒤 REST API로 필드와 아이템을 등록하거나, REST API로 스키마까지 한 번에 만들 수 있습니다.
API로 만들 때는 API 인증 토큰을 발급받고 다음 요청을 보냅니다.
{ "name": "id", "type": "string" }이어야 합니다. 카탈로그를 만든 뒤 아이템은 한 번에 최대 50개씩 등록할 수 있습니다.
메시지에서 아이템 사용하기
메시지 에디터에서catalog_items 태그에 카탈로그 이름과 아이템 ID를 차례로 전달합니다. 조회 결과는 items 배열에 저장됩니다.
지원 범위예약·이벤트 기반 캠페인과 유저 여정에서는 앱/웹 푸시, 문자, 카카오 알림톡, 카카오 브랜드메시지, 웹훅에서 사용할 수 있습니다.채널과 관계없이 API 기반 발송 캠페인은 지원하지 않습니다. 이 경로에서는 카탈로그를 조회하지 않아
items가 빈 배열로 처리됩니다. API 직접 발송도 카탈로그를 조회하지 않으므로, 호출하기 전에 필요한 값을 직접 조회해 메시지에 넣어야 합니다.이벤트 기반 캠페인
이벤트 파라미터에 상품 ID가 들어 있다면event에서 읽을 수 있습니다.
event를 사용합니다.
유저 여정
이벤트로 시작한 유저 여정에서는 진입 이벤트의 파라미터를entry_event에서 읽습니다.
여러 항목 조회하기
여러 ID를 공백으로 구분하면 한 번에 조회할 수 있습니다. 유저 속성이나 이벤트 파라미터도 ID 자리에 넣을 수 있습니다.items.size를 확인하거나 for로 순회한 뒤 값을 사용하세요. 조회 결과가 비어 있으면 대체 문구를 보여주거나, 채널에서 지원하는 경우 abort_message로 발송을 중단할 수 있습니다.
같은 메시지에서 카탈로그 태그를 다시 호출하면 items 배열이 새 결과로 바뀝니다.
카탈로그 필드 안에 Liquid 문법이 들어 있고 그 값까지 다시 렌더링해야 한다면 :rerender 옵션을 사용합니다.
:rerender를 사용하세요.
셀렉션 사용하기
API 카탈로그에서는 필터·정렬·개수 조건으로 셀렉션을 만들 수 있습니다. 셀렉션은 최대 30개, 셀렉션마다 필터는 최대 4개, 결과는 최대 50개입니다. 필드 타입별로 사용할 수 있는 연산자가 정해져 있습니다.string은 equals·does not equal, number는 두 연산자와 greater than·less than, boolean은 is, time은 before·after, array는 includes value·does not include value를 지원합니다. geo와 object는 필터링할 수 없고 필터 값에 null을 사용할 수 없습니다.
문제 해결
Google Sheets 권한 오류가 표시됩니다.
Google Sheets 권한 오류가 표시됩니다.
공유 설정에서
catalog-reader@notifly.tech에 뷰어 권한이 있는지 확인하세요. 스프레드시트 ID와 시트 탭 이름도 함께 확인합니다.데이터 검증 오류가 표시됩니다.
데이터 검증 오류가 표시됩니다.
첫 번째 열 이름이 소문자
id인지, 헤더가 비어 있거나 중복되지 않았는지 확인하세요. 각 행의 id와 헤더에는 영문·숫자·하이픈·밑줄만 사용할 수 있으며, 데이터 행의 열 수가 헤더보다 많아도 동기화에 실패합니다.시트를 수정했는데 메시지 값이 바뀌지 않습니다.
시트를 수정했는데 메시지 값이 바뀌지 않습니다.
시트를 수정해도 메시지 값이 즉시 바뀌지는 않습니다. 다음 정기 동기화를 기다리거나 지금 동기화를 실행한 뒤, 상세 화면의 최근 동기화 시각과 내용 미리보기를 확인하세요.
재입고나 가격 인하 메시지가 자동으로 발송되나요?
재입고나 가격 인하 메시지가 자동으로 발송되나요?
카탈로그 값이 바뀌어도 발송은 시작되지 않습니다. 재입고나 가격 인하 이벤트를 노티플라이로 보내고, 해당 이벤트를 캠페인 또는 유저 여정의 시작 조건으로 설정하세요. 카탈로그에서는 메시지에 표시할 상품명, 가격, 링크 등을 조회합니다.
주요 제한
- 프로젝트당 활성 카탈로그: 최대 20개
- Google 스프레드시트 카탈로그 필드:
id제외 최대 1,000개 - API 카탈로그 필드:
id포함 최대 500개 - 필드 추가 요청: 한 번에 최대 50개
- 아이템 생성·수정·삭제 요청: 한 번에 최대 50개
- 아이템 한 개의 저장 크기: 최대 1 MiB
- 카탈로그 한 개의 저장 크기: 최대 2 GiB
- 프로젝트의 활성 카탈로그 합계: 최대 15 GiB
- 카탈로그·필드·아이템 ID: 최대 250자
- 문자열: 최대 5,000자
- 배열: 문자열 최대 100개
object·array중첩: 최대 50단계, object key에는.또는$사용 불가- Google 스프레드시트 동기화 소스: 1회 최대 100 MiB
- API JSON 요청 본문: 최대 4 MiB
