핵심 요약
- 구독 연동은 계약 정의, 가입, 회차 청구, 조정, 관리 다섯 단계를 순서대로 붙여야 안정적이에요.
- 일반 결제와 달리 첫 결제 이후의 운영 단계가 길기 때문에 문서 읽는 순서 자체가 구현 순서가 돼요.
plan → subscribe → bill → adjust → manage흐름이 commerce 구독의 기본 골격이에요.- 가입 승인과 운영 복구는 다른 단계이므로 같은 용어로 다루지 않는 편이 안전해요.
이런 상황이라면
월간 요금제, 멤버십, 정기배송처럼 한 번 팔고 끝나지 않는 서비스라면 이 순서로 보면 돼요. 첫 결제만 붙여 두고 이후 회차 처리나 해지 운영을 나중에 보완하려 하면 정책 충돌이 쉽게 생겨요. 결제 API 빌링을 직접 조합하기보다 commerce 구독 라이프사이클을 그대로 쓰고 싶다면 이 순서가 가장 짧아요.
구독은 개별 API보다 단계 사이 연결을 이해하는 것이 더 중요해요.
1계약 정의 (/subscription/plan/contract)
구독은 먼저 무엇을 어떤 주기로 팔 것인지 정해야 해요. 이 단계에서 가격, 주기, 약정, 상품 구성이 흔들리면 이후 가입과 조정 문서가 모두 불안정해져요. 엔티티 네 계층(구독 템플릿 · 구독 정책 · 구독 상품 · 구독 계약) 의 관계는 구독 모델 구조에서 봐요.
핵심 문서:
이 단계에서 정할 내용:
- 월간인지 연간인지
- 기본 구독 상품과 상위 구독 상품을 어떻게 나눌지 (회차 가격표 설계)
- 가입 즉시 과금인지 체험 후 과금인지
- 회차 금액 조정이 가능한 상품인지
계약 정의는 기획 문서가 아니라 운영 규칙 문서라고 생각하는 편이 맞아요.
2가입 (/subscription/subscribe/purchase)
계약 정의를 마쳤다면 고객이 실제로 구독을 시작하는 진입점을 만들어요. 여기서는 purchase가 시작점이고 approve와 reject가 그 뒤를 이어져요.
핵심 문서:
이 단계에서 정할 내용:
- 고객이 신청 즉시 결제하는가
- 관리자 승인이 필요한가
- 신청 철회가 가능한가
- 다른 사용자에게 이전할 수 있는가
가입 단계는 계약을 시작할지 말지를 결정하는 구간이에요. 운영 단계의 해지·거절과 섞어 읽지 않는 편이 좋아요.
3청구 회차 (/subscription/ops/bill/cycle)
가입이 끝나면 실제 과금은 회차 단위로 관리돼요. 여기서 중요한 것은 계약 전체 상태와 각 회차 상태를 구분하는 것이에요.
핵심 문서:
이 단계에서 정할 내용:
- 회차 성공과 실패를 어떤 웹훅으로 동기화할 것인가
- 결제 실패 시 재시도 정책을 어떻게 가져갈 것인가
- 회차별 금액 변경이 필요한가
회차 문서를 읽을 때는 계약이 살아 있는가와 이번 회차가 성공했는가를 분리해서 봐야 해요.
4조정 (/subscription/ops/adjust/plan)
운영하다 보면 구독은 거의 항상 변해요. 업그레이드·다운그레이드, 회차 금액 조정(설치비·할인·추가 요금) 같은 변경이 필요해요.
핵심 문서:
이 단계에서 정할 내용:
- 다음 회차부터 반영할지 즉시 반영할지
- 추가 요금을 어떤 이름으로 관리할지
- 조정 이력을 운영자가 추적할 수 있는지
조정은 계약 상태를 바꾸기보다 청구 규칙을 바꾸는 작업에 가까워요.
5관리 (/subscription/ops/manage)
마지막은 운영 단계예요. 신규 승인으로 계약을 켜거나, 거절로 시작 전에 막거나, 일시정지·재개·해지를 처리해요.
핵심 문서:
이 단계에서 정할 내용:
- 해지와 거절을 어떤 정책으로 구분할 것인가 (진행 중 종료 vs 승인 전 반려)
- 고객 자의 정지와 관리자 강제 중단을 어떻게 분리할 것인가
- 승인·거절 권한을 어디까지 자동화할 것인가
운영 단계는 가입 단계와 용어가 닮아 보이지만 전혀 다른 책임을 가져요. 그래서 activate와 block 문서를 별도로 두는 구조가 중요해요.
다음 읽기 순서
- 구독 용어 사전으로 단계 이름을 먼저 맞춰요.
- 계약 조회에서 상품 규칙을 고정해요.
- 가입 시작과 가입 승인을 붙여요.
- 회차 조회와 계약 내용 변경으로 운영 중간 흐름을 붙여요.
- 신규 승인과 해지로 종료 단계까지 닫아요.
이 순서를 그대로 따라가면 구독 문서를 API 목록이 아니라 실제 라이프사이클 문서로 읽게 돼요.