스킨 연동 가이드

대상: 쇼핑몰 스킨을 작업하는 디자이너·퍼블리셔 · 문서 버전 2026-11-06 · 데이터 버전 1

1. 이 데이터로 할 수 있는 것
2. 데이터 위치와 읽는 방법
3. 전체 구조
4. 필드 설명
5. 값이 없을 수 있는 경우
6. 할인 금액 계산
7. 활용 예제

1. 이 데이터로 할 수 있는 것

"내 마음대로 할인" 앱이 설치된 쇼핑몰의 메인 · 상품 목록 · 검색 결과 · 상품 상세 페이지에는 지금 보고 있는 방문자에게 해당하는 할인 정보가 JSON 데이터로 들어 있습니다. 스킨에서 이 데이터를 읽으면 할인 표시를 원하는 모양으로 직접 만들 수 있습니다.

• 상품 카드의 할인율 배지, 할인가
• 타임세일 남은 시간 카운트다운
• 한정 수량 남은 개수 ("오늘 37개 남음")
• 수량별 할인 단계 안내 ("3개 이상 13% 할인")
• 회원 등급 혜택, 첫 구매 혜택 문구

2. 데이터 위치와 읽는 방법

데이터는 페이지 <head>에 아래 태그로 들어갑니다. 화면에는 보이지 않습니다.

<script type="application/json" id="wonlab-dp-discount-data">
  ...JSON...
</script>

언제 들어가나요

• 페이지가 열린 뒤 앱이 할인 정보를 받아 와서 넣습니다. 그래서 스킨 HTML이 그려지는 순간에는 아직 없을 수 있습니다.
• 더보기·무한 스크롤로 상품이 추가되면 그 상품들이 데이터에 추가됩니다.
• 데이터가 들어가거나 바뀔 때마다 document에서 wonlab:dp:discount-data 이벤트가 발생합니다.

권장 읽기 방법

"지금 있는 데이터를 한 번 읽고 + 이후 바뀔 때마다 다시 읽기"를 함께 쓰면 타이밍 문제 없이 동작합니다.

function readDiscountData() {
    var tag = document.getElementById('wonlab-dp-discount-data');
    if (!tag) return null;
    try { return JSON.parse(tag.textContent); } catch (e) { return null; }
}

function render() {
    var data = readDiscountData();
    if (!data || !data.products) return;
    // 여기서 할인 표시를 그립니다 (예제는 7장 참고)
}

render();                                                    // 이미 들어 있는 경우
document.addEventListener('wonlab:dp:discount-data', render); // 나중에 들어오거나 바뀌는 경우

• 이벤트의 event.detail.product_nos에는 이번에 추가·갱신된 상품 번호 목록이 들어 있습니다. 빈 배열이면 회원 정보 같은 페이지 공통 정보만 바뀐 것입니다. 전체를 다시 그려도 되고, 이 목록의 상품만 다시 그려도 됩니다.
• 같은 상품이 여러 번 그려지지 않도록, 이미 그린 요소는 다시 만들지 말고 내용만 바꿔 주세요.
• 태그 내용을 직접 고치지 마세요. 앱이 갱신할 때 덮어씁니다.

3. 전체 구조

예시 값입니다. 실제로는 해당하는 할인만 들어 있습니다.

