할인

​

할인 코드란?

• 유연한 할인: 비율 또는 고정 금액 할인
• 대상 제어: 제품 및 구독 주기에 따라 제한
• 캠페인 관리: 만료 날짜 및 사용 한도
• 원활한 결제: 결제 세션을 통한 UI 필드 및 API 지원
• 유연한 할인: 백분율 기반 또는 정액 기반 할인
• 중첩 가능한 코드: checkout, 결제 또는 subscription당 최대 20개 코드 적용
• 타겟 제어: 제품, subscription 주기 및 고객 자격에 따른 제한
• 캠페인 관리: 예약된 시작일, 만료일, 전체 및 고객별 사용 한도
• 통화별 가격 설정: 각 통화별 정액 차감액, 금액 상한 및 최소 소계 설정

​

대시보드 설정

​

Dashboard 설정

• Discount Name (필수): 대시보드에서 사용하는 내부 레이블입니다.
• Code (필수): 고객이 checkout에서 입력하는 문자열입니다. 무작위 코드를 생성하거나 직접 입력할 수 있습니다(최소 3자, 자동으로 대문자 변환).
• Type (필수): Percentage(백분율 할인) 또는 Amount(고정 금액 차감)입니다.
• Amount (필수): 백분율의 경우 대시보드에서 할인할 백분율입니다(예: 15(15%)). API에서는 동일한 값이 basis points로 전달됩니다(1500). 금액의 경우 code의 기본 통화로 적용되는 고정 차감액입니다.
• Start Date (선택 사항): 향후 날짜에 code가 활성화되도록 예약합니다. 즉시 활성화하려면 비워 두세요.
• Expiration Date (선택 사항): code를 더 이상 사용할 수 없게 되는 날짜입니다.
• Usage Limit (선택 사항, Advanced 아래): 모든 고객을 대상으로 한 최대 사용 횟수입니다. multi-subscription cart는 사용 1회로 계산됩니다.
• Per-Customer Usage Limit (선택 사항, Advanced 아래): 단일 고객이 사용할 수 있는 최대 횟수입니다. 두 값이 모두 설정된 경우 전체 사용 한도보다 작거나 같아야 합니다.
• Customer Eligibility (선택 사항): 사용할 수 있는 고객을 제한합니다 — 모든 고객, 첫 구매 고객, 기존 고객 또는 직접 선택한 목록 중에서 지정할 수 있습니다.
• Currency Options (선택 사항): 판매하는 각 통화별 할인 금액입니다. Per-Currency Options를 참조하세요.
• Product Restriction (선택 사항): 특정 product로 code 사용을 제한합니다.
• Subscription Cycle Limit (선택 사항, Advanced 아래): 할인이 적용되는 billing cycle 수입니다. 무기한 적용하려면 비워 두세요.
• Preserve on Plan Change (선택 사항): subscription이 plan을 변경할 때도 할인을 활성 상태로 유지합니다(preserve_on_plan_change).
• Metadata (선택 사항): 내부 추적을 위한 사용자 지정 key–value 쌍을 추가합니다.
• Require a minimum order value (선택 사항, Advanced 아래): code가 적용되기 위한 최소 cart subtotal(통화별)입니다.

​

할인 유형

​

고객 자격

​

통화별 옵션

• Amount — Amount 할인인 경우 해당 통화로 표시되는 정액 차감액이며, Percentage 할인인 경우 최대 할인 상한입니다. API에서는 max_amount_possible에 매핑됩니다.
• Default — 하나의 통화를 기본 통화로 지정합니다. 설정되지 않은 통화는 이 기본 통화에서 환산됩니다.

• Minimum subtotal — 해당 통화의 장바구니 소계가 이 금액에 도달한 경우에만 코드가 적용됩니다. 0는 최소 금액이 없음을 의미합니다.

​

Checkout Experience

​

Stacking Discount Codes

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
  discount_codes: ['WELCOME10', 'BLACKFRIDAY20'], // applied in this order
  customer: { email: 'user@example.com' },
  return_url: 'https://yoursite.com/return'
});

​

API Management

​

Common Use Cases

• Intro offers: 새로운 product를 위한 기간 한정 출시 프로모션
• Bulk or B2B: 특정 product 묶음을 위한 계약 할인
• Retention plays: churn 방지 workflow에서 고객 재유치를 위한 code
• Seasonal campaigns: holiday 또는 event 기반 프로모션

​

Integration Examples

​

Create a Discount with Metadata

const discount = await client.discounts.create({
  type: 'percentage',
  amount: 1500, // 15%
  code: 'SUMMER2025',
  metadata: {
    campaign: 'summer_promo',
    source: 'email_blast'
  }
});

​

Apply Discounts in Checkout Sessions

const session = await client.checkoutSessions.create({
  product_cart: [
    { product_id: 'pdt_abc', quantity: 1 }
  ],
  discount_codes: ['BLACKFRIDAY2024', 'NEWUSER5'], // stacked in array order
  customer: { email: 'user@example.com', name: 'Jane Doe' },
  return_url: 'https://yoursite.com/return'
});

​

Apply Discounts During Plan Changes

await client.subscriptions.changePlan('sub_123', {
  product_id: 'pdt_pro',
  quantity: 1,
  proration_billing_mode: 'prorated_immediately',
  discount_codes: ['UPGRADE20']
});

​

Hide the Discount Code Field

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_abc', quantity: 1 }],
  feature_flags: {
    allow_discount_code: false
  },
  return_url: 'https://yoursite.com/return'
});

​

Best Practices

• Name clearly: campaign name과 일치하는 알아보기 쉬운 code를 사용하세요.
• Time-box: 긴급성을 높이고 오용을 방지하기 위해 expiration을 추가하세요.
• Scope wisely: margin leakage를 방지하기 위해 특정 product로 제한하세요.
• Validate early: checkout을 확정하기 전에 code 적용 가능성을 확인하세요.
• Monitor impact: campaign별 사용량과 conversion을 추적하세요.