42 lines
3.9 KiB
YAML
42 lines
3.9 KiB
YAML
report-header:
|
|
bottom-line: >
|
|
Pro 하이브리드(committed base + metered overage)를 Stripe Billing Meters로 구현한다 —
|
|
licensed 기본료 price와 meter 연결 metered price를 한 subscription의 두 item으로 묶고,
|
|
사용량은 결정론적 identifier를 붙인 Meter Event로 멱등 전송해 Stripe가 집계·티어링·정산하게 한다.
|
|
decision-needed: { needed: false }
|
|
confidence: { value: Med, derived-from: evidence }
|
|
risks:
|
|
- 멱등성/중복계량 - at-least-once 전송·재시도 시 identifier가 없거나 24h 롤링 윈도를 넘겨 재전송되면 이중 계량 → 결정론적 identifier(EVENT_NAME:customer:unit_key) 필수, 윈도 밖 재처리 금지.
|
|
- 정산 오차 - timestamp가 과거 35일/미래 5분 밖이면 이벤트가 거부되어 미청구 누락 발생, 클록 스큐·지연배치 주의. 앱측 추정치는 UX 전용이며 Stripe 집계가 원장.
|
|
- 파라미터 미확정 - value-metric(호출/크레딧/완료건수), 무료 allotment, 단위마진 하한 배수(overage 단가)가 CPO/CFO 미승인 상태라 price 재발행 시 마이그레이션 비용 발생 가능.
|
|
evidence:
|
|
- source-uri: _sandbox/evidence/probilling/stripe-usage-billing.md
|
|
grade: E3
|
|
note: >
|
|
공식 Stripe 문서 근거 — 개요 https://docs.stripe.com/billing/subscriptions/usage-based ,
|
|
Meter 생성 https://docs.stripe.com/api/billing/meter/create ,
|
|
Meter Event https://docs.stripe.com/api/billing/meter-event/create (+ v2 24h 멱등 윈도
|
|
https://docs.stripe.com/api/v2/billing/meter-events/object ),
|
|
Price(metered/tiered) https://docs.stripe.com/api/prices/create ,
|
|
Subscription https://docs.stripe.com/api/subscriptions/create . 인용일 2026-07-07.
|
|
- source-uri: _sandbox/evidence/probilling/metering_sample.py
|
|
grade: E3
|
|
note: 공식 API 시그니처 기반 실행가능 샘플(py_compile 통과). 테스트키로 --demo 프로비저닝 가능.
|
|
design:
|
|
api-flow:
|
|
- "1. Meter 생성: POST /v1/billing/meters (stripe.billing.Meter.create) — event_name=pro_api_call, default_aggregation.formula=sum, customer_mapping.type=by_id."
|
|
- "2. Price 생성: POST /v1/prices — (a) licensed 기본료 price(committed base), (b) metered price(recurring.usage_type=metered, recurring.meter=<meter id>, billing_scheme=tiered, tiers_mode=graduated: allotment까지 unit_amount=0, 초과분 overage 단가)."
|
|
- "3. 구독: POST /v1/subscriptions (stripe.Subscription.create) — items[]에 기본료 item(quantity=1) + metered item(quantity 없음). Idempotency-Key 헤더로 재시도 안전."
|
|
- "4. 계량: POST /v1/billing/meter_events (stripe.billing.MeterEvent.create) — event_name + payload{stripe_customer_id,value} + identifier(멱등)."
|
|
- "5. 정산: 청구주기 말에 Stripe가 meter event를 formula로 집계 → metered tier 적용 → 기본료와 합산해 단일 invoice 발행. overage=max(0, 집계량-allotment)*overage단가."
|
|
idempotency: >
|
|
Meter Event에 결정론적 `identifier`(예: sha256(EVENT_NAME:customer_id:unit_key))를 부여한다.
|
|
Stripe는 identifier를 롤링 24시간 윈도 내에서 유일성 강제하므로 동일 unit_key의 재전송·재시도는
|
|
이중 계량되지 않는다(공식 권고: 전역 유일 식별자 사용). timestamp는 과거 35일/미래 5분 이내만 허용.
|
|
쓰기 API(Meter/Price/Subscription create)는 `Idempotency-Key` 요청 헤더로 재시도 멱등 보장.
|
|
interface-for-consuming-teams: >
|
|
제품/프론트는 얇은 파사드 두 메서드만 호출한다 —
|
|
(1) MeteringClient.report(customer_id, value, unit_key): 사용 1건을 멱등 계량(Stripe API·identifier 은닉),
|
|
(2) MeteringClient.estimate(customer_id, aggregated_usage) -> UsageEstimate: 60/80/100% 인앱 넛지용
|
|
overage_units·estimated_invoice_total 추정치 반환(표시 전용, 원장은 Stripe). 팀은 Stripe SDK를 직접 다루지 않는다.
|