Upcart에서 커스텀 템플릿 설정하기

⚠️ 중요 공지

커스텀 템플릿에는 HTML, CSS, JavaScript, React에 대한 고급 기술 지식이 필요해요. 진행하기 전에 충분한 개발 전문성이 있거나 자격을 갖춘 Shopify 개발자의 도움을 받을 수 있는지 확인해 주세요. 저희 지원팀은 커스텀 템플릿 개발, 디버깅, 문제 해결을 지원하지 않아요. 기술적인 질문은 Shopify 전문가나 자격을 갖춘 개발자에게 문의해 주세요.

코드 에디터 기능

커스텀 템플릿 코드 에디터에는 유효한 템플릿을 더 쉽게 작성할 수 있도록 도와주는 내장 도구가 포함되어 있어요.

TypeScript IntelliSense

에디터는 TypeScript를 이해하므로, 입력하는 동안 사용 가능한 모든 props에 대한 자동 완성 제안, 타입 검사, 인라인 문서를 제공받을 수 있어요. prop 타입 힌트는 템플릿 작성을 돕기 위한 에디터 전용 IntelliSense예요 — 템플릿에 직접 작성하는 것이 아니며, 스토어프론트에서 실행되지도 않아요.

편집 가능한 템플릿 본문

에디터에는 템플릿의 편집 가능한 JSX 본문만 표시돼요 — 잠긴 줄은 없어요. 이를 감싸는 함수 래퍼는 빌드 시 자동으로 추가되며 에디터에는 표시되지 않아요. 편집으로 인해 템플릿 구조가 깨지면 언제든지 Reset to default를 사용해 원래 템플릿을 복원할 수 있어요.

General 섹션

Header 모듈을 사용하면 상품 수 표시와 닫기 버튼 제공 같은 필수 카트 기능을 유지하면서 카트 헤더를 원하는 디자인으로 커스터마이징할 수 있어요.

사용 가능한 Props - Full template

cartQuantity

타입: string
설명: 문자열로 형식화된 현재 카트의 상품 수
사용법: 커스텀 헤더 디자인에 카트 상품 수를 표시해요

<h2>Shopping Cart ({props.cartQuantity})</h2>

closeHandler

타입: () => void
설명: 트리거되면 카트를 닫는 콜백 함수
사용법: 버튼, 아이콘 또는 기타 인터랙티브 요소에 연결해 카트를 닫아요

<button  
  onClick={props.closeHandler}  
  aria-label="Close cart"  
>×</button>

titleComponent

타입: React.ReactElement | null
설명: 적절한 스타일링과 번역이 포함된, 미리 렌더링된 카트 헤더 제목 컴포넌트
사용법: 카트 설정 구성에 따라 카트 제목을 표시해요

<div>{props.titleComponent}</div>

Body 섹션

공지

Announcements 모듈을 사용하면 타이머 제어와 조건부 표시 같은 필수 공지 기능을 유지하면서 공지 표시를 원하는 디자인으로 커스터마이징할 수 있어요.

사용 가능한 Props - Full template

announcementTemplate

타입: string
설명: 공지 메시지의 HTML 콘텐츠
사용법: 커스텀 구현에서 공지 메시지를 표시해요

<div dangerouslySetInnerHTML={{ __html: props.announcementTemplate }} />

timer

타입: string
설명: 문자열로 형식화된 현재 타이머 값
사용법: 커스텀 공지 구현에서 카운트다운 타이머를 표시해요

<div>Time remaining: {props.timer}</div>

shouldUseTimer

타입: boolean
설명: 이 공지에서 타이머 기능이 활성화되어 있는지를 나타내요
사용법: 타이머 관련 콘텐츠와 컨트롤을 조건부로 렌더링해요

<div>  
  {props.shouldUseTimer && (  
    <span>{props.timer}</span>   
  )}  
</div>

isTimerExpiredAndShouldHide

타입: boolean
설명: 타이머가 만료되어 공지를 숨겨야 하는지를 나타내요
사용법: 타이머 상태에 따라 공지 전체의 표시 여부를 제어해요

<div>  
  {!props.isTimerExpiredAndShouldHide && (  
    <div>{props.timer}</div>  
  )}  
</div>

티어형 리워드

Rewards 모듈을 사용하면 마일스톤 추적, 진행 상황 시각화, 리워드 메시지 같은 필수 리워드 기능을 유지하면서 리워드 진행 표시를 원하는 디자인으로 커스터마이징할 수 있어요.

사용 가능한 Props - Full template

rewardsMessageHtml

타입: string
설명: 리워드 메시지의 HTML 콘텐츠
사용법: 커스텀 구현에서 서식이 적용된 리워드 메시지를 표시해요

<div dangerouslySetInnerHTML={{ __html: props.rewardsMessageHtml }} />

milestonesCompleted

타입: number
설명: 완료된 마일스톤 수
사용법: 완료 수를 표시하거나 완료 비율을 계산해요

<div>  
  {Math.round((props.milestonesCompleted / props.milestonesData.milestonesToRender.length) * 100)}% Complete  
</div>

milestonesData

타입:

