구독 수명 주기 및 청구

구독 상태 전환, 청구 기간 및 갱신 계산, 결제 실패 처리 방식을 설명합니다.

상태

필요하면 좌우로 스크롤하세요

상태	의미
`created`	구독이 생성되었지만 고객이 아직 결제 수단 등록과 정기 청구 동의를 완료하지 않았습니다.
`trialing`	체험 기간 중이며 아직 요금이 청구되지 않았습니다.
`active`	정상 청구 중입니다. 매 청구 기간 종료 시 새 주문이 자동 생성·청구됩니다.
`unpaid`	현재 기간 주문 결제에 실패했습니다. 재시도 중이며 `active`로 복구되거나 `expired`로 종료됩니다.
`canceled`	판매자가 고객 대신 취소했습니다. 최종 상태이며 더 이상 청구되지 않습니다.
`expired`	초기 결제 실패 또는 재시도 소진으로 대금을 받지 못해 종료되었습니다. 최종 상태이며 더 이상 청구되지 않습니다.

canceled와 expired는 모두 최종 상태지만 의미가 다릅니다. 전자는 고객을 대신한 의도적 취소, 후자는 결제 실패입니다. 자체 이탈 분석에서도 구분하세요.

모든 활성 구독에는 currentBillingPeriodEnd가 있고, 체험 구독에는 trialEnd도 있습니다.

주기: unit(WEEK, MONTH, YEAR)과 count(갱신 간 단위 수) 객체입니다. 월·년 단위 청구 기간은 청구 기준일(첫 결제 성공일)과 같은 일자를 기준으로 갱신됩니다. 대상 월에 해당 일자가 없으면 말일을 사용합니다(예: 31일 기준이면 짧은 달에는 30일 또는 28·29일).
갱신: 현재 청구 기간 종료 시 Tokenz가 관리합니다.

다이어그램

생성 시 trialPeriodDays(1~365)를 지정하면 Checkout에서 초기 주문을 생성하지 않습니다. 대신 다음과 같이 진행됩니다.

고객이 카드를 제공하여 체험을 시작하고 Tokenz가 결제 네트워크에 동의를 등록합니다. 결제 수단 및 동의를 참고하세요.
trialing으로 전환되고 subscription.trial_started 웹훅이 전송됩니다.
trialEnd에 도달하면 주문을 생성하고 저장된 카드로 청구합니다. 성공하면 active로 전환되고 subscription.activated가 전송됩니다.

체험이 없으면 Checkout 시 초기 주문을 생성·청구하며 결제 승인 성공 즉시 active가 됩니다.

각 구독은 예약 청구 실패 시 동작을 결정하는 전략을 가집니다.

RETRY (기본): 미납 주문을 dunningMaxAttempts회(기본 3)까지 재시도하며, 주문 만료 기간(dunningExpireAfterHours, 기본 24시간)까지 간격을 두고 진행합니다. 고객에게 카드 업데이트가 가능한 복구 결제 링크도 이메일로 보냅니다. 재시도 성공 시 active로 돌아가고, 모두 실패하여 주문이 만료되면 expired가 됩니다.
CANCEL_IMMEDIATELY: 첫 청구 실패 즉시 구독이 만료되며 재시도 기간이 없습니다.

필요하면 좌우로 스크롤하세요

필드	설명
`dunningMode`	`RETRY` 또는 `CANCEL_IMMEDIATELY`. 기본은 `RETRY`입니다.
`dunningMaxAttempts`	`RETRY`일 때 최대 재시도 횟수. 1~10, 기본 3.
`dunningExpireAfterHours`	`RETRY`일 때 미납 주문 만료까지의 시간. 1~168, 기본 24.

참고: unpaid에서 active로 복구되어도 원래 청구 기간은 바뀌지 않습니다. 다음 갱신은 복구일이 아닌 원래 기준일에 따라 예약됩니다.

판매자는 trialing, active, unpaid 상태에서 고객 대신 구독을 취소할 수 있습니다. 취소 시 다음이 적용됩니다.

취소는 최종적이며 현재 재개할 방법이 없습니다. 다시 사용하려면 새 구독을 시작해야 합니다.

일부 지역은 체험의 유료 전환이나 연간 갱신 등 특정 청구 전 사전 고지를 요구합니다. 필요한 경우 Tokenz가 자동 전송합니다.