상품·가격·세금 카탈로그
Paddle Product/Price, 국가별 가격, KRW, tax-inclusive/exclusive 정책 설계
핵심 요약
- Product/Price 구조는 코드보다 먼저 정해야 월마감·환불·권한·가격 변경이 흔들리지 않는 가장 오래 남는 결정이다.
- Product는 가치 묶음(Pro/Team), Price는 주기·금액으로 나누고, 국가별 가격은 country-specific price override로 조정한다.
- KRW는 소수점 없는 통화이므로 가격·할인·환불·분석 파이프라인에서
1000원 = 1000으로 처리되는지 확인한다. Price ID는 코드·권한 매핑에 쓰이므로 임의 삭제·재사용하지 않고, 가격 변경 전 grandfathering 여부를 먼저 결정한다.- Product의
tax_category와 Price의tax_mode를 가격 출시 전에 확정하고 변경 영향을 기존 구독까지 검토한다. - 원화 가격은 환율뿐 아니라 세금 포함 표시·수수료·환불률까지 반영한 하한을 검토한다.
Paddle 연동에서 가장 오래 남는 결정이 Product/Price 구조입니다. 코드를 짜기 전에 상품 카탈로그와 회계 분석 단위부터 정해 둬야 월마감, 환불, 권한 부여, 가격 변경이 흔들리지 않습니다.
기본 모델
| 개념 | 권장 사용 |
|---|---|
| Product | 고객이 구매하는 가치 묶음. 예: Pro, Team, Enterprise |
| Price | 결제 주기와 금액. 예: Pro Monthly, Pro Annual |
| Product tax category | saas, standard, digital-goods 등 상품의 과세 분류 |
| Price tax mode | 세금 포함·별도 표시 정책. 지역 자동 판단에는 location 검토 |
| Price override | 국가별 가격·통화 조정 |
| Discount | 캠페인/쿠폰. 장기 할인 정책은 별도 관리 |
| Transaction | Checkout, renewal, upgrade 등 과금 이벤트 |
| Subscription | 반복 과금과 권한의 기준 객체 |
SaaS 구독 카탈로그 예시
| Product | Price | Billing cycle | 권한 |
|---|---|---|---|
| Pro | Pro Monthly | monthly | 개인 고급 기능 |
| Pro | Pro Annual | yearly | 개인 고급 기능 + 연간 할인 |
| Team | Team Monthly | monthly | 워크스페이스, 멤버, 협업 |
| Team | Team Annual | yearly | 워크스페이스, 멤버, 협업 + 연간 할인 |
Product를 너무 잘게 쪼개면 권한 매핑은 쉬워지지만 가격 변경과 리포팅이 복잡해집니다. 반대로 하나의 Product에 전부 욱여넣으면 결제·권한·회계 분석 단위가 흐려집니다.
과금 패턴별 모델
| 패턴 | Paddle 모델 | 내부에서 추가로 필요한 것 |
|---|---|---|
| 고정 월간·연간 | recurring Price | 플랜·권한 매핑 |
| 좌석 과금 | subscription item quantity | 승인된 좌석 수와 실제 사용 좌석 reconcile |
| tier·volume | Price quantity tiers | preview와 proration QA |
| add-on | 같은 subscription의 추가 item | add-on별 entitlement·해지 정책 |
| 선불 credit | recurring/one-time charge + 내부 credit ledger | 잔액·만료·환불·세금 정책 |
| 사용량 후불 | usage를 외부에서 계량하고 upcoming transaction에 custom item 추가 | 계량 원장, cutoff, 고객 검증, 과다 청구 방지 |
| paid trial | trial period의 할인된 charge | 한국 유료전환 동의와 trial 가격 표시 |
순수 사용량 과금은 Paddle이 사용량 원장을 대신 보관한다고 가정하지 않습니다. 내부 metering과 immutable usage ledger를 원장으로 두고 Paddle에는 청구 시점의 line item을 전달합니다.
국가별 가격
Paddle은 country-specific price override를 제공합니다. 같은 Price를 기준으로 한국·일본·EU 등 국가마다 가격을 따로 조정할 수 있습니다.
| 지역 | 통화 | 권장 방식 |
|---|---|---|
| 한국 | KRW | 심리 가격을 직접 지정. 원화는 소수점 없음 |
| 미국 | USD | 기준 가격 |
| EU | EUR | VAT 포함/별도 표시 정책 확인 |
| 일본 | JPY | 소수점 없음, 소비세 포함 표시 확인 |
KRW 처리
Paddle API는 통화별 최소 단위로 금액을 다룹니다. KRW는 소수점이 없는 통화이므로 내부 가격 계산,
할인, 환불, 분석 파이프라인에서 1000원 = 1000으로 처리되는지 확인하세요.
세금 포함/별도 표시
Paddle은 MoR 거래의 국가별 거래세를 계산하지만, 가격 페이지 문구는 자사가 책임져야 합니다.
product.tax_category
Product API의 tax_category는 계정에 활성화된 과세 카테고리 중 하나를 지정하는 필수 필드입니다. SaaS라고
모든 상품을 기계적으로 saas로 두지 말고, 소프트웨어 구현·전문 서비스·교육·디지털 상품을 별도 Product로
분리합니다. 카테고리를 바꾸면 기존 subscription item의 세금 계산과 고객 청구액에 영향을 줄 수 있으므로
Finance 승인과 checkout preview를 거칩니다.
price.tax_mode
지역별로 세금 포함/별도 표시를 자동 결정하려면 지원되는 계정·가격에서 tax_mode: location을 검토합니다.
기존 internal, external, account_setting 가격과 섞여 있을 수 있으므로 API 응답을 기준으로 inventory를
만들고, B2C 표시가격·B2B VAT ID·country override 조합을 sandbox와 live에서 확인합니다.
| 고객 유형 | 권장 문구 |
|---|---|
| B2C | 결제 단계에서 적용 세금이 포함되거나 추가될 수 있음을 표시 |
| B2B | VAT ID/사업자 정보 입력 가능성과 reverse charge 가능성을 안내 |
| 한국 개인 | 원화 가격, 자동결제 주기, 해지/환불 조건을 명확히 표시 |
| 한국 법인 | Paddle 인보이스 발행 구조와 한국 세금계산서 제공 여부를 사전 안내 |
원화 가격 sanity check
원화 가격은 미국 가격 × 환율로만 정하지 말고 세금 포함 표시, Paddle 수수료, 고정 수수료, 환불률까지
반영해 최소 가격을 다시 보세요. 아래 계산기는 가격 후보를 확정하는 장치가 아니라, 가격 하한을 빠르게
가늠해 보는 도구입니다.
가격 변경 원칙
Price ID는 코드와 권한 매핑에 들어가므로 임의 삭제/재사용하지 않습니다.- 기존 고객 grandfathering 여부를 가격 변경 전에 결정합니다.
- 연간 결제 고객에게 변경 가격이 언제 적용되는지 이메일과 포털에서 확인 가능해야 합니다.
- 국가별 가격 override는 환율보다 전환율·환불률·지원 비용 기준으로 조정합니다.
내부 데이터 모델
plans
- internal_plan_code
- paddle_product_id
- paddle_tax_category
- paddle_price_ids[]
- paddle_tax_modes[]
- entitlement_set
- display_name
subscriptions
- user_id / workspace_id
- paddle_customer_id
- paddle_subscription_id
- paddle_status
- current_price_id
- next_billed_at
- entitlement_snapshot참고 자료
- Paddle Developer - Prices
- Paddle Developer - Products API
- Paddle Help - Taxable categories
- Paddle Developer - Automatic tax-inclusive/exclusive prices
- Paddle Developer - Supported currencies
- Paddle Developer - Localize prices
- Paddle Developer - SaaS billing patterns
- Paddle Developer - Usage-based billing for AI companies
- Paddle Developer - Paid trials