{  
  milestonesToRender: {  
    id: string;  
    label: string;  
    icon: React.ReactElement;  
    isCompleted: boolean;  
    positionPercent: number;  
  }[];  
  progressPercent: number;  
  showMilestones: boolean;  
  settings: {  
    iconContainerSize: string;  
    iconAlignment: string;  
    labelAlignment: string;  
    hideLabel: boolean;  
  };  
}

설명: 리워드 시스템의 전체 마일스톤 구성 및 진행 데이터
사용법: 마일스톤 정보, 진행 비율, 표시 설정에 접근해요
속성:
- milestonesToRender: 완료 상태와 위치 정보가 포함된 마일스톤 객체 배열
- progressPercent: 현재 진행률(0-100 백분율)
- showMilestones: 마일스톤 마커 표시 여부
- settings: 마일스톤 표시를 위한 시각적 구성

할인

Discounts 모듈은 규칙 관리, 섹션 표시, 리워드 표시 같은 필수 기능을 유지하면서 직접 디자인할 수 있도록 커스텀 템플릿을 지원해요. 커스텀 템플릿의 내부 모듈 타입 식별자는 기존 커스텀 템플릿 코드와의 하위 호환성을 위해 TRIGGERED_REWARDS예요.

사용 가능한 Props - Full template

rules

타입:

{  
  id: string;  
  title: string;  
  description: string;  
  conditionsMet: boolean;  
}[]

설명: 현재 활성화된 Discount 규칙 배열
사용법: 사용 가능한 리워드와 제목, 설명, 각 규칙의 조건 충족 여부를 표시해요
속성:
- id: 리워드 규칙의 고유 식별자
- title: Discount 규칙의 제목
- description: 리워드 규칙의 설명
- conditionsMet: 규칙의 조건이 현재 카트에서 충족되었는지 여부. 이를 사용해 “X를 잠금 해제했어요” 대 “X를 잠금 해제하려면 $Y 더 지출하세요” UX 패턴을 만들 수 있어요

<div>
  {props.rules.map((rule) => (
    <div key={rule.id}>
      <h3>{rule.title}</h3>
      <p>{rule.conditionsMet ? "Reward unlocked!" : rule.description}</p>
    </div>
  ))}
</div>

showSection

타입: boolean
설명: Discounts 섹션을 표시할지 여부를 나타내요
사용법: Discounts 모듈 전체의 표시 여부를 제어해요

<div>  
  {props.showSection && (  
    <div>  
      <h2>Available Rewards...</h2>  
    </div>  
  )}  
</div>

onToggleSection

타입: () => void
설명: Discounts 섹션의 표시 상태를 전환하는 콜백 함수
사용법: 버튼이나 인터랙티브 요소에 연결해 사용자가 리워드 섹션을 표시/숨김할 수 있도록 해요

<button type="button" onClick={props.onToggleSection}>  
  {props.showSection ? "Hide Rewards" : "Show Available Rewards"}  
</button>

카트 상품

Cart Items 모듈을 사용하면 필수 이커머스 기능을 유지하면서 카트 상품 표시를 원하는 디자인으로 커스터마이징할 수 있어요. 이 모듈은 카트 상품 표시의 다양한 측면을 위한 각각의 전용 props를 가진 여러 템플릿 유형을 제공해요.

카트 담기 또는 카트 업데이트 중 로딩 표시기 표시하기: 표준 Cart Items 모듈에는 내장된 “카트에 추가 중” 스피너가 없어요. 상품이 추가되는 동안이나 카트 작업이 진행 중일 때 로딩 상태를 표시하고 싶다면, Product tile 템플릿을 사용해 isLoading과 loadingOperation props(아래에 문서화됨)를 읽어 스피너나 오버레이를 조건부로 렌더링하세요. 커스텀 템플릿에는 개발 경험이 필요해요 — 이 페이지 상단의 공지를 참고하세요.

사용 가능한 Props - Product tile template

참고: Product Tile 템플릿을 활성화하면 Variant template, Properties template, Bundle template, Price template을 포함한 이 모듈의 다른 모든 템플릿이 재정의돼요.
해당 템플릿 중 하나에서 커스텀 코드를 사용하려면 반드시 Product Tile 템플릿을 꺼야 해요.

이미지, 옵션, 할인가, 수량 선택기, 구독 버튼이 있는 카트 상품 타일

title

타입: string
설명: 상품 제목/이름
사용법: 카트 상품에 주요 상품명을 표시해요

variant

타입: React.ReactNode
설명: 미리 렌더링된 옵션(variant) 정보 컴포넌트
사용법: 옵션 세부 정보를 React 컴포넌트로 표시해요

properties

타입: React.ReactNode
설명: 미리 렌더링된 상품 속성 컴포넌트
사용법: 상품 속성과 구독 정보를 React 컴포넌트로 표시해요

bundle

타입: React.ReactNode
설명: 미리 렌더링된 번들 세부 정보 컴포넌트
사용법: 번들 정보를 React 컴포넌트로 표시해요

compareAtPrice

타입: string | undefined
설명: 형식화된 비교 가격(원래 가격)
사용법: 할인 상품의 원래 가격을 표시해요

price

타입: string
설명: 형식화된 현재 가격
사용법: 현재 상품 가격을 표시해요

savings