{
  "version": 1,
  "products": {
    "123": {
      "source": "detail",
      "price": 42000,
      "discounts": {
        "base": { "type": "rate", "value": 10,
                  "start_date": "2026-11-01 00:00:00", "end_date": "2026-11-30 23:59:59",
                  "limit": 100, "limit_type": "daily", "remaining": 37 },
        "time_sale": { "type": "rate", "value": 20, "time_start": "10:00:00", "time_end": "22:00:00",
                       "end_date": "2026-11-30 23:59:59" },
        "member_group": { "type": "rate", "value": 5, "group_no": 2, "group_name": "VIP" },
        "first_purchase": { "type": "fixed", "value": 3000 },
        "product_first_purchase": { "type": "rate", "value": 10 },
        "quantity": { "type": "rate", "value": 10, "threshold": 2,
                      "tiers": [ { "threshold": 2, "value": 10 }, { "threshold": 3, "value": 13 } ] }
      },
      "is_first_purchase_eligible": true,
      "is_product_first_purchase_eligible": false,
      "fp_apply_scope": "all",
      "excluded_variants": ["P000000X000A"]
    },
    "456": {
      "source": "list",
      "price": 29000,
      "discounts": {},
      "is_first_purchase_eligible": false,
      "is_product_first_purchase_eligible": false
    }
  },
  "member": { "logged_in": true, "group_no": 2 },
  "server_time": "2026-11-06T14:20:00+09:00"
}

4. 필드 설명

최상위

상품 (products["상품번호"])

할인 유형 (discounts의 키)

할인 기간이 시작 전이거나 끝난 할인, 적용 시간 밖의 타임세일, 한정 수량이 다 팔린 할인은 데이터에서 빠집니다.

할인 항목 공통 필드

유형별 추가 필드

5. 값이 없을 수 있는 경우

아래 경우에는 필드가 아예 없을 수 있습니다. 값이 있는지 확인한 뒤 사용하고, 없으면 해당 표시를 숨기도록 만들어 주세요.

• 할인이 없는 상품 — discounts가 빈 객체입니다.
• 목록 상품의 price — 목록의 판매가는 화면의 상품 카드에서 읽어 옵니다. 스킨 구조상 가격을 읽지 못한 상품은 price가 없습니다.
• 상품 상세 전용 필드 — fp_apply_scope, excluded_variants는 목록 상품에는 없습니다.
• 쇼핑몰이 앱의 이전 버전 표시 방식을 쓰는 경우 — price, tiers, fixed_mode, limit·limit_type·remaining, member, server_time이 없고, 목록 상품에는 첫 구매 대상 여부(is_*_eligible)도 없습니다. 이 필드가 필요하면 쇼핑몰 운영자에게 새 표시 방식 사용 여부를 확인해 주세요.
• 페이지에 상품이 없는 경우 — 태그 자체가 만들어지지 않습니다.

6. 할인 금액 계산

화면에 할인가를 보여 줄 때는 아래 규칙으로 계산하면 앱의 기본 표시와 같은 값이 나옵니다.

• 정률: 판매가 × 할인율 ÷ 100, 원 미만은 버립니다.
• 정액: value원 (상품 1개 기준).
• 할인이 여러 개: 각 할인을 판매가 기준으로 따로 계산해 더합니다. 할인된 금액에 다시 할인하지 않습니다.
  예) 30,000원 상품에 기본 10% + 회원등급 5% → 3,000원 + 1,500원 = 4,500원 할인, 25,500원

지금 이 방문자에게 적용되는 할인

• base, time_sale, member_group — 데이터에 있으면 적용됩니다.
• first_purchase, product_first_purchase — 각각 is_first_purchase_eligible, is_product_first_purchase_eligible이 true일 때만 적용됩니다. false라면 "회원가입 후 첫 구매 시 10% 할인"처럼 안내 문구로 쓰세요.
• quantity — 담는 수량에 따라 달라지므로 할인가에 미리 넣지 말고 "2개 이상 10% 할인" 같은 안내로 보여 주는 것을 권장합니다.

function discountAmount(d, price) {
    if (!d || !price) return 0;
    if (d.type === 'rate') return Math.floor(price * d.value / 100);
    return Number(d.value) || 0;
}

// 1개 구매 기준, 지금 이 방문자에게 적용되는 할인 합계
function currentDiscount(product) {
    var ds = product.discounts || {};
    var price = product.price;
    var sum = discountAmount(ds.base, price)
            + discountAmount(ds.time_sale, price)
            + discountAmount(ds.member_group, price);
    if (product.is_first_purchase_eligible) sum += discountAmount(ds.first_purchase, price);
    if (product.is_product_first_purchase_eligible) sum += discountAmount(ds.product_first_purchase, price);
    return Math.min(sum, price);
}

