Skip to Content
개발자REST APISubscriptions

Subscriptions

구독(Subscription)은 월/연 정기결제예요.
목록·단건 조회와 해지를 다룰 수 있어요.
구독 생성은 API로 직접 하지 않아요 — 구매자가 결제 링크나 Checkout Session의 결제창에서 플랜을 선택해 첫 결제를 하면 만들어져요.

구독 목록

GEThttps://api.payri.kr/v1/subscriptionsscope subscriptions:read
curl "https://api.payri.kr/v1/subscriptions?page=1&limit=20" \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

페이지네이션 형식으로 응답해요.
키가 특정 상품으로 제한돼 있으면 해당 상품의 구독만 담겨요.

구독 단건

GEThttps://api.payri.kr/v1/subscriptions/:idscope subscriptions:read
curl https://api.payri.kr/v1/subscriptions/sub_77a \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxx"
{
  "id": "sub_77a",
  "productId": "prod_88x",
  "productName": "MeetNote Solo",
  "buyerName": "김구매",
  "buyerEmail": "buyer@example.com",
  "planId": "plan_solo",
  "billingInterval": "monthly",
  "status": "active",
  "currentPeriodStart": "2026-06-01T00:00:00.000Z",
  "currentPeriodEnd": "2026-07-01T00:00:00.000Z",
  "startedAt": "2026-04-01T00:00:00.000Z",
  "refundEligibleUntil": "2026-06-08T00:00:00.000Z",
  "hasBillingKey": true
}

주요 필드

필드타입설명
statusenumactive · past_due · canceled · ended · refunded
billingIntervalenummonthly · yearly
currentPeriodEndISO현재 결제 주기 종료 시각
refundEligibleUntilISO환불 보장 기한 (첫 결제 후 7일). 이 전에 해지하면 전액 환불
scheduledChangeobject예약된 변경(해지·플랜 전환). 있을 때만
hasBillingKeyboolean자동 청구 가능 여부 (빌링키 보유)

구독 해지

POSThttps://api.payri.kr/v1/subscriptions/cancelscope subscriptions:write
curl -X POST https://api.payri.kr/v1/subscriptions/cancel \
  -H "X-Api-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "subscriptionId": "sub_77a", "reason": "고객 요청" }'
필드타입필수설명
subscriptionIdstring✅해지할 구독 ID
reasonstring—해지 사유

해지는 호출 시점에 따라 두 방식으로 처리돼요.

시점처리
refundEligibleUntil 이전첫 결제를 전액 환불하고 구독을 즉시 종료해요. status가 refunded로 바뀌어요
refundEligibleUntil 이후현재 주기 종료 시점으로 해지를 예약해요. status가 canceled로 바뀌고, 주기 종료까지는 구독이 유지돼요

응답

갱신된 구독이 subscription에 담겨 와요.
즉시 환불로 처리된 경우엔 환불된 주문 ID가 refundOrderId로 함께 와요.

{
  "subscription": {
    "id": "sub_77a",
    "status": "canceled",
    "currentPeriodEnd": "2026-07-01T00:00:00.000Z",
    "scheduledChange": { "type": "cancel", "effectiveAt": "2026-07-01T00:00:00.000Z" }
  }
}

환불 보장 기간 안의 해지는 환불을 함께 일으키므로 order.refunded 웹훅이 전송돼요.
예약 해지를 되돌리는 재개(resume)는 셀러 콘솔에서만 할 수 있어요.

관련 에러

코드HTTP상황
SUBSCRIPTION_NOT_FOUND404구독이 없거나 키의 상품 범위 밖
ALREADY_CANCELED409이미 해지가 예약된 구독
ALREADY_ENDED409이미 종료·환불된 구독
Last updated on
ProductsLicenses