일반적인 Upcart API 활용법

API 패턴 작동 방식

대부분의 Upcart API 스크립트는 동일한 간단한 패턴을 따라요: 카트 이벤트 수신 → 조건 확인 → 액션 실행 예를 들어: “카트가 로드되면 → 비어 있는지 확인하고 → 고정 버튼을 숨겨요.” 💡 API가 처음이신가요? 아래 예시로 들어가기 전에 API란 무엇인가요?부터 시작해 보세요.

스크립트를 추가할 위치

아래의 모든 스크립트는 다음 위치에 추가하세요: Cart Editor → Settings → Custom HTML → Scripts (before load) 각 스니펫을 <script>...</script> 태그로 감싸고 저장하세요. 테스트하려면 브라우저의 개발자 도구 콘솔(F12)을 열고 console.log 메시지를 확인하세요.

레거시 콜백과 최신 콜백에 대한 참고 사항

Upcart에는 카트 이벤트를 수신하는 두 가지 방법이 있어요:

스타일	예시	상태
최신 (권장)	`upcartSubscribeAddedToCart(fn)`	현재
레거시 (지원 중단)	`upcartOnAddToCart = fn`	여전히 작동하지만 콘솔 경고를 기록

아래의 모든 예시는 최신 API를 사용해요. 기존 스타일을 사용하는 기존 스크립트도 계속 작동해요.

예시 1: 카트가 비어 있을 때 고정 카트 버튼 숨기기

<script>
  window.upcartSubscribeCartLoaded(function(event) {
    var stickyBtn = document.querySelector("#upCartStickyButton");
    if (stickyBtn) {
      var totalQty = event.cart.items.reduce(function(sum, item) {
        return sum + item.quantity;
      }, 0);
      stickyBtn.style.display = totalQty === 0 ? "none" : "block";
    }
  });
</script>

작동 방식: upcartSubscribeCartLoaded는 카트가 로드될 때마다 실행돼요. 콜백은 items 배열이 포함된 cart 객체가 있는 event를 받아요. 각 아이템의 quantity를 합산해 카트가 비어 있는지 판단해요. ⚠️ 중요: event.cart에는 item_count 속성이 없어요. event.cart.items를 순회하며 합계를 계산해야 해요.

예시 2: 아이템이 카트에 추가될 때 로그 남기기

<script>
  window.upcartSubscribeAddedToCart(function(event) {
    console.log("Added to cart:", event.item.title, "| Qty:", event.item.quantityAdded);
  });
</script>

event.item에서 사용할 수 있는 속성:

속성	설명
`event.item.title`	상품 제목
`event.item.quantityAdded`	이 액션에서 추가된 수량
`event.item.quantity`	현재 카트에 담긴 이 아이템의 총 수량
`event.item.variantId`	Shopify 옵션(variant) ID
`event.item.handle`	상품 핸들
`event.item.productId`	Shopify 상품 ID
`event.item.finalPrice`	할인 적용 후 최종 가격
`event.item.image`	상품 이미지 URL

예시 3: 서드파티 분석 앱(예: TripleWhale)과 통합하기

<script>
  window.upcartSubscribeAddedToCart(function(event) {
    window.TriplePixel('AddToCart', {
      item: event.item.variantId,
      q: event.item.quantityAdded
    });
  });
</script>

참고: 서드파티 앱마다 달라요. 올바른 이벤트 형식은 해당 앱의 지원팀에 확인하세요.

예시 4: 상품이 추가된 후 카트 자동으로 열기

<script>
  window.upcartSubscribeAddedToCart(function(event) {
    window.upcartOpenCart();
  });
</script>

참고: Cart Editor → Settings → Cart settings에서 “Open cart drawer on add to cart”가 이미 활성화되어 있다면 이 스크립트는 필요 없어요.