타입: string | undefined
설명: 형식화된 절약 금액
사용법: 고객이 얼마나 절약하는지 표시해요

imageUrl

타입: string | undefined
설명: 상품 이미지 URL
사용법: 상품 이미지를 표시해요

productUrl

타입: string | undefined
설명: 상품 페이지 URL
사용법: 상품 상세 페이지로 링크해요

quantity

타입: number
설명: 카트에 담긴 현재 상품 수량
사용법: 상품 수량을 표시하고 관리해요

showQuantitySelector

타입: boolean
설명: 수량 컨트롤 표시 여부
사용법: 수량 선택기를 조건부로 표시해요

discountCodes

타입: string[] | undefined
설명: 이 상품에 적용된 할인 코드 배열
사용법: 상품별 할인을 표시해요

subscription

타입:

{  
  subscriptionUpgradeData: {  
    buttonText: string;  
    defaultSellingPlanId: number;  
  } | null;  
  sellingPlansData: {  
    sellingPlanGroups: {  
      name: string;  
      selling_plans: {  
        id: number;  
        name: string;  
      }[];  
    }[] | null;  
    activeSellingPlanId: string;  
    oneTimePurchaseText: string | null;  
  } | null;  
  upgradeSellingPlan: (item: CartItem, sellingPlanId: number) => void;  
  changeSellingPlan: (item: CartItem, value: string) => void;  
  getSellingPlanGroupText: (groupName: string, planName: string) => string;  
}

설명: 업그레이드 데이터, 판매 플랜, 핸들러 함수가 포함된 완전한 구독 관리 객체
사용법: 구독 기능을 관리해요
subscription 객체에는 다음이 포함돼요:
- subscriptionUpgradeData: 업그레이드 정보(업그레이드가 없으면 null)
  - buttonText: 업그레이드 버튼 텍스트
  - defaultSellingPlanId: 업그레이드용 기본 판매 플랜 ID
- sellingPlansData: 사용 가능한 판매 플랜 옵션(플랜이 없으면 null)
  - sellingPlanGroups: 판매 플랜이 포함된 플랜 그룹 배열
  - activeSellingPlanId: 현재 선택된 판매 플랜 ID
  - oneTimePurchaseText: 일회성 구매 옵션 텍스트(사용 불가 시 null)
- upgradeSellingPlan: 특정 판매 플랜으로 업그레이드하는 함수
- changeSellingPlan: 현재 판매 플랜을 변경하는 함수
- getSellingPlanGroupText: 판매 플랜 표시 텍스트를 형식화하는 유틸리티 함수

onIncrease

타입: () => void
설명: 상품 수량을 늘리는 함수
사용법: 수량 증가 액션을 처리해요

onDecrease

타입: () => void
설명: 상품 수량을 줄이는 함수
사용법: 수량 감소 액션을 처리해요

onDeleteProduct

타입: () => void
설명: 카트에서 상품을 제거하는 함수
사용법: 상품 제거를 처리해요

onQuantityChange

타입: (quantity: string) => void
설명: 직접 수량 입력을 처리하는 함수
사용법: 수동 수량 변경을 처리해요

handleInputChange

타입: (e: React.ChangeEvent<HTMLInputElement>) => void
설명: 수량 필드의 입력 변경 핸들러
사용법: 수량 입력 필드 변경을 처리해요

replaceItemWithVariant

타입: (variantId: string) => Promise<{ success: boolean }>
설명: 상품을 다른 옵션(variant)으로 교체하는 함수
사용법: 옵션 전환을 처리해요

isLoading

타입: boolean
설명: 카트 작업의 로딩 상태
사용법: 로딩 표시기를 표시해요

loadingOperation

타입: 'increase' | 'decrease' | 'inputChange' | 'remove' | 'subscription' | undefined
설명: 현재 로딩 중인 특정 작업
사용법: 작업별 로딩 상태를 표시해요

setLoadingOperation

타입: (op: "increase" | "decrease" | "inputChange" | "remove" | "subscription" | undefined) => void
설명: 로딩 작업 상태를 설정하는 함수
사용법: 다양한 작업의 로딩 상태를 관리해요

rawItem

타입: CartItem(아래의 CartItem 타입 참고)
설명: 모든 정보를 담고 있는 원시 카트 상품 데이터

사용 가능한 Props - Variant template

item

타입: CartItem(아래의 CartItem 타입 참고)
설명: 옵션(variant) 정보가 포함된 원시 카트 상품 데이터
사용법: 카트 상품에서 옵션 세부 정보에 접근해요

사용 가능한 Props - Properties template

productProperties

타입: { key: string; value: string; isUrl?: boolean; }[]
설명: 상품 속성 배열(커스텀 필드, 라인 아이템 속성)

subscriptionLabel

타입: string | undefined
설명: 구독 정보 레이블

사용 가능한 Props - Bundle template

getSizedImageUrl

타입: getSizedImageUrl: ({ src, width, height }: SizedImageParams) => string
설명: 적절한 크기의 이미지 URL을 가져오는 유틸리티 함수

item

타입:

