카탈로그 사용하기

미리 설정 해 둔 카탈로그를 발송 시점에 메시지 본문으로 불러오는 기능입니다. 상품 정보, 매장 목록, 콘텐츠 메타데이터처럼 여러 사용자가 공유하는 데이터를 사용자 속성과 별개로 관리할 수 있습니다.

시작 전 준비물

메시지에서 사용하려면 먼저 카탈로그와 데이터가 준비되어 있어야 합니다.

카탈로그 설정법은 다음 페이지를 참고하세요 {카탈로그 Link}

기본 문법

{% catalog_items <카탈로그명> <아이템ID> [아이템ID] [아이템ID] %}

조회 결과는 items 변수에 담기며, 이후 본문에서 items[번호].필드명 으로 사용합니다.

{% catalog_items Games 1234 %}{{ items[0].title }} 지금 {{ items[0].price }}원
→ 슈퍼마리오 지금 49000원

파라미터 상세

파라미터	설명	필수
<카탈로그명>	조회할 카탈로그 이름	✅
<아이템ID>	조회할 아이템의 ID. 공백으로 구분해 최대 3개	최소 1개 필수

---

지원 기능

아이템 여러 개 조회 — 한 태그에서 최대 3개까지

{% catalog_items Games 1234 1235 1236 %}{{ items[0].title }}, {{ items[1].title }}, {{ items[2].title }}

아이템 ID에 개인화 변수 사용

{% catalog_items Games {{ user_properties["last_viewed_item"] }} %}{{ items[0].title }}

필터 적용

{{ items[0].price | default: "가격 문의" }}

필드 타입에 맞는 값 사용 — 카탈로그 필드 타입에 따라 값이 그대로 전달됩니다

필드 타입	메시지에서의 값
STRING	문자열
NUMBER	숫자 (계산·필터 적용 가능)
BOOLEAN	true / false (조건문에 사용 가능)
TIME	ISO-8601 문자열 (예: 2026-08-20T00:00:00Z)

아이템 ID 자체 참조 — {{ items[0].id }}

---

응답 처리 규칙

상황	처리 방식
정상 조회	items 에 아이템이 담김
요청한 아이템이 카탈로그에 없음	그 자리만 빈 값, 나머지 아이템은 그대로
조회 실패 (일시적 오류 등)	전체가 빈 값
아이템 ID 자리의 변수가 빈 값	그 자리만 빈 값
카탈로그명이 빈 값	태그 전체를 건너뜀 (items 가 비어 있음)
아이템 ID를 4개 이상 지정	태그 전체를 건너뜀

응답 여부에 따라 메시지 발송이 실패하지 않습니다. 값을 가져오지 못하면 그 자리가 비워진 채로 발송됩니다.

결과에 따라 메시지 발송을 취소하고싶다면? -> {Abort Link}

아이템이 없어도 순서가 밀리지 않습니다

요청한 아이템 ID의 순서와 위치가 그대로 유지됩니다. 가운데 아이템이 삭제되어도 뒤 아이템의 번호가 당겨지지 않습니다.

{% catalog_items Games 1234 없는ID 1236 %}[{{ items[0].title }}] [{{ items[1].title }}] [{{ items[2].title }}]
→ [슈퍼마리오] [] [젤다의전설]

items[2] 는 언제나 세 번째로 지정한 아이템입니다. 아이템 하나가 삭제되었을 때 다른 상품 정보가 그 자리에 표시되는 일이 없습니다.

---

에러 처리 및 방어 패턴

값이 비어 있을 수 있으므로 아래 두 가지 방법을 권장합니다.

1. 기본값 지정 — default 필터

{% catalog_items Games 1234 %}{{ items[0].title | default: "인기 상품" }} 을 확인해 보세요

2. 조건 분기 — if 문

{% catalog_items Games 1234 %}{% if items[0] %}  {{ items[0].title }} 이 {{ items[0].price }}원!{% else %}  이번 주 신작을 확인해 보세요{% endif %}

여러 아이템을 쓸 때는 각 자리를 따로 확인할 수 있습니다.

{% catalog_items Games 1234 1235 %}{% if items[1] %}{{ items[1].title }}도 함께 만나보세요{% endif %}

전체 개수가 필요하면 size 필터를 사용합니다. 비어 있는 자리도 개수에 포함됩니다.

{{ items | size }}

---

실 사용 예시

1. 단일 상품 소개

{% catalog_items Products SKU-1001 %}{{ items[0].name }} 이 {{ items[0].discount_price }}원으로 준비되어 있어요

2. 사용자가 마지막으로 본 상품

{% catalog_items Products {{ user_properties["last_viewed_sku"] }} %}{% if items[0] %}  아직 고민 중이신가요? {{ items[0].name }} 이 기다리고 있어요{% else %}  이번 주 추천 상품을 확인해 보세요{% endif %}

3. 이벤트 속성으로 주문 상품 안내

{% catalog_items Products {{ event_properties["sku"] }} %}{{ items[0].name }} 주문이 완료되었습니다

4. 세 가지 상품 한 번에

{% catalog_items Products SKU-1001 SKU-1002 SKU-1003 %}이번 주 베스트 31위 {{ items[0].name }}2위 {{ items[1].name }}3위 {{ items[2].name }}

5. BOOLEAN 필드로 조건 분기

{% catalog_items Products SKU-1001 %}{% if items[0].on_sale %}  🔥 {{ items[0].name }} 특가 진행 중{% else %}  {{ items[0].name }} 을 만나보세요{% endif %}

6. 이미지 URL 사용

이미지 URL 필드도 문자열로 저장해 사용할 수 있습니다. 이미지 영역에 입력할 때는 태그와 URL 출력 사이에 공백이나 줄바꿈을 넣지 마세요.

{% catalog_items Products SKU-1001 %}{{ items[0].image_url }}