함수	실행 시점	콜백이 받는 값
`upcartSubscribeCartLoaded(fn)`	카트 데이터 로드	`{ cart }` - cart에는 `.items[]`, `.total`, `.currency`가 있음
`upcartSubscribeAddedToCart(fn)`	아이템이 카트에 추가됨	`{ item }` - item에는 `.title`, `.variantId`, `.quantityAdded`, `.quantity`가 있음
`upcartSubscribeCartOpened(fn)`	카트 드로어 열림	`{}` (빈 객체)
`upcartSubscribeCartClosed(fn)`	카트 드로어 닫힘	`{}` (빈 객체)
`upcartSubscribeCartUpdated(fn)`	카트 내용 변경	`{ cart }`
`upcartSubscribeItemRemoved(fn)`	아이템 제거됨	`{ item }`
`upcartSubscribeCheckoutClicked(fn)`	체크아웃 버튼 클릭됨	`{ event }` - 브라우저 MouseEvent
`upcartSubscribeUpsellsAddedToCart(fn)`	업셀 아이템 추가됨	`{ variant }` - `.id`와 `.title`이 있음
`upcartSubscribeUpsellsRendered(fn)`	카트에 업셀이 렌더링됨	`{ item, element }` - item은 상품, element는 DOM 노드
`upcartSubscribeNotesTextChanged(fn)`	카트 노트 업데이트됨	`{ newNotesText, oldNotesText }` - 새 노트 문자열과 이전 문자열
`upcartSubscribeRewardsMilestonesCompletedChanged(fn)`	리워드 마일스톤 상태 변경	`{ numOfMilestonesCompleted, status }` - `status`는 `"promotion"`, `"demotion"`, 또는 `"initial-state"`

직접 액션 함수

함수	기능
`window.upcartOpenCart()`	카트 드로어를 열어요
`window.upcartCloseCart()`	카트 드로어를 닫아요
`window.upcartRefreshCart()`	카트 데이터를 새로고침해요
`window.upcartGetCart()`	현재 카트 객체를 반환해요
`window.upcartRegisterAddToCart()`	페이지 빌더(Replo, PageFly 등)용 add-to-cart를 등록해요
`window.upcartFormatMoney()`	스토어의 통화 형식으로 가격을 포맷해요

전체 API 문서는 Upcart Public API Documentation을 참조하세요.

문제 해결

스크립트가 실행되지 않나요? 배치를 다시 확인하세요: 로드 후가 아니라 _Scripts (before load)_에 있어야 해요.
요소를 찾을 수 없나요? 셀렉터(예: #upCartStickyButton)가 카트의 실제 요소 ID와 일치하는지 확인하세요.
뭔가 깨졌나요? 각 줄 시작에 //를 추가해 스크립트를 주석 처리하고, 저장한 다음 새로고침하세요.
여전히 막혀 있나요? 추가 문제 해결 단계는 API FAQ를 참조하세요.

시작하기

장바구니 모듈

장바구니 설정

고정 장바구니 버튼

멀티카트

사용자 지정

분석

연동 및 호환성

요금 및 계정

문제 해결

API 패턴 작동 방식

스크립트를 추가할 위치

레거시 콜백과 최신 콜백에 대한 참고 사항

예시 1: 카트가 비어 있을 때 고정 카트 버튼 숨기기

예시 2: 아이템이 카트에 추가될 때 로그 남기기

예시 3: 서드파티 분석 앱(예: TripleWhale)과 통합하기

예시 4: 상품이 추가된 후 카트 자동으로 열기

직접 액션 함수

문제 해결

​API 패턴 작동 방식

​스크립트를 추가할 위치

​레거시 콜백과 최신 콜백에 대한 참고 사항

​예시 1: 카트가 비어 있을 때 고정 카트 버튼 숨기기

​예시 2: 아이템이 카트에 추가될 때 로그 남기기

​예시 3: 서드파티 분석 앱(예: TripleWhale)과 통합하기

​예시 4: 상품이 추가된 후 카트 자동으로 열기

​빠른 참조: Subscribe 함수 (최신 API)

​직접 액션 함수

​문제 해결

API 패턴 작동 방식

스크립트를 추가할 위치

레거시 콜백과 최신 콜백에 대한 참고 사항

예시 1: 카트가 비어 있을 때 고정 카트 버튼 숨기기

예시 2: 아이템이 카트에 추가될 때 로그 남기기

예시 3: 서드파티 분석 앱(예: TripleWhale)과 통합하기

예시 4: 상품이 추가된 후 카트 자동으로 열기

빠른 참조: Subscribe 함수 (최신 API)

직접 액션 함수

문제 해결