{  
  itemComponents: {  
    quantity: number;  
    image: {  
      url: string;  
      height: number | null;  
      width: number | null;  
      alt: string;  
    };  
    product: {  
      title: string;  
      has_only_default_variant: boolean;  
    };  
    variantTitle: string;  
  }[];  
  variantTitle: string | undefined;  
  hasComponents: boolean;  
}

설명: 구성 요소를 포함한 번들 상품 정보. itemComponents는 구성 요소 객체 배열이에요 — 각 번들 구성 요소를 렌더링하려면 배열을 순회(map)하세요.

showDetailsText

타입: string | undefined
설명: “세부 정보 표시” 액션 텍스트
사용법: 펼치기 버튼 텍스트를 표시해요

hideDetailsText

타입: string | undefined
설명: “세부 정보 숨기기” 액션 텍스트

isExpanded

타입: boolean
설명: 번들 세부 정보가 펼쳐져 있는지 여부

toggleCollapsible

타입: () => void
설명: 번들 세부 정보 표시를 전환하는 함수
사용법: 펼치기/접기 액션을 처리해요

chevronDownIconComponent

타입: React.ReactElement
설명: 펼치기/접기용으로 미리 렌더링된 셰브론 아이콘
사용법: 일관된 펼치기/접기 표시기를 표시해요

사용 가능한 Props - Price template

compareAtPrice

타입: string | undefined
설명: 형식화된 비교 가격(원래 가격)
사용법: 할인 상품의 원래 가격을 표시해요

price

타입: string
설명: 형식화된 현재 가격
사용법: 현재 상품 가격을 표시해요

savings

타입: string | undefined
설명: 형식화된 절약 금액
사용법: 고객이 얼마나 절약하는지 표시해요

CartItem 객체 속성

CartItem 객체에는 카트 라인 아이템에 대한 모든 세부 정보가 담겨 있어요. 이 객체는 Product Tile 템플릿에서는 props.rawItem으로, Variant 템플릿에서는 props.item으로 사용할 수 있어요.

핵심 식별 정보

key (string) - 이 카트 상품의 고유 식별자.
id (number) - 옵션(variant) ID(레거시 필드, 대신 variant_id 사용)
variant_id (number) - 이 상품의 Shopify 옵션 ID
product_id (number) - Shopify 상품 ID
lineIdxFrom1 (number) - 수정 전 원래 카트에서 이 상품의 1부터 시작하는 인덱스

상품 정보

title (string) - 라인 아이템 제목(일반적으로 옵션 제목)
product_title (string) - 주요 상품 제목
handle (string) - 상품 URL 핸들(예: “camp-stool”)
vendor (string) - 상품 공급업체/브랜드명
product_type (string) - 세금 목적의 상품 카테고리/유형
sku (string) - 재고 관리 단위(SKU) 식별자
product_description (string) - 전체 상품 설명
product_has_only_default_variant (boolean) - 상품에 옵션이 하나뿐인지 여부

가격(모든 가격은 센트 단위)

quantity (number) - 카트에 담긴 이 상품의 수량
price (number) - 할인 전 단가
original_price (number) - price와 동일
discounted_price (number) - 상품 수준 할인 후 단가
compare_at_price (number | null) - 비교 가격(MSRP). 참고: 이 필드는 Shopify 카트 API에서 제공하는 것이 아니라 Upcart가 추가한 필드예요
final_line_price (number) - 상품 수준 할인 후 총 가격(수량 × discounted_price)
original_line_price (number) - 할인 전 총 가격(수량 × price)
line_price (number) - 모든 할인 적용 후 총 가격
final_price (number) - 지원 중단됨 - 상품 할인 후 단가(수량 미반영)
total_discount (number) - line_level_total_discount와 동일
line_level_total_discount (number) - 이 라인 아이템에 적용된 총 할인 금액

미디어 및 URL

image (string) - 기본 상품 이미지 URL
url (string) - 상품 페이지의 상대 URL 경로(예: “/products/camp-stool?variant=42789611372803”)
featured_image (object | null) - 대표 이미지 세부 정보:
- alt (string) - 이미지 대체 텍스트
- aspect_ratio (number) - 이미지 가로세로 비율
- height (number) - 이미지 높이(픽셀)
- url (string) - 이미지 URL
- width (number) - 이미지 너비(픽셀)

옵션(Variant) 정보

variant_title (string | null) - 옵션 제목(예: “Large / Red”)
variant_options (string[]) - 옵션 값 배열
options_with_values (Array) - 상세 옵션 정보:
- name (string) - 옵션 이름(예: “Size”)
- value (string) - 옵션 값(예: “Large”)
untranslated_product_title (string | undefined) - 번역 전 원래 상품 제목(카트 변경 응답에서만 제공)
untranslated_variant_title (string | undefined) - 번역 전 원래 옵션 제목(카트 변경 응답에서만 제공)

커스텀 속성 및 메타데이터

properties (Record<string, any> | null) - 커스텀 라인 아이템 속성이며, 라인에 속성이 없으면 null이에요 — 키를 읽기 전에 확인하세요. 키가 __로 시작하는 속성은 항상 고객에게 숨겨지고, 단일 _로 시작하는 키는 Hide properties starting with single underscore ”_” 카트 설정이 켜져 있을 때 함께 숨겨져요.
gift_card (boolean) - 이 상품이 기프트 카드인지 여부
taxable (boolean) - 이 상품이 과세 대상인지 여부
requires_shipping (boolean) - 이 상품이 배송을 필요로 하는지 여부
grams (number) - 상품 무게(그램)

