credit-system
AI 사용량 과금 — 크레딧 모델, idempotent UsageRecord, 한도·auto-refill, LLM 원가+마진 가격, Free Tier, immutable ledger 환불. Use when 토큰·API 호출 단위 종량제나 충전식 크레딧을 설계할 때.
SKILL.mdplugins/saas/skills/credit-system/SKILL.md
GitHubCredit System — AI/사용량 모네타이징
LLM 토큰·API 호출·연산 시간 등 사용량 단위로 과금하는 비즈니스 패턴. subscription-billing-flows.md §5 Metered Billing의 자연 연장이며, AI 제품에서는 정액 seat + per-token usage hybrid가 디폴트.
이 skill은 사용량 모네타이징 전용 hub. Stripe Subscription 자체는
subscription-billing.md참조. 일회성 결제는payment-integration.md. 이 문서는 잔액·차감·임계치·LLM 원가 추적의 도메인 모델과 함정에 집중.
When to Use
- AI 제품 (LLM 챗봇, 코드 어시스턴트, 이미지 생성 등) 모네타이징 설계
- API 제품 (요청/GB/CPU초 단위) 가격 모델 설계
- "월정액으로 가? 충전식으로 가? 둘 다?" 의사결정
- LLM provider 원가 변동을 사용자 가격에 어떻게 반영할지
- 무료 tier(예: 월 100만 토큰)와 유료 한도 정책 설계
- AI 호출 폭증으로 한 사용자가 월 $1,000 청구되는 사고 예방
관련 skill (cross-link):
business/subscription-billing.md— 메인 hub, 정기 빌링 인프라 (seat 부분)business/subscription-billing-flows.md§5 — Metered Billing 패턴 (idempotency/late events 원칙)business/subscription-billing-metrics.md— MRR/Cohort SQL 패턴 → usage 메트릭으로 확장business/payment-integration.md— 충전 결제 (one-time topup)business/rate-limiting.md— 토큰/RPS hard cap, threshold 결합business/notification-multichannel.md— low balance / cap 도달 알림business/audit-log.md— usage_event 감사, refund/조정 기록business/multi-tenancy.md— tenant 단위 잔액, seat × usage 결합ai/prompt-engineering.md,ai/rag-patterns.md— 토큰 효율 (원가 절감)
관련 agent: tech-lead (가격 모델 ADR), cost-analyzer (LLM provider 원가 추적)
관련 skill: /infra:postgresql-operations (ledger 파티셔닝/아카이빙), /messaging:broker-troubleshooting (usage 이벤트 큐), /infra:redis-operations (잔액 캐시)
1. 모델 결정 매트릭스
| 모델 | 적합 | 사용자 멘탈 모델 | 함정 |
|---|---|---|---|
| Prepaid Credit (충전식) | API 제품, 변동성 큰 사용량 | "지갑에 잔액" — 친숙 | 미사용 잔액 환불/만료 정책, 회계 처리(deferred revenue) |
| Postpaid Metered | 엔터프라이즈, 신뢰관계 있는 B2B | "월말 청구서" | 미수금/dunning, 사용 폭증 시 충격 청구 |
| Hybrid: Seat + Usage | AI 제품 표준 (Cursor/v0/ChatGPT Pro) | "월 $20 + 한도 초과 시 충전" | seat 가격에 usage 어디까지 포함할지 |
| Pay-as-you-go (no commit) | Indie/playground 제품 | "쓴 만큼만" | 사용자 1명이 무한 사용 → 청구 폭탄 → 환불 분쟁 |
| Tiered with Hard Cap | B2C, 청구 폭탄 회피 | "정액 + 초과 시 차단" | 비즈니스 critical 호출도 차단되는 UX |
| Tiered with Soft Overage | B2B, 매출 우선 | "정액 + 초과 시 자동 청구" | 사용자 사전 동의 + 경고 흐름 필수 |
2026 트렌드 (AI 제품 디폴트):
- **Hybrid (월 seat + per-token credit)**가 사실상 표준. ChatGPT Pro($20+사용량), Cursor($20 monthly+overage), v0(seat+credit), Anthropic Console(prepaid).
- Hard cap 기본 ON + 사용자 명시적 opt-in으로 soft overage 활성화가 신뢰 표준 (청구 폭탄 사고 방지).
- Auto-refill + Spend limit는 짝패. refill 없이 limit만 두면 운영 중단, limit 없이 refill만 두면 청구 폭탄.
모델 추상화 — subscription-billing.md SubscriptionGateway 연장
CreditGateway (interface) # subscription-billing의 SubscriptionGateway와 짝
├─ create_account(tenant) → CreditAccountId
├─ topup(account, amount, currency, idempotency_key) → TxId # 충전
├─ debit(account, units, meter, metadata, idempotency_key) → TxId # 차감
├─ get_balance(account) → Balance{available, reserved, committed}
├─ set_threshold(account, level, action: notify|block|refill)
└─ refund(tx_id, reason) → TxId # 보상 트랜잭션
Adapters:
├─ StripeMetersAdapter # postpaid usage → Stripe Subscription에 합산
├─ InternalLedgerAdapter # prepaid 자체 ledger (PostgreSQL)
└─ LagoAdapter # open-source metered billing 위임
원칙: 도메인 코드는 CreditGateway만 의존. Stripe Meters / 자체 ledger / Lago 어느 쪽이든 어댑터로 격리. subscription-billing.md Pattern과 동일.
2. 도메인 모델 (필수)
CreditAccount (1) ── (1) Tenant 또는 (1) Customer
├─ id
├─ tenant_id (multi-tenancy 결합)
├─ currency (USD/KRW/EUR — currency lock)
├─ balance_available (즉시 사용 가능 = 충전 - 차감 - 예약)
├─ balance_reserved (진행 중 요청 hold)
├─ free_tier_remaining (월간 무료 잔량, 매월 reset)
├─ low_balance_threshold (알림 임계치)
├─ auto_refill_enabled / auto_refill_amount / auto_refill_trigger
├─ spend_limit_monthly (hard cap, 사용자 설정)
└─ status: active|frozen|closed
CreditLedgerEntry (immutable, append-only)
├─ id, account_id, occurred_at
├─ entry_type: topup|debit|refund|adjustment|free_tier_grant|expiration
├─ amount (양수: 입금, 음수: 출금)
├─ balance_after (스냅샷, 빠른 조회용. 주기적 재계산으로 검증)
├─ idempotency_key (UNIQUE)
├─ source_event_id (UsageEvent.id 또는 invoice.id)
├─ metadata (JSONB) (model, prompt_tokens, completion_tokens, ...)
└─ provider (stripe|internal|lago)
UsageEvent (raw, billing 전 단계)
├─ id (UUID), tenant_id, account_id
├─ meter (llm_tokens|api_calls|gb_storage|...)
├─ quantity (예: 12500 tokens)
├─ occurred_at, recorded_at (late event 식별)
├─ idempotency_key (UNIQUE — 같은 요청 재시도 시 1회만)
├─ unit_cost (이 요청 시점의 unit price snapshot)
├─ metadata (JSONB) (request_id, model, prompt/completion 분리, latency)
└─ status: pending|priced|debited|voided
PriceBook (시간 가변, immutable version)
├─ id, effective_at
├─ meter, model (예: meter=llm_tokens, model=claude-opus-5-5)
├─ unit (1000 tokens / 1 image / 1 GB-month)
├─ unit_amount, currency (예: USD 0.02 — Opus 5.5 output, 2026-11 공시가)
├─ markup_percent (provider 원가 대비 마진)
└─ cost_basis_amount (provider 원가, 회계용)
핵심 원칙:
- Ledger는 immutable + append-only: 잔액은 계산값 (sum). 직접 update 절대 금지. 오류 → adjustment entry 추가.
- balance_available은 캐시: source of truth는
SUM(amount) FROM ledger WHERE account_id=.... 정기 reconciliation으로 검증. - PriceBook = PlanVersion 패턴 재사용: provider 원가 변동, 자체 마진 변경, 환율 변동을 시간축에 immutable 로 기록. UsageEvent에는 그 시점 unit_cost를 snapshot으로 저장 (소급 계산 금지).
- idempotency_key는 두 곳에: UsageEvent 발생 시(중복 기록 차단) + LedgerEntry 차감 시(중복 차감 차단). 둘은 다른 키.
- late event 처리 정책 ADR: occurred_at < 현재 주기 시작 시점인 이벤트가 도착하면 어떻게? (다음 주기 / 거절 / 강제 차감).
subscription-billing-flows.md§5와 동일 함정. tenant_id일찍 결정한다:multi-tenancy.md결합 — 잔액은 tenant 단위가 보통.
3. 사용량 트래킹 — Idempotent UsageRecord (의사코드)
LLM 호출은 네트워크 실패/재시도가 흔하다. 같은 호출이 두 번 차감되면 사용자 신뢰 즉사.
# 사용 시점에 호출. 동기 차감 또는 큐 위임 모두 idempotency 동일 적용.
def record_usage(
account_id: str,
meter: str, # "llm_tokens"
quantity: int, # 12500
request_id: str, # 상위 요청 ID — idempotency 기반
model: str, # "claude-opus-5-5"
metadata: dict,
):
idem_key = f"usage:{request_id}:{meter}" # 한 요청 = 한 차감
with db.transaction():
# 1. UsageEvent 중복 차단 (UNIQUE 제약 + INSERT ... ON CONFLICT DO NOTHING)
event = UsageEvent.insert_or_get(
idempotency_key=idem_key,
account_id=account_id,
meter=meter, quantity=quantity,
occurred_at=now(), recorded_at=now(),
metadata={"model": model, **metadata},
status="pending",
)
if event.status != "pending":
return event # 이미 처리됨, 즉시 반환
# 2. PriceBook에서 그 시점 단가 snapshot (소급 변경 X)
price = PriceBook.lookup(meter=meter, model=model, at=event.occurred_at)
cost = round_currency(quantity * price.unit_amount / price.unit, price.currency)
event.unit_cost = price.unit_amount
event.status = "priced"
# 3. Free tier 우선 차감 → 부족분만 유료 잔액 차감
free_used = min(quantity, account.free_tier_remaining)
paid_units = quantity - free_used
paid_cost = round_currency(paid_units * price.unit_amount / price.unit, price.currency)
if paid_cost > account.balance_available:
event.status = "voided"
raise InsufficientBalance(account_id, paid_cost, account.balance_available)
# 4. Ledger에 immutable entry 2개 (free_tier_grant 차감 + paid debit)
if free_used > 0:
Ledger.append(account_id, type="free_tier_grant", amount=0, # 금액 0, 카운터만
metadata={"free_units_consumed": free_used},
idempotency_key=f"ft:{idem_key}")
account.free_tier_remaining -= free_used
Ledger.append(account_id, type="debit", amount=-paid_cost,
source_event_id=event.id,
idempotency_key=f"debit:{idem_key}",
metadata={"meter": meter, "quantity": paid_units, "unit_cost": price.unit_amount})
# 5. 캐시 잔액 업데이트 + 차후 reconcile 잡으로 검증
account.balance_available -= paid_cost
event.status = "debited"
# 6. Threshold 평가 (트랜잭션 밖 — 알림 실패가 차감 롤백시키지 않게)
evaluate_thresholds(account_id)
return event
핵심 포인트:
idem_key는 상위 request_id 기반. retry는 같은 키, 새 요청은 다른 키.INSERT ... ON CONFLICT DO NOTHING또는SELECT ... FOR UPDATE패턴으로 race 차단.PriceBook.lookup(at=event.occurred_at)은 그 시점 가격 고정 — provider가 다음 날 가격 인하해도 어제 호출은 어제 가격.- 잔액 부족 시
voided로 표시. 이미 호출된 LLM 응답은 사용자에게 어떻게 처리할지 비즈니스 결정 (환불/할인 표시/그냥 보여주기). - 알림은 트랜잭션 밖 — 알림 실패로 차감이 롤백되면 안 됨 (
audit-log.mdoutbox 패턴 권장).
Reservation 패턴 (선택)
긴 작업 (예: 1분짜리 video gen)은 시작 시 예상 비용 reserve → 완료 시 실제 차감 + 잔여분 release.
estimate(request) → estimated_cost
reserve(account, estimated_cost) → reservation_id # balance_reserved 증가
... 작업 진행 ...
on_completion(actual_cost):
debit(account, actual_cost, idempotency_key=f"res:{reservation_id}")
release(reservation_id) # balance_reserved 감소
on_failure:
release(reservation_id) # 차감 없이 풀어줌
→ 짧은 호출(LLM completion 수 초)은 reservation 생략, 폭주 worker만 적용.
4. 한도 관리 — Threshold + Auto-refill (의사코드)
청구 폭탄 vs 운영 중단의 균형. Hard cap + 명시적 opt-in soft overage가 표준.
# Threshold 평가 — 차감 직후 또는 주기적 (5분 간격) 호출
def evaluate_thresholds(account_id: str):
account = CreditAccount.get(account_id)
balance = account.balance_available
# 1. Low balance 알림 (예: 잔액 < $10)
if balance < account.low_balance_threshold:
if not already_notified_today(account_id, "low_balance"):
notify(account, "low_balance", balance=balance) # notification-multichannel
mark_notified(account_id, "low_balance")
# 2. Auto-refill (idempotency_key로 동시 충전 차단)
if account.auto_refill_enabled and balance < account.auto_refill_trigger:
refill_key = f"autorefill:{account_id}:{date_hour()}" # 시간당 1회
if redis.set(refill_key, "1", nx=True, ex=3600):
charge_payment_method(account, account.auto_refill_amount) # PG 결제
# 결제 webhook → Ledger에 topup entry → balance 증가
# 3. Hard cap 도달 (월간 spend_limit)
monthly_spent = sum_debits(account_id, since=start_of_month())
if monthly_spent >= account.spend_limit_monthly:
account.status = "frozen"
notify(account, "spend_limit_reached")
# 이후 record_usage()에서 InsufficientBalance 또는 SpendLimitExceeded 발생
원칙:
- 알림 dedup: 같은 임계치 알림을 일/주 단위로 1회만 (피로도 방지).
- Auto-refill idempotency:
autorefill:{account}:{시간단위}키로 동시 충전/중복 충전 차단. - Hard cap은 hard: spend_limit 도달 시 frozen — 비즈니스 critical이라도 차단. 풀려면 사용자 명시적 액션. (수동 해제 후 도메인 액션 다시 가능).
- Soft overage는 별도 ADR: spend_limit + 명시적 opt-in (
overage_allowed=true). UI에 "초과 사용 시 자동 청구" 약관 동의 필수. - Webhook delay 고려: PG 충전 결제 → webhook → Ledger topup 사이 갭. UX는 "충전 진행 중" 상태 명시 + 일시 사용 가능 옵션 ADR.
→ rate limit과 차이: rate-limiting은 RPS 한도 (초당 요청), credit cap은 누적 비용 한도. 둘 다 필요하면 결합 (business/rate-limiting.md).
5. 가격 책정 — LLM Provider 원가 + 마진
LLM 사용량 가격 = provider 원가 + 마진(markup). provider 가격이 빠르게 변하므로 시간축 분리 필수.
| 항목 | 자체 결정 | 함정 |
|---|---|---|
| Cost basis (provider 원가) | OpenAI/Anthropic/Google 공시 단가 + cache hit 할인 + batch API 할인 | input/output 단가 다름. cache hit ratio가 평균 원가 좌우. |
| Markup % | 보통 30~200% (prompt 가공 + 인프라 + 마진) | 너무 낮으면 운영 적자, 너무 높으면 사용자가 직접 OpenAI 가입 |
| 표시 단위 | 사용자 친화 단위 ("크레딧" / "토큰") | provider raw 토큰을 그대로 노출하면 모델 변경 시 사용자 혼란 |
| 모델별 가격 | Opus = Sonnet × 2, Haiku = Sonnet ÷ 20 등 비례 (Claude 5.5 공시가, 2026-11 기준) | 모델 라우팅(downgrade) 시 사용자 경험 통일 |
| Cache hit 처리 | 할인 (예: Opus·Sonnet 5.5 95%, Haiku 5.5 90% 절감) 사용자에게 일부 환급 / 자체 마진 흡수 | 회계 분리 (cost_basis 기록) 필수 |
| Batch API 할인 | 50% 할인 (Anthropic/OpenAI batch). 사용자가 비동기 동의 시 적용 | UX: 동기/배치 옵션 명시 |
Multi-currency / 통화별 토큰 가격 ADR
subscription-billing-flows.md §4 Multi-currency 패턴 재사용:
| 패턴 | 권장 | 이유 |
|---|---|---|
| 통화별 PriceBook 분리 | ✅ 권장 | USD/KRW/EUR 별 unit_amount. 환율 자동 변환 X |
| 단일 USD base + 결제 시 FX | ⚠️ 비추 | 환율 변동으로 잔액 차감액이 매일 다름, 사용자 혼란 |
| CreditAccount currency lock | ✅ 필수 | 첫 충전 시 통화 고정. 변경 = 새 account |
| 반올림 정책 | ✅ 필수 | KRW=정수, USD=4 decimal(소액 차감) — provider raw 단가가 $0.000015/token 단위라 이슈 |
| provider 원가 USD → 사용자 KRW 가격 | 분기 환율 + 마진으로 고정 | 매월 재산정 X (사용자 가격 안정성) |
## 통화/단가 ADR
| 항목 | 결정 | 근거 |
|---|---|---|
| 사용자 표시 단위 | 크레딧 (1 credit = $0.001 또는 ₩1) | 모델 변경 시 사용자 가격 안정 |
| 통화 | USD primary + KRW (한국 customer) | 한국은 카드 외화 결제 거부감 |
| Markup | input 50%, output 80%, cache hit 30% | 평균 cost ratio 기반 |
| 환율 갱신 | 분기 1회 수동 + 변동 5% 초과 시 임시 갱신 | 회계 안정성 |
| 모델 라우팅 시 가격 | 라우팅된 실제 모델 단가 적용 | 사용자에게 명시 (logs) |
6. Free Tier — 차감 정책
| 패턴 | 적합 | 함정 |
|---|---|---|
| 월간 reset (예: 매월 1일 100만 토큰 grant) | B2C 표준 | 월말 무료 폭주 → 인프라 부담 |
| Rolling 30일 | 신규 사용자 균등 | 회계 복잡 |
| 계정당 1회 (전 평생) | 트라이얼 대용 | 어뷰즈 (멀티계정), 가입 매력 ↓ |
| Subscription 포함분 | Hybrid 모델 (월 $20에 100만 토큰 포함) | 잔여 carry-over 정책 ADR |
핵심:
- 차감 우선순위: free_tier → prepaid balance → overage(있으면)
- Free tier 잔량은 별도 카운터 (
free_tier_remaining). 매월 reset cron + audit-log. subscription-billing-flows.md§6 Trial 어뷰즈 방지 패턴 그대로 적용 (도메인/카드 fingerprint/rate-limit).
7. Refund / 조정 (immutable ledger 준수)
실패한 LLM 호출 (provider error, timeout)
▼
원본 debit entry 식별
▼
Ledger에 type=refund (양수 amount) entry 추가
▼
audit-log + 사용자 알림
원칙:
- 원본 entry 수정 금지 — 보상 entry 추가만 허용 (이중부기).
- 부분 환불: 응답 일부만 받았다면 quantity 재산정 → 부분 refund.
- 자동 환불 룰 ADR 필수: provider 5xx → 자동 100% / 4xx → 자동 0% / timeout → 50% 등.
- 회계 시스템 매핑: refund entry는 deferred revenue 감소. 충전된 적 없는 free_tier는 refund 대상 X.
8. 한국 시장 깊이 (충전식 캐시 모델)
한국 사용자는 "충전식 캐시" 멘탈 모델 친숙 (네이버페이 포인트, 카카오 캐시).
| 항목 | 한국 특수성 |
|---|---|
| 충전 PG | PortOne / Toss로 일회성 결제 (subscription 빌링키와 별도) |
| 부가세 | 충전 시점에 10% 부가세 별도 표시 + 세금계산서 발급 (B2B). B2C는 카드 영수증. |
| 환불 정책 | 전자상거래법: 미사용 잔액 환불 의무 (수수료 차감 가능). 정책 명시 필수. |
| 사용 기한 | 충전금 사용 기한 두는 게 일반적 (예: 1년). 만료 정책 ADR + 알림 필수. |
| 이용약관 | "충전금은 환불 불가" 조항 무효 가능성 (소비자 보호). 변호사 검토 필수. |
| 회계 처리 | 충전 시점 = deferred revenue (부채), 사용 시점 = 매출 인식. 한국 K-IFRS와 매핑. |
| 결제 수단 | 카드/계좌이체/간편결제 (네이버페이/카카오페이/페이코). 가상계좌(무통장 입금)는 B2B 흔함. |
| 현금영수증 | 10만 원 미만 자동 / 이상은 의무 발행 (B2C). PG가 처리하지 않으면 자체 처리. |
한국 LLM 시장 함정:
- 국내 LLM provider (네이버 HyperCLOVA, 카카오 KoGPT, KT Mi:dm 등) 등장. multi-provider 추상화 (
ai/카테고리) 필요. - 데이터 주권: B2B 엔터프라이즈는 "데이터 국외 반출 금지" 요구 — 한국 리전/한국 LLM 라우팅 별도 ADR.
- 세금계산서 자동 발행: Bill36524 / 더존 / 자체 ERP 연동. 충전 마다 발행 (월간 합산 X) — 한국 회계 관행.
→ 한국 단일 시장이면 이 § 그대로. 글로벌+한국 듀얼이면 currency lock + 부가세 자동화(subscription-billing-flows.md §4) 결합.
9. 보안 / 안티패턴
- ❌ 클라이언트가 사용량 self-report: 위변조 즉시. 항상 서버 측 record (LLM proxy/gateway에서).
- ❌ 잔액을 클라이언트에서 캐시: 차감 race로 사용자가 음수 잔액으로 호출.
- ❌ balance를 SELECT FOR UPDATE 없이 차감: race로 이중 차감 / 음수 잔액. 트랜잭션 + 잠금 또는 atomic decrement (Redis) 필수.
- ❌ PriceBook 변경 시 기존 UsageEvent 소급 재계산: 사용자 신뢰 파괴. 그 시점 단가 snapshot 고정 원칙.
- ❌ 알림 실패가 차감 롤백시키게: outbox 패턴 (
audit-log.md)으로 분리. - ❌ Hard cap 없이 PG에 자동 청구: 청구 폭탄 사고. spend_limit 기본값 + soft overage opt-in.
- ❌ 무료 tier도 PG customer 안 만듦: subscription-billing 동일 함정. 가입 시점에 customer + free CreditAccount 생성.
- ✅ 모든 debit/topup/refund에 idempotency_key: UNIQUE 제약 강제.
- ✅ Reconciliation job: ledger sum vs cached balance, provider 원가 vs 자체 cost_basis 일일 검증.
- ✅ provider rate limit 자체 sub-limit: provider quota 도달 전 자체 차단 (사용자에게 명확한 메시지).
안티패턴 모음
| 안티패턴 | 왜 위험 | 올바른 방법 |
|---|---|---|
| balance를 정수 컬럼 1개로 관리 | reconciliation 불가, 감사 불가 | append-only ledger + 캐시된 balance |
| free_tier를 balance에 직접 입금 | 환불/회계 분리 안 됨 | 별도 카운터 또는 separate ledger entry |
| usage_record 즉시 PG report | spike 시 PG rate limit | 배치/aggregator (Stripe Meters는 1초 1k+ 처리) |
| late event를 무조건 차감 | 마감된 주기 정합성 파괴 | 정책 ADR (다음 주기 / void / 특정 기간만 허용) |
| 환불을 원본 entry update로 처리 | 감사 추적 불가, 회계 위반 | 양수 amount의 refund entry append |
| spend_limit 기본 OFF | 청구 폭탄 사고 | 기본 ON + soft overage opt-in |
| 모델별 가격 매핑 누락 | 모델 라우팅 시 원가 폭증 | 모델별 PriceBook + 라우팅 시 단가 검증 |
10. ADR 템플릿 — Credit System
## Credit System ADR
| 항목 | 결정 | 대안 | 근거 |
|---|---|---|---|
| 모델 | Hybrid (월 seat $20 + per-token credit) | Pure prepaid / Pure metered | AI 제품 표준 |
| Credit 단위 | 1 credit = $0.001 (USD 표시) | raw token / 자체 단위 | 모델 라우팅 시 사용자 가격 안정 |
| Free tier | 월 100만 토큰 (매월 1일 reset, carry-over X) | rolling / lifetime | 어뷰즈 방지 + 마케팅 |
| Hard cap | 기본 $50/월, 사용자 변경 가능 | 무제한 / 고정 | 청구 폭탄 회피 |
| Soft overage | 사용자 명시적 opt-in | 기본 ON / 영구 OFF | 신뢰 + 매출 |
| Auto-refill | 잔액 < $5 시 $20 충전 (시간당 1회 한도) | 수동 / 무한 자동 | 운영 중단 회피 |
| Late event 정책 | occurred_at < 3일 전 = void, audit 기록 | 다음 주기 / 강제 차감 | reconciliation 단순 |
| Refund 정책 | provider 5xx = 자동 100% refund, 4xx = 0% | 모두 수동 / 모두 자동 | 운영 부담 균형 |
| Markup % | input 50%, output 80%, cache hit 30% | 단일 markup | provider 원가 구조 반영 |
| 환율 갱신 | 분기 1회 + 변동 5% 초과 시 임시 | 실시간 / 연 1회 | 회계 안정성 |
| Provider | 1차: Anthropic, 2차: OpenAI fallback | 단일 provider | 가용성 + 비용 |
| 한국 부가세 | 충전 시점 10% 별도, 세금계산서 자동 (B2B) | 사용 시점 / 수동 | 한국 관행 + 자동화 |
→ agents/tech-lead + agents/cost-analyzer 협업으로 ADR 작성.
11. Quick Start Checklist (신규 AI 제품)
- 모델 결정 (Hybrid/Prepaid/Postpaid) → ADR
- CreditAccount + Ledger + UsageEvent + PriceBook 4개 도메인 모델 구축 (immutable ledger)
- LLM gateway/proxy에서 record_usage 호출 (클라이언트 self-report 금지)
- idempotency_key 패턴:
usage:{request_id}:{meter},debit:{...},autorefill:{...} - PriceBook + cost_basis (provider 원가) + markup 분리
- Free tier 별도 카운터 + 매월 reset cron
- Hard cap 기본 ON + UI에서 사용자 조정 가능
- Soft overage opt-in 흐름 (약관 동의 + 명시적 액션)
- Auto-refill + low balance threshold 알림 (
notification-multichannel.md) - Reconciliation job: ledger sum vs cached balance, provider 원가 vs cost_basis 일일
-
audit-log통합: topup/debit/refund/threshold 모든 이벤트 - Hybrid 시
subscription-billing.mdseat 모델 결합 (월 seat → CreditAccount free tier grant) - 한국 시장: 부가세 + 세금계산서 + 환불 정책 ADR
- Stripe Meters 또는 자체 ledger 결정 → CreditGateway 어댑터
- 모니터링: 잔액 분포, MRR contribution from credit, provider 원가 추적
12. 관련 자원
같은 카테고리 (subscription-billing 시리즈와 짝):
business/subscription-billing.md— 정기 빌링 hub (seat 모델 결합 시)business/subscription-billing-flows.md§5 — Metered Billing 패턴 (이 skill의 부모 섹션)business/subscription-billing-metrics.md— MRR/Cohort SQL → usage MAU/ARPU/LTV로 확장
우리 시스템 내부 (cross-link):
business/payment-integration.md— 충전 일회성 결제, webhook idempotency 원칙business/multi-tenancy.md— tenant 단위 CreditAccount, seat × usage 결합business/rate-limiting.md— RPS hard cap (credit hard cap과 결합)business/notification-multichannel.md— low balance / cap / refund 알림business/audit-log.md— outbox 패턴, 잔액 변경 감사business/feature-flags.md— credit 기능 점진 롤아웃, kill-switchbusiness/admin-api-keys.md— usage report endpoint scopeskills/ai/prompt-engineering.md— 토큰 효율화 (원가 절감)skills/ai/rag-patterns.md— context 절약, cache hit 최대화skills/observability/observability-cost.md— provider 원가 추적, cardinality 주의 (account_id 라벨 회피)skills/messaging/redis-streams.md/kafka-*— usage event 큐agents/tech-lead— 가격 모델 ADR/infra:postgresql-operations— ledger 파티셔닝/아카이빙agents/cost-analyzer— provider 원가 추적 + markup 분석/infra:redis-operations— atomic decrement, 잔액 캐시rules/core/security.md,rules/process/documentation.md— ADR/회계 문서
외부 표준 / 도구:
- Stripe Meters + Events (2025+) — postpaid usage billing
- Lago / Killbill / Orb — open-source / 전용 metered billing
- Anthropic Console / OpenAI Platform — prepaid credit 표준 UX 참고
- ChartMogul / Sigma — usage metric 분석 (subscription metric과 결합)
- Bill36524 / 더존 — 한국 세금계산서
13. 다음 단계 (이 skill 적용 후)
- 정기 빌링 결합 (Hybrid) →
subscription-billing.md(seat 모델 + Stripe Meters 합산 invoice) - 메트릭 확장 →
subscription-billing-metrics.md패턴으로 MAU/ARPU/usage retention SQL 작성 - AI 비용 최적화 →
ai/prompt-engineering.md,ai/rag-patterns.md(cache hit 최대화로 원가 절감) - 장애 시 보상 →
/architecture:msa-saga(LLM 실패 → 자동 refund saga) - 엔터프라이즈 인보이스 → 충전식 → postpaid commitment + 월말 인보이스 (sales-led ADR)