> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aftersell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 일반적인 Upcart API 활용법

> 실용적인 복사-붙여넣기 예시로 Upcart의 Public API를 활용하는 방법을 알아보세요.

<div id="how-the-api-pattern-works">
  ## API 패턴 작동 방식
</div>

대부분의 Upcart API 스크립트는 동일한 간단한 패턴을 따라요:

카트 이벤트 수신 → 조건 확인 → 액션 실행

예를 들어: "카트가 로드되면 → 비어 있는지 확인하고 → 고정 버튼을 숨겨요."

💡 **API가 처음이신가요?** 아래 예시로 들어가기 전에 [API란 무엇인가요?](/ko/upcart/what_is_an_api)부터 시작해 보세요.

***

<div id="where-to-add-your-scripts">
  ## 스크립트를 추가할 위치
</div>

아래의 모든 스크립트는 다음 위치에 추가하세요:

**Cart Editor → Settings → Custom HTML → Scripts (before load)**

각 스니펫을 `<script>...</script>` 태그로 감싸고 저장하세요. 테스트하려면 브라우저의 개발자 도구 콘솔(`F12`)을 열고 `console.log` 메시지를 확인하세요.

***

<div id="a-note-on-legacy-vs-modern-callbacks">
  ## 레거시 콜백과 최신 콜백에 대한 참고 사항
</div>

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

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

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

***

<div id="example-1-hide-the-sticky-cart-button-when-the-cart-is-empty">
  ## 예시 1: 카트가 비어 있을 때 고정 카트 버튼 숨기기
</div>

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<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`를 순회하며 합계를 계산해야 해요.

***

<div id="example-2-log-when-an-item-is-added-to-the-cart">
  ## 예시 2: 아이템이 카트에 추가될 때 로그 남기기
</div>

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<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             |

***

<div id="example-3-integrate-with-a-third-party-analytics-app-eg-triplewhale">
  ## 예시 3: 서드파티 분석 앱(예: TripleWhale)과 통합하기
</div>

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<script>
  window.upcartSubscribeAddedToCart(function(event) {
    window.TriplePixel('AddToCart', {
      item: event.item.variantId,
      q: event.item.quantityAdded
    });
  });
</script>
```

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

***

<div id="example-4-open-the-cart-automatically-after-a-product-is-added">
  ## 예시 4: 상품이 추가된 후 카트 자동으로 열기
</div>

```html theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
<script>
  window.upcartSubscribeAddedToCart(function(event) {
    window.upcartOpenCart();
  });
</script>
```

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

***

<div id="quick-reference-subscribe-functions-modern-api">
  ## 빠른 참조: Subscribe 함수 (최신 API)
</div>

| 함수                                                     | 실행 시점          | 콜백이 받는 값                                                                                             |
| ------------------------------------------------------ | -------------- | ---------------------------------------------------------------------------------------------------- |
| `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"` |

***

<div id="direct-action-functions">
  ## 직접 액션 함수
</div>

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

전체 API 문서는 [Upcart Public API Documentation](https://rokt.notion.site/upcart-public-api)을 참조하세요.

***

<div id="troubleshooting">
  ## 문제 해결
</div>

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