할인 및 프로모션

discounts (Array) - 간소화된 할인 정보:
- amount (number) - 할인 금액(센트)
- title (string) - 할인 제목/이름
line_level_discount_allocations (Array) - 상세 할인 할당 정보:
- amount (number) - 할인 금액(센트)
- discount_application (object) - 전체 할인 적용 세부 정보:
  - allocation_method (string) - 할인 할당 방식
  - created_at (string) - 할인 생성 시점
  - description (string | null) - 할인 설명
  - key (string) - 할인 키 식별자
  - target_selection (string) - 할인 대상 선택
  - target_type (string) - 대상 유형
  - title (string) - 할인 제목
  - total_allocated_amount (number) - 총 할당 금액
  - type ('discount_code' | '') - 할인 유형(자동 할인은 빈 문자열)
  - value (string) - 할인 값
  - value_type (string) - 값 적용 방식

번들 상품

has_components (boolean | undefined) - 이 상품이 다른 상품을 포함하는 번들인지 여부(GET 카트 응답에서만 제공)
item_components (Array | null | undefined) - 번들 구성 요소 세부 정보:
- quantity (number) - 이 구성 요소의 수량
- image (object) - 구성 요소 이미지:
  - url (string) - 이미지 URL
  - height (number | null) - 이미지 높이
  - width (number | null) - 이미지 너비
  - alt (string) - 대체 텍스트
product (object) - 구성 요소 상품 정보:
- title (string) - 상품 제목
- has_only_default_variant (boolean) - 상품에 기본 옵션만 있는지 여부
variantTitle (string) - 구성 요소 옵션 제목

비즈니스 규칙

quantity_rule (object | undefined) - 수량 제약(GET 카트 응답에서만 제공):
- min (number) - 최소 허용 수량
- max (number | null) - 최대 허용 수량(null = 제한 없음)
- increment (number) - 수량 증가 단위

구독 정보

selling_plan_allocation (object | undefined) - 구독/판매 플랜 세부 정보:
- price (number) - 구독 가격(센트)
- compare_at_price (number | null) - 구독 비교 가격
- per_delivery_price (number) - 배송당 가격
- selling_plan (object) - 판매 플랜 세부 정보:
  - id (number) - 판매 플랜 ID
  - name (string) - 플랜 이름
  - description (string) - 플랜 설명
  - options (Array) - 플랜 옵션:
    - name (string) - 옵션 이름
    - position (number) - 옵션 위치
    - value (string) - 옵션 값
  - recurring_deliveries (boolean) - 플랜에 반복 배송이 있는지 여부

통합 메타데이터

__appIntegrated (object | undefined) - 서드파티 앱 통합 데이터:
- app ('stay.ai') - 통합된 앱 식별자
- bundleRole ('parent' | 'child') - 번들 구조에서의 역할

업셀

Upsells 모듈을 사용하면 옵션(variant) 선택, 카트 담기 액션, 상품 정보 표시 같은 필수 이커머스 기능을 유지하면서 업셀 상품 표시를 원하는 디자인으로 커스터마이징할 수 있어요.

사용 가능한 Props - Upsell tile template

itemUrl

타입: string
설명: 상품 페이지의 URL
사용법: 사용자 탐색 향상을 위해 상품 상세 페이지 링크를 만들어요

<a href={props.itemUrl} className="product-link">  
  <img src={props.imageUrl} alt={props.altText} />  
</a>

imageUrl

타입: string | undefined
설명: 상품 이미지의 URL
사용법: 커스텀 업셀 구현에서 상품 이미지를 표시해요
폴백: 플레이스홀더 이미지로 undefined 값을 안전하게 처리하세요

description

타입: string
설명: 상품 설명
사용법: 커스텀 업셀 구현에서 상품 설명을 표시해요

altText

타입: string
설명: 접근성을 위한 상품 이미지 대체 텍스트
사용법: 스크린 리더 지원을 제공하고 접근성 준수를 개선해요

<img   
  src={props.imageUrl}   
  alt={props.altText}  
  className="product-image"  
/>

productId

타입: string
설명: 상품의 고유 식별자
사용법: 상품 추적, 분석 구현 또는 카트 담기 기능에 사용해요

productTitle

타입: string
설명: 상품의 제목/이름
사용법: 커스텀 업셀 구현에서 상품명을 표시해요

<div>  
  <h3>{props.productTitle}</h3>  
</div>

oldPrice & newPrice

타입: string | null (oldPrice), string (newPrice)
설명: 형식화된 비교 가격과 현재 가격
사용법: 세일 표시와 함께 가격 정보를 표시해요

isSingleVariant

타입: boolean
설명: 상품에 옵션(variant)이 하나뿐인지 나타내요
사용법: 옵션 선택 UI 요소를 조건부로 렌더링해요

productOptions

타입: { name: string; position: 1 | 2 | 3; values: string[]; }[]
설명: 사용 가능한 모든 선택지를 포함한 전체 상품 옵션 구성
사용법: 고급 옵션 선택 UI를 위한 상세 상품 옵션 정보에 접근해요

