---
title: "구독 수명 주기 및 청구"
description: "구독 상태 전환, 청구 기간 및 갱신 계산, 결제 실패 처리 방식을 설명합니다."
source: "https://docs.tokenz.one/ko-KR/v2/subscriptions/lifecycle"
api_version: "v2"
locale: "ko-KR"
version_status: "current"
docs_stage: "prod"
---

# 구독 수명 주기 및 청구

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

## 상태

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

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

## 청구 기간

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

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

```mermaid
sequenceDiagram;
autonumber;
participant T as Tokenz;
participant PSP as 카드 네트워크 / PSP;
participant W as 판매자 웹훅 핸들러;
T->>T: 청구 기간의 갱신 주문 생성;
T->>PSP: 저장된 카드 청구;
alt 결제 성공
PSP-->>T: 승인됨;
T->>T: 다음 청구 기간으로 이동, active 유지;
T->>W: webhook: subscription.renewed;
else 결제 실패
PSP-->>T: 거절됨;
T->>T: 구독 unpaid 전환, 미납 재시도 시작;
T->>W: webhook: subscription.unpaid;
end
```

## 체험 기간

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

1. 고객이 카드를 제공하여 체험을 시작하고 Tokenz가 결제 네트워크에 동의를 등록합니다. [결제 수단 및 동의](https://docs.tokenz.one/ko-KR/v2/subscriptions/payment-methods)를 참고하세요.
2. `trialing`으로 전환되고 `subscription.trial_started` 웹훅이 전송됩니다.
3. `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` 상태에서 고객 대신 구독을 취소할 수 있습니다. 취소 시 다음이 적용됩니다.

- `canceledAt`을 설정하고 이후 갱신 주문 생성을 중단합니다.
- 결제 대기 주문 등 진행 중인 구독 주문을 취소합니다.
- `subscription.canceled` 웹훅을 전송합니다.

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

## 갱신 알림

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