7. 활용 예제

예제의 클래스명·문구는 자유롭게 바꿔 쓰시면 됩니다. 아래 코드는 2장의 readDiscountData(), 6장의 discountAmount()·currentDiscount()를 함께 넣었다고 가정합니다.

7-1. 상품 목록 카드에 할인율 배지

스킨의 상품 목록 모듈에서 카드마다 상품번호를 속성으로 달고, 배지 자리를 만들어 둡니다. ({$product_no}는 카페24 상품 목록 모듈의 상품번호 변수입니다.)

<li class="prd-item" data-my-product="{$product_no}">
    ...
    <span class="my-discount-badge" hidden></span>
</li>

function renderBadges() {
    var data = readDiscountData();
    if (!data || !data.products) return;
    document.querySelectorAll('[data-my-product]').forEach(function (card) {
        var product = data.products[card.getAttribute('data-my-product')];
        var badge = card.querySelector('.my-discount-badge');
        if (!badge) return;
        if (!product || !product.price) { badge.hidden = true; return; }
        var amount = currentDiscount(product);
        var rate = Math.floor(amount / product.price * 100);
        badge.textContent = rate + '%';
        badge.hidden = !(rate > 0);
    });
}
renderBadges();
document.addEventListener('wonlab:dp:discount-data', renderBadges);

7-2. 상품 상세에 타임세일 남은 시간

지금 보고 있는 상품은 source가 detail인 상품입니다. 방문자 PC 시계 대신 server_time을 기준으로 계산합니다.

<div class="my-timesale" hidden>타임세일 종료까지 <b class="my-timesale-left"></b></div>

var timer = null;

function renderTimeSale() {
    var data = readDiscountData();
    var box = document.querySelector('.my-timesale');
    if (!data || !data.products || !data.server_time || !box) return;

    var product = null;
    Object.keys(data.products).forEach(function (no) {
        if (data.products[no].source === 'detail') product = data.products[no];
    });
    var ts = product && product.discounts.time_sale;
    if (!ts || !ts.time_end) { box.hidden = true; return; }

    // 서버 시각과 방문자 PC 시계의 차이를 보정
    var offset = Date.parse(data.server_time) - Date.now();
    var endTime = ts.time_end.length === 5 ? ts.time_end + ':00' : ts.time_end;
    var end = Date.parse(data.server_time.slice(0, 10) + 'T' + endTime + '+09:00');

    clearInterval(timer);
    function tick() {
        var left = Math.floor((end - (Date.now() + offset)) / 1000);
        if (left <= 0) { box.hidden = true; clearInterval(timer); return; }
        var h = Math.floor(left / 3600), m = Math.floor(left % 3600 / 60), s = left % 60;
        box.querySelector('.my-timesale-left').textContent =
            h + '시간 ' + String(m).padStart(2, '0') + '분 ' + String(s).padStart(2, '0') + '초';
        box.hidden = false;
    }
    tick();
    timer = setInterval(tick, 1000);
}
renderTimeSale();
document.addEventListener('wonlab:dp:discount-data', renderTimeSale);

7-3. 한정 수량 · 수량별 할인 안내 문구

function limitText(d) {
    if (!d || d.remaining == null) return '';
    return (d.limit_type === 'daily' ? '오늘 ' : '') + d.remaining + '개 남음';
}

function quantityText(q) {
    if (!q) return '';
    var tiers = q.tiers || [{ threshold: q.threshold, value: q.value }];
    var unit = q.type === 'rate' ? '%' : '원';
    return tiers.map(function (t) {
        return t.threshold + '개 이상 ' + Number(t.value).toLocaleString() + unit + ' 할인';
    }).join(' / ');
}
// 예) "오늘 37개 남음", "2개 이상 10% 할인 / 3개 이상 13% 할인"