구독은 구독 템플릿 → 구독 정책 → 구독 상품 → 구독 계약 네 계층으로 흐릅니다. 이 문서는 각 계층과 가격·정책이 상품과 계약에 도달하는 경로, 용어를 정리합니다. 승인·거절·재활성화 같은 액션 용어는 구독 용어 사전에 있습니다.
같은 주문에 서로 다른 상품 두 종류를 넣고 구독으로 신청하면 ORDER_SUBSCRIPTION_INVALID 로 거절됩니다.
수량은 늘려도 되지만 상품 ID 는 하나여야 합니다. 여러 상품을 구독시키려면 계약을 나눠 만듭니다.
일반(비구독) 주문에는 이 제약이 없습니다.
1네 계층
| 계층 | 권장 용어 | 내부 모델 | 역할 |
|---|---|---|---|
| 1 | 구독 템플릿 | SubscriptionSetting (상품과 연결되지 않은 것) |
여러 상품에 재사용할 정책·계산 규칙 팩 |
| 2 | 구독 정책 | SubscriptionSetting (상품에 귀속된 것), SubscriptionSettingSnapshot |
특정 상품에 고정된 정책 |
| 3 | 구독 상품 | Product + embedded SubscriptionPeriod |
고객에게 노출되는 회차별 가격표를 가진 상품 |
| 4 | 구독 계약 | OrderSubscription + embedded SubscriptionSettingSnapshotEmbed |
주문 시점에 정책을 박아 살아 있는 계약 |
SubscriptionSetting 한 모델이 상품 귀속 여부(pd_id 유무)에 따라 템플릿과 정책 두 역할을 겸합니다. 템플릿은 pd_id 에 속하지 않을 수 있습니다.
흐름은 단방향입니다.
- 관리자가 템플릿을 등록합니다.
- 상품을 만들 때 템플릿을 참조해 상품 귀속 정책과 회차 가격표를 생성합니다.
- 고객이 구독을 신청하면 상품의 정책이 계약 쪽에 스냅샷으로 박힙니다.
- 계약 스냅샷은 불변입니다. 이후 템플릿·상품을 수정해도 이미 체결된 계약의 정책은 바뀌지 않습니다.
2템플릿 가격과 상품 회차 가격
가격은 템플릿(계산 규칙)과 상품(결과 가격표) 두 곳에 저장되며, 둘은 서로 다른 값입니다.
템플릿 가격 = 계산 규칙
모델: SubscriptionSettingPrice + SubscriptionSettingPriceOption.
apply_target: 상품원가에 적용할지, 회차비용에 적용할지 지정합니다.price_type: 정률(1) / 정액(2).use_prepaid,use_deposit: 선급금·보증금 여부.- 옵션의
price가 음수면 할인입니다.
예: 원가에 10%를 더하고 1회차에 보증금 50,000원을 얹는 규칙.
상품 회차 가격 = 결과 가격표
모델: SubscriptionPeriod (Product·ProductOption에 embed).
cost_price: 원가.display_price: 판매가.tax_free_price: 비과세가.discount_price,discount_price_type: 할인가·할인 유형.expected_residual_value: 예상 잔존가치(렌탈·리스).use_times_benefit: 회차별 혜택 사용 여부.
예: 1회차 9,900원, 2회차 9,900원, …, 12회차 8,000원 같은 계산된 결과 표.
관계
규칙(템플릿) → 자동계산 → 결과표(상품) 한 방향입니다. 상품에 박힌 회차 가격이 고객에게 보이고 결제의 기준이 됩니다. 템플릿의 규칙은 한 번 계산되고 나면 상품에 복제됩니다. 템플릿을 수정해도 기존 상품·계약 가격은 자동으로 갱신되지 않습니다.
3관리자 화면 라벨과 문서 용어
관리자 화면의 한글 라벨과 문서 용어의 대응입니다.
| 관리자 화면에서 보이는 말 | 이 문서의 용어 | 의미 |
|---|---|---|
| 구독 템플릿 | 구독 템플릿 | 여러 상품에 재사용하는 정책·계산 규칙 팩 |
| 구독 템플릿명 · 구독 정책 · 구독 설정 (혼용) | 구독 정책 | 특정 상품에 고정된 정책 |
| 반복 요금 · 회차 설정 (템플릿 탭) | 회차 자동계산 규칙 | 금액을 만들어 내는 규칙. 결과 숫자가 아닙니다 |
| 구독기간 · 회차 · 회차 설정 (상품 편집) | 회차 가격표 | 고객에게 보이는 회차별 금액. 규칙의 결과입니다 |
| 구독 · 주문 구독 · 구독 관리 | 구독 계약 | 고객과 체결돼 살아 있는 계약 |
| 회차 · 구독 결제 | 회차 청구 | 한 회차분의 청구·결제 |
상품 편집 화면에서 템플릿을 불러오는 단계는 "구독 템플릿"이고, 불러온 결과가 그 상품에 박히면 "구독 정책"이 됩니다. 템플릿을 나중에 고쳐도 이미 상품에 박힌 정책과 체결된 계약은 바뀌지 않습니다.
"구독 플랜"이라는 말은 쓰지 않습니다
문서에서는 "구독 플랜"이라는 말을 쓰지 않습니다. 플랜이라는 단어를 만나면 맥락을 보고 구독 템플릿 / 구독 정책 / 구독 상품 / 회차 가격표 중 하나로 바꿔 읽습니다. URL의 /subscription/plan/*은 "계약을 설계하는 단계"를 뜻하는 단계명일 뿐입니다.
4모델-API-한글 용어 매핑
관리자 API와 공개 API에서 다루는 리소스를 용어에 맞춰 정리합니다.
| 모델 | API 리소스 | 권장 용어 |
|---|---|---|
SubscriptionSetting |
subscription_settings |
구독 템플릿 / 구독 정책 (pd_id 유무로 구분) |
SubscriptionSettingPrice |
템플릿 하위 구조 | 템플릿 가격 규칙 |
SubscriptionSettingPriceOption |
템플릿 하위 구조 | 템플릿 가격 옵션 |
SubscriptionPeriod |
상품 하위 구조 | 회차 가격표 |
SubscriptionTimesBenefit |
회차 가격표 하위 구조 | 회차 혜택 |
SubscriptionSettingSnapshot |
상품 하위 구조 | 정책 스냅샷 (상품 단위) |
SubscriptionSettingSnapshotEmbed |
구독 계약 하위 구조 | 정책 스냅샷 (계약 단위) |
Product |
products |
상품 (구독이 붙으면 구독 상품) |
OrderSubscription |
order_subscriptions |
구독 계약 |
OrderSubscriptionBill |
order_subscription_bills |
회차 청구 |
관리자 화면에서 보이는 "템플릿 목록"은 SubscriptionSetting 중 pd_id가 없는 레코드를, "이 상품의 구독 설정"은 pd_id가 있는 레코드를 각각 필터링해 보여줍니다.
5자주 혼동되는 것
템플릿 vs 정책
둘 다 SubscriptionSetting이지만 상품에 묶였는지 여부가 다릅니다. 묶이지 않은 것이 템플릿, 묶인 것이 정책입니다. 상품에 묶인 것은 "이 상품의 구독 정책"으로 부릅니다.
정책 vs 정책 스냅샷
정책은 현재 시점의 값이고, 스냅샷은 과거 어느 시점에 박힌 불변 사본입니다. 상품 단위 스냅샷(SubscriptionSettingSnapshot)은 상품 버전이 바뀔 때 쓰이고, 계약 단위 스냅샷(SubscriptionSettingSnapshotEmbed)은 주문이 생성된 시점의 정책을 고정합니다. 계약이 체결된 뒤 정책을 수정해도 해당 계약은 스냅샷을 따릅니다.
상품 vs 구독 상품
상품은 엔티티, 구독 상품은 "구독 정책이 붙은 상품"이라는 상태를 가리키는 말입니다. 별도 테이블이 있지는 않습니다. "구독 상품을 만든다"는 "상품에 구독 정책을 바인딩한다"와 같습니다.
구독 vs 구독 계약
살아 있는 고객의 구독 건을 가리킬 때는 구독 계약(OrderSubscription)이라고 쓰고, 약어가 필요하면 "계약"이라고 씁니다.
플랜
엔티티 용어에서 "플랜"은 쓰지 않습니다. "플랜"은 문맥에 따라 템플릿·정책·상품·회차 가격표 중 하나를 뜻합니다.