variantOptions

타입: { label: string; value: string }[]
설명: 상품에서 사용 가능한 옵션(variant) 목록
사용법: 옵션 선택 드롭다운이나 버튼을 만들어요
구조: 각 옵션에는 표시 레이블과 고유 값 식별자가 포함돼요

selectedVariantId & selectedVariantLabel

타입: string (selectedVariantId), string | undefined (selectedVariantLabel)
설명: 현재 선택된 옵션 ID와 표시 레이블
사용법: 선택된 옵션 정보를 추적하고 표시해요

onVariantChange

타입: (variantId: string) => void
설명: 옵션 선택 변경을 처리하는 함수
사용법: 사용자가 선택할 때 선택된 옵션을 업데이트해요

onAddClick

타입: (productId: string, variantId?: string) => void
설명: 상품을 카트에 추가하는 것을 처리하는 함수
사용법: 올바른 상품 및 옵션 식별과 함께 카트 담기 기능을 구현해요

<button   
  onClick={() => props.onAddClick(props.productId, props.selectedVariantId)}  
  disabled={props.addLoading}  
>  
  {props.addLoading ? 'Adding...' : props.addButtonText}  
</button>

rating & reviewCount

타입: number | undefined (rating), string | undefined (reviewCount)
설명: 상품 평점과 형식화된 리뷰 수 텍스트
사용법: 사회적 증거와 상품 품질 지표를 표시해요

addLoading & addButtonText

타입: boolean (addLoading), string (addButtonText)
설명: 카트 담기 액션의 로딩 상태와 버튼 텍스트
사용법: 카트 작업 중 사용자 피드백을 제공하고 버튼 텍스트를 커스터마이징해요

cartItemsCount

타입: number
설명: 현재 카트에 담긴 상품 수
사용법: 카트 상태를 표시하거나 카트 기반 로직을 구현해요

추가 노트

Notes 모듈을 사용하면 펼침 섹션, 텍스트 입력 처리, 로딩 상태 같은 필수 노트 기능을 유지하면서 카트 노트 기능을 원하는 디자인으로 커스터마이징할 수 있어요.

사용 가능한 Props - Full template

cartNote

타입: string
설명: 고객이 입력한 현재 카트 노트 내용
사용법: 커스텀 구현에서 카트 노트 텍스트를 표시하고 관리해요

<textarea  
  value={props.cartNote}  
  ...  
/>

notesPlaceholder

타입: string
설명: 노트 입력 필드의 플레이스홀더 텍스트
사용법: 노트에 어떤 내용을 포함할지 고객에게 안내해요

<textarea  
  placeholder={props.notesPlaceholder}  
  ...  
/>

notesTitle

타입: string
설명: 노트 섹션의 제목/헤더 텍스트
사용법: 커스텀 노트 구현에서 섹션 제목을 표시해요

<h3 className="notes-title" dangerouslySetInnerHTML={{ __html: props.notesTitle }} />

chevronDownIconComponent

타입: React.ReactElement
설명: 펼치기/접기 기능을 위한 미리 렌더링된 셰브론 아이콘 컴포넌트
사용법: 커스텀 구현에서 일관된 펼치기/접기 표시기를 표시해요

loadingIndicatorComponent

타입: React.ReactElement | null
설명: 비동기 작업을 위한 미리 렌더링된 로딩 표시기 컴포넌트
사용법: 노트 저장 작업 중 로딩 상태를 표시해요

handleCartNoteChange

타입: (newCartNote: string) => void
설명: 카트 노트 내용 변경을 처리하는 함수
사용법: 사용자가 텍스트를 수정할 때 카트 노트를 업데이트해요

isExpanded

타입: boolean
설명: 노트 섹션이 현재 펼쳐져 있는지 나타내요
사용법: 노트 입력 영역의 표시 여부를 제어해요

toggleCollapsible

타입: () => void
설명: 노트 섹션의 펼침/접힘 상태를 전환하는 함수
사용법: 버튼이나 인터랙티브 요소에 연결해 섹션 표시를 제어해요

애드온

Addons 모듈을 사용하면 상품 정보 표시, 가격, 토글 컨트롤, 통화 형식 같은 필수 이커머스 기능을 유지하면서 애드온 상품 표시를 원하는 디자인으로 커스터마이징할 수 있어요.

사용 가능한 Props - Full template

addonProduct

타입:

{  
  product: {  
    id: number;  
    title: string;  
    description: string;  
  };  
  variant: {  
    id: number;  
    price: number;  
    compare_at_price: number | null;  
  };  
  image: {  
    src: string;  
    alt: string;  
  };  
}

설명: 상품 세부 정보, 옵션 가격, 이미지 데이터를 포함한 완전한 애드온 상품 정보
사용법: 애드온 상품 표시에 필요한 모든 상품 정보에 접근해요
구조: 포괄적인 상품 데이터가 담긴 중첩된 product, variant, image 객체를 포함해요
- Product 객체 속성 addonProduct.product
  - id: 상품의 고유 숫자 식별자
  - title: 애드온 상품의 표시 이름
  - description: 상품의 HTML 설명 콘텐츠
