> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 할인
> 프로모션 코드를 생성하여 전환을 유도하고, 캠페인을 실행하고, 한 번 및 구독 구매 전반에 걸쳐 고객에게 퍼센트 할인을 제공합니다.
할인 코드를 사용하여 타겟 프로모션 및 인센티브를 실행하세요. 퍼센트 기반 할인을 생성하고, 제한 및 만료를 설정하고, 제품에 제한을 두고, 결제 시 원활하게 적용하세요.
호스팅된 체크아웃 중 `discount_codes` 및 UI 컨트롤로 하나 이상의 스택형 코드를 적용합니다.
할인 ID로 유효성을 확인하세요.
코드 이름(예: "SAVE20")을 사용해 할인을 조회하고 유효성을 확인하세요.
프로그래밍 방식으로 새로운 할인 코드를 생성하세요.
기존 할인을 찾아보고, 필요에 따라 업데이트하거나 삭제하세요.
## 할인 코드란?
할인 코드는 결제 시 주문 총액을 줄여주는 프로모션 토큰입니다. 다음과 같은 경우에 적합합니다:
* **계절 캠페인**: 블랙 프라이데이, 제품 출시 또는 기념일
* **획득 제안**: 첫 구매 인센티브 또는 추천 보상
* **유지**: 기존 고객을 위한 재유치 또는 충성도 보상
* **B2B 거래**: 계약된 또는 협상된 가격을 통한 비공식 코드
## 주요 이점
* **유연한 할인**: 비율 또는 고정 금액 할인
* **대상 제어**: 제품 및 구독 주기에 따라 제한
* **캠페인 관리**: 만료 날짜 및 사용 한도
* **원활한 결제**: 결제 세션을 통한 UI 필드 및 API 지원
* **유연한 할인**: 퍼센트 기반 할인
* **누적 가능한 코드**: 결제, 결제 수단, 또는 구독 당 최대 20개의 코드 적용 — 맞춤 코드를 생성하지 않고 캠페인을 결합하세요 (예: `WELCOME10` + `BLACKFRIDAY20`)
* **타겟 제어**: 제품 및 구독 주기에 따라 제한
* **캠페인 관리**: 만료 날짜와 사용 제한
* **원활한 결제**: 결제 세션을 통해 UI 필드 및 API 지원
Dodo Payments 대시보드에서 할인 코드를 생성한 후, 호스팅된 결제 또는 API를 통해 적용합니다.
### 대시보드 설정
* **할인 이름** (필수): 내부 및 대시보드 표시 이름
* **코드** (필수): 고객이 결제 시 입력하는 문자열
* **유형 및 금액** (필수): 비율 또는 고정 금액 값을 설정하거나 제공된 버튼을 사용하여 무작위 코드를 생성합니다.
* **만료 날짜** (선택 사항): 코드가 무효가 되는 날짜
* **사용 한도** (선택 사항): 모든 고객에 대한 최대 총 사용 횟수
* **제품 제한** (선택 사항): 선택한 제품에만 적용 가능하도록 제한
* **구독 주기 제한** (선택 사항): 할인이 적용되는 청구 주기 수
* **할인 이름** (필수): 내부 및 대시보드 표시 이름
* **코드** (필수): 고객이 입력하는 문자열
* **유형 및 금액** (필수): 퍼센트 값을 설정 (현재는 퍼센트 기반 할인만 지원), 또는 제공된 버튼을 사용하여 무작위 코드 생성
* **만료 날짜** (선택 사항): 코드가 무효화되는 날짜
* **사용 제한** (선택 사항): 모든 고객에 대한 최대 총 사용 횟수
* **제품 제한** (선택 사항): 선택한 제품에 대한 적용 제한
* **구독 주기 제한** (선택 사항): 할인이 적용되는 청구 주기 수
* **메타데이터** (선택 사항): 내부 추적 또는 통합을 위한 사용자 키-값 쌍 첨부
## 결제 경험
1. 쇼핑객이 결제 필드에 코드를 입력합니다.
2. 적격 할인 적용 후 총액이 즉시 업데이트됩니다.
Checkout Sessions에서 코드를 미리 적용하려면 `discount_code`를 전달하고, 입력 필드를 표시하려면 `feature_flags.allow_discount_code`를 설정하세요.
체크아웃 세션에서 코드 하나 이상을 미리 적용하기 위해 `discount_codes`(배열)을 전달하고 입력 필드를 표시하도록 `feature_flags.allow_discount_code`를 설정합니다. 코드는 배열 순서대로 적용되며 최대 20개까지 가능합니다.
## 할인 코드 스태킹
체크아웃 세션, 결제 및 구독은 **20개의 스택형 코드**까지 `discount_codes` 배열(최대 20항목)을 통해 수용합니다. 코드는 **배열 순서**대로 적용되며, 첫 번째 적용 가능한 코드가 기본 가격을 먼저 줄이며, 다음 코드는 이미 할인된 가격을 줄입니다. 모든 적용된 할인 세트는 응답에 `discount_ids`(결제/구독에서) 및 `discounts`(할인당 더 풍부한 세부사항 포함, 위치 및 남아있는 구독 주기 포함)로 반환됩니다.
```typescript theme={null}
const session = await client.checkoutSessions.create({
product_cart: [{ product_id: 'prod_abc', quantity: 1 }],
discount_codes: ['WELCOME10', 'BLACKFRIDAY20'], // applied in this order
customer: { email: 'user@example.com' },
return_url: 'https://yoursite.com/return'
});
```
단일 `discount_code` 필드는 **더는 지원되지 않음**이지만 하위 호환성을 위해 여전히 완전히 지원되며, 기존 통합은 변경 없이도 계속 작동합니다. 같은 요청에서 `discount_codes`와 결합될 수 없습니다. 스태킹과 더 풍부한 형태의 응답을 이용하려면, 싱글 코드에도 언제든지 `discount_codes`(배열 형태)로의 마이그레이션을 권장합니다.
## API 관리
유형 및 금액으로 프로그램matically 할인 코드를 생성합니다.
할인 생성 API를 봅니다.
모든 할인을 나열하거나 관리 및 감사 세부 정보를 검색합니다.
목록 및 검색 API를 탐색합니다.
내부 ID 대신 사람에게 읽기 쉬운 코드 (e.g., "SAVE20")를 사용하여 할인을 조회합니다.
코드명으로 할인 검색.
금액, 만료, 제약 조건과 같은 할인 구성을 수정합니다.
할인 세부 사항 업데이트 방법 알아보기.
적용하기 전에 할인이 유효하고 적용 가능한지 확인합니다.
할인 사용 유효성 검사.
더 이상 필요하지 않은 할인을 비활성화하거나 제거합니다.
할인 삭제.
## 일반적인 사용 사례
* **소개 오퍼**: 신제품을 위한 제한된 시간 동안의 출시 프로모션
* **대량 또는 B2B**: 선택된 제품 세트에 대한 계약된 할인
* **유지 전략**: 이탈 방지 워크플로우의 재유치 코드
* **시즌별 캠페인**: 휴일 또는 이벤트 기반의 프로모션
## 통합 예시
### 메타데이터가 포함된 할인 생성
내부 추적을 위한 맞춤 키-값 쌍 첨부.
```typescript theme={null}
const discount = await client.discounts.create({
type: 'percentage',
amount: 1500, // 15%
code: 'SUMMER2025',
metadata: {
campaign: 'summer_promo',
source: 'email_blast'
}
});
```
메타데이터를 사용하여 할인에 캠페인, 소스, 내부 참조 ID로 태그를 붙여 나중에 사용량을 조정하고 ROI를 측정할 수 있습니다.
### 체크아웃 세션에서 할인 적용
하나 이상의 스택형 할인을 미리 적용하고 코드 입력 UI를 표시합니다.
```typescript theme={null}
const session = await client.checkoutSessions.create({
product_cart: [
{ product_id: 'prod_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'
});
```
### 플랜 변경 시 할인 적용
고객이 구독을 업그레이드하거나 다운그레이드 할 때 프로모션 가격을 제공합니다.
```typescript theme={null}
await client.subscriptions.changePlan('sub_123', {
product_id: 'prod_pro',
quantity: 1,
proration_billing_mode: 'prorated_immediately',
discount_codes: ['UPGRADE20']
});
```
| `discount_codes` 값 | 플랜 변경 시 동작 |
| ------------------------------ | ------------------------------------------------------------------ |
| `undefined` / `null` (제공되지 않음) | 기존 할인이 새로운 제품에 적용 가능한 경우 `preserve_on_plan_change=true`와 함께 유지됩니다. |
| `[]` (빈 배열) | **모든** 기존 할인이 구독에서 제거됩니다. |
| `['CODE_A', 'CODE_B', ...]` | 기존 할인을 이 스택형 세트로 대체하며, 배열 순서대로 적용됩니다. |
구독 응답의 새로운 `discounts` 배열을 통해 구독에서 모든 적용된 할인을 읽습니다. 각 항목에는 `discount_id`, `position`, `cycles_remaining`(구독용), 및 원본 코드가 포함됩니다.
### 미리 적용하지 않고 할인 입력 활성화
고객이 사전 전달 없이 체크아웃 시 코드를 입력할 수 있도록 합니다.
```typescript theme={null}
const session = await client.checkoutSessions.create({
product_cart: [
{ product_id: 'prod_abc', quantity: 1 }
],
feature_flags: {
allow_discount_code: true
},
return_url: 'https://yoursite.com/return'
});
```
## 모범 사례
* **분명한 이름 사용**: 캠페인 이름과 일치하는 알아보기 쉬운 코드 사용
* **기한 설정**: 만료를 추가하여 긴급성을 유발하고 오용 방지
* **현명하게 범위 설정**: 특정 제품에만 제한하여 이익 손실 방지
* **조기에 유효성 검사**: 체크아웃을 확인하기 전에 코드 적용 가능 여부 확인
* **영향 모니터링**: 캠페인별 사용 및 전환 추적
할인 코드는 획득 및 유지에 강력한 레버입니다. 간단하고 잘 이름 붙인 오퍼로 시작하고, 철저히 검증하며, 성과에 따라 반복하십시오.