- Variant 객체 속성
  - id: 옵션의 고유 숫자 식별자
  - price: 현재 가격(센트)
  - compare_at_price: 원래 가격(센트, 비교 가격이 없으면 null)
- Image 객체 속성
  - src: 상품 이미지의 URL
  - alt: 이미지 대체 텍스트(접근성용)

toggle

타입:

{  
  state: 'enabled' | 'disabled' | 'loading';  
  handleEnable: () => void;  
  handleDisable: () => void;  
} | null

설명: 애드온 활성화/비활성화를 위한 토글 컨트롤 상태와 핸들러
사용법: 애드온 선택을 위한 인터랙티브 토글 기능을 구현해요
상태: enabled, disabled, loading 세 가지 상태가 가능해요
핸들러: 활성화와 비활성화 액션을 위한 별도의 함수

moneyFormat

타입: string
설명: 가격 형식화에 사용되는 통화 형식 문자열
사용법: 일관된 통화 표시를 위해 formatMoney 함수에 전달하세요

formatMoney

타입:

(options: {  
  cents: string | number;  
  format?: string;  
  shouldRemoveHTML?: boolean;  
}) => string

설명: 통화 값을 형식화하는 유틸리티 함수
사용법: 스토어 통화 설정에 맞게 가격을 일관되게 형식화해요
매개변수: 센트 값, 선택적 형식 문자열, HTML 제거 옵션을 받아요

할인 코드

Discount Code 모듈을 사용하면 코드 검증, 폼 제출, 사용자 피드백 같은 필수 이커머스 기능을 유지하면서 할인 코드 입력 기능을 원하는 디자인으로 커스터마이징할 수 있어요.

사용 가능한 Props - Full template

indicator

타입: 'validating' | 'invalid' | 'none'
설명: 할인 코드 입력의 현재 검증 상태
사용법: 검증 상태에 따라 적절한 UI 피드백을 표시해요
상태:
- validating: 코드가 처리/검증 중이에요
- invalid: 코드 검증에 실패했어요
- none: 검증 상태 없음(기본/대기)

discountCodeInput

타입: string
설명: 할인 코드 입력 필드의 현재 값
사용법: 사용자가 입력한 할인 코드 텍스트를 표시하고 관리해요

<input  
  type="text"  
  value={props.discountCodeInput}  
  onChange={(e) => props.setDiscountCodeInput(e.target.value)}  
  ...  
/>

discountCodePlaceholder

타입: string
설명: 할인 코드 입력 필드의 플레이스홀더 텍스트
사용법: 입력란에 무엇을 입력할지 사용자에게 안내해요

discountCodeButtonText

타입: string
설명: 적용/제출 버튼에 표시할 텍스트
사용법: 할인 코드 제출 버튼 텍스트를 커스터마이징해요

setDiscountCodeInput

타입: (value: string | ((prev: string) => string)) => void
설명: 할인 코드 입력 값을 업데이트하는 함수
사용법: 할인 코드 필드의 사용자 입력 변경을 처리해요

handleSubmit

타입: (e: React.FormEvent<HTMLFormElement>) => void
설명: 할인 코드 적용을 위한 폼 제출을 처리하는 함수
사용법: 할인 코드 검증 및 적용을 처리해요
이벤트: 폼 제출 이벤트를 처리해요

<form onSubmit={props.handleSubmit} >  
  <div className="input-group">  
    <input  
      type="text"  
      value={props.discountCodeInput}  
      onChange={(e) => props.setDiscountCodeInput(e.target.value)}  
      placeholder={props.discountCodePlaceholder}  
    />   
    <button   
      type="submit"  
      disabled={props.indicator === 'validating' || !props.discountCodeInput.trim()}  
    >  
      {props.discountCodeButtonText}  
    </button>  
  </div>  
</form>

카트 요약

Cart Summary 모듈을 사용하면 할인 관리, 절약 금액 계산, 가격 투명성 같은 필수 이커머스 기능을 유지하면서 카트 요약 및 할인 표시를 원하는 디자인으로 커스터마이징할 수 있어요.

사용 가능한 Props - Full template

totalSavingsText

타입: string
설명: 총 절약 금액 섹션의 텍스트 레이블
사용법: 커스텀 카트 요약 구현에서 절약 레이블을 표시해요

discountApplications

타입:

{  
  key: string;  
  title: string;  
  type: 'discount_code' | '';  
}[]

설명: 적용된 할인 코드와 자동 할인의 배열
사용법: 활성화된 모든 할인을 제목과 유형과 함께 표시해요
구조: 각 할인에는 고유 키, 표시 제목, 유형 식별자가 포함돼요

cartTotalDiscount

타입: number
설명: 총 할인 금액(센트)
사용법: 계산이나 커스텀 형식화를 위해 원시 할인 값에 접근해요

showCartTotalDiscount

타입: boolean
설명: 총 할인을 표시해야 하는지를 나타내요. showTotalSavings를 위해 지원 중단으로 표시되었지만, 아래 참고를 확인하세요 — 커스텀 템플릿 내부에서는 여전히 이 prop을 사용해야 해요.
사용법: 설정에 따라 할인 정보를 조건부로 렌더링해요

formattedCartTotalDiscount

타입: string
설명: 미리 형식화된 총 할인 금액의 HTML 문자열. formattedTotalSavings를 위해 지원 중단으로 표시되었지만, 아래 참고를 확인하세요.
사용법: 통화 기호와 함께 올바르게 형식화된 할인 금액을 표시해요

showTotalSavings와 formattedTotalSavings는 커스텀 템플릿 내부에서 사용할 수 없어요. 이 값들은 모듈의 내부 컨텍스트에 존재하지만, Cart summary 템플릿에는 showCartTotalDiscount와 formattedCartTotalDiscount만 전달돼요 — 새로운 두 값을 읽으면 undefined가 반환돼요. 위의 두 prop을 사용하시고, 이 값들은 할인 총액만 표시하며 Show compare-at price savings in footer total 설정을 따르지 않는다는 점에 유의하세요.

isRemovingDiscount

타입: boolean
설명: 할인 제거 작업이 진행 중인지 나타내요
사용법: 할인 제거 중 로딩 상태를 표시해요

handleRemoveDiscount

타입: () => Promise<void>
설명: 할인 코드 제거를 처리하는 함수
사용법: 카트에서 적용된 할인 코드를 제거해요

totalCompareAtPrice

타입: number
설명: 비교 가격의 합계(카트의 모든 상품)
사용법: 절약 금액이나 원래 가격 정보를 계산하고 표시해요

totalAfterAllDiscounts

타입: number
설명: 모든 할인 적용 후 최종 카트 총액(센트)
사용법: 고객이 지불할 최종 가격을 표시해요

originalTotalPrice

타입: number
설명: 할인 전 원래 카트 총액(센트)
사용법: 투명성과 절약 금액 계산을 위해 원래 가격을 표시해요

cartItemCount

타입: number
설명: 카트에 담긴 총 상품 수
사용법: 카트 요약에 상품 수 정보를 표시해요

신뢰 배지

Trust Badges 모듈을 사용하면 조건부 배지 표시와 올바른 이미지 처리 같은 필수 신뢰 구축 기능을 유지하면서 신뢰 배지 표시를 원하는 디자인으로 커스터마이징할 수 있어요.

사용 가능한 Props - Full template

showBadge

타입: boolean
설명: 신뢰 배지를 표시해야 하는지를 나타내요
사용법: 모듈 설정에 따라 신뢰 배지의 표시 여부를 제어해요

badgeUrl

타입: string
설명: 표시할 신뢰 배지 이미지의 URL
사용법: 커스텀 구현에서 신뢰 배지 이미지의 소스 URL로 사용해요

​⚠️ 중요 공지

​코드 에디터 기능

​TypeScript IntelliSense

​편집 가능한 템플릿 본문

​General 섹션

​헤더

​사용 가능한 Props - Full template

​Body 섹션

​공지

​사용 가능한 Props - Full template

​티어형 리워드

​사용 가능한 Props - Full template

​할인

​사용 가능한 Props - Full template

​추천

​사용 가능한 Props - Recommendation tile template

​카트 상품

​사용 가능한 Props - Product tile template

​사용 가능한 Props - Variant template

​사용 가능한 Props - Properties template

​사용 가능한 Props - Bundle template

​사용 가능한 Props - Price template

​CartItem 객체 속성

​핵심 식별 정보

​상품 정보

​가격(모든 가격은 센트 단위)

​미디어 및 URL

​옵션(Variant) 정보

​커스텀 속성 및 메타데이터

​할인 및 프로모션

​번들 상품

​비즈니스 규칙

​구독 정보

​통합 메타데이터

​업셀

​사용 가능한 Props - Upsell tile template

​추가 노트

​사용 가능한 Props - Full template

​Footer 섹션

​애드온

​사용 가능한 Props - Full template

​할인 코드

​사용 가능한 Props - Full template

​카트 요약

​사용 가능한 Props - Full template

​신뢰 배지

​사용 가능한 Props - Full template

⚠️ 중요 공지

코드 에디터 기능

TypeScript IntelliSense

편집 가능한 템플릿 본문

General 섹션

헤더

사용 가능한 Props - Full template

Body 섹션

공지

사용 가능한 Props - Full template

티어형 리워드

사용 가능한 Props - Full template

할인

사용 가능한 Props - Full template

추천

사용 가능한 Props - Recommendation tile template

카트 상품

사용 가능한 Props - Product tile template

사용 가능한 Props - Variant template

사용 가능한 Props - Properties template

사용 가능한 Props - Bundle template

사용 가능한 Props - Price template

CartItem 객체 속성

핵심 식별 정보

상품 정보

가격(모든 가격은 센트 단위)

미디어 및 URL

옵션(Variant) 정보

커스텀 속성 및 메타데이터

할인 및 프로모션

번들 상품

비즈니스 규칙

구독 정보

통합 메타데이터

업셀

사용 가능한 Props - Upsell tile template

추가 노트

사용 가능한 Props - Full template

Footer 섹션

애드온

사용 가능한 Props - Full template

할인 코드

사용 가능한 Props - Full template

카트 요약

사용 가능한 Props - Full template

신뢰 배지

사용 가능한 Props - Full template