Skip to Content
개발자REST APISubscriptions

Subscriptions

구독을 조회하고 해지 미리보기와 해지를 요청해요.

구독 목록

API 키의 test 또는 live 환경과 상품 범위에 속한 구독을 페이지 단위로 조회해요.

권한 subscriptions:read

쿼리 파라미터

pagenumber

조회할 페이지 번호예요.

제약 1 이상·예 1
limitnumber

페이지마다 조회할 항목 수예요.

제약 1~100·예 20
buyerEmailstring

구매자 이메일로 구독을 찾아요.

제약 이메일·예 buyer@example.com
statusstring

구독의 공개 상태로 결과를 좁혀요. 결제가 밀린 채 해지를 예약한 구독도 past_due 로 조회돼요.

허용 값 active, past_due, ended
productIdstring

상품 식별자로 구독을 좁혀요.

예 prod_123

응답

성공하면 HTTP 200과 구독 객체 목록을 돌려줘요.
형식은 { data, total, page, limit }예요.

오류

표에 없는 공통 오류(인증·권한, 호출 한도, 입력 검증, 서버 오류)는 에러 코드에서 확인해요.

구독 단건

구독의 공개 상태, 청구 기간과 예약 변경 정보를 조회해요.

권한 subscriptions:read

알아둘 점

  • 기간말 해지를 예약해도 status는 바뀌지 않고(active 또는 past_due) cancelAtPeriodEnd가 true가 돼요.

경로 파라미터

idstring필수

조회할 구독 식별자예요.

예 sub_123

응답

성공하면 HTTP 200과 구독 객체를 돌려줘요.

오류

코드HTTP의미
SUBSCRIPTION_NOT_FOUND404구독이 없거나 키의 상품 범위 밖이에요.

표에 없는 공통 오류(인증·권한, 호출 한도, 서버 오류)는 에러 코드에서 확인해요.

해지 미리보기

기간 종료 해지와 즉시 해지의 적용 시점과 환불 금액을 비교해요.

권한 subscriptions:read

경로 파라미터

idstring필수

미리보기할 구독 식별자예요.

예 sub_123

응답

성공하면 HTTP 200과 아래 필드를 돌려줘요.

immediateobject

즉시 해지 미리보기예요.

하위 필드 18개
blockedReasonobjectnull 가능

즉시 해지가 불가능한 이유예요.

하위 필드 2개
codestring

즉시 해지가 차단된 이유 코드예요.

허용 값 SUBSCRIPTION_REFUND_SETTLED, REFUND_REQUEST_PENDING, ALREADY_ENDED
messagestring

즉시 해지가 차단된 이유예요.

breakdownarray of object

주문별 환불 금액 내역이에요.

하위 필드 3개
amountnumber

해당 주문에서 환불할 금액이에요.

currencystring

금액 통화를 알려줘요.

허용 값 KRW
orderIdstring

환불 계산 대상 주문 식별자예요.

clawbacknumber

연간 할인 환수 금액이에요.

clawbackCurrencystring

환수 금액 통화예요.

허용 값 KRW
currencystring

금액 통화를 알려줘요.

허용 값 KRW
deductionnumber

환불액에서 차감할 금액이에요.

deductionCapnumber

차감할 수 있는 최대 금액이에요.

deductionCapCurrencystring

차감 한도 통화예요.

허용 값 KRW
deductionCurrencystring

차감 금액 통화예요.

허용 값 KRW
fullRefundboolean

전액 환불인지 알려줘요.

penaltynumber

위약금 금액이에요.

penaltyCurrencystring

위약금 통화예요.

허용 값 KRW
reasonstring

환불 계산 사유예요.

허용 값 initial_full, statutory_full, renewal_full, prorated, past_due, nothing_refundable
refundAmountnumber

즉시 해지 시 환불 예정 금액이에요.

requiresApprovalboolean

환불 요청의 판매자 승인이 필요한지 알려줘요.

statutoryboolean

법정 환불 기준 적용 여부예요.

totalDaysnumber

환불 계산에 사용하는 전체 일수예요.

usedDaysnumber

구독 시작 후 사용한 일수예요.

modestring

test 또는 live 구독 환경을 알려줘요.

허용 값 live, test
pendingRefundRequestobjectnull 가능

처리 중인 환불 요청 정보예요.

하위 필드 23개
approvedAmountnumbernull 가능

승인한 환불 금액을 원 단위로 알려줘요.

autoApproveAtstringnull 가능

요청 후 72시간 안에 결정되지 않으면 자동 승인되는 시각이에요.

breakdownobject

주문별 환불 금액 내역이에요.

하위 필드 1개
ordersarray of object

환불 대상 주문별 금액이에요.

하위 필드 3개
amountnumber

대상 주문의 환불 금액이에요.

currencystring

금액 통화를 알려줘요.

허용 값 KRW
orderIdstring

환불 대상 주문 식별자예요.

buyerEmailstring

구매자 이메일 주소예요.

buyerReasonstringnull 가능

구매자가 남긴 환불 사유예요.

createdAtstring

환불 요청이 생성된 시각이에요.

currencystring

금액 통화를 알려줘요.

허용 값 KRW
decidedAtstringnull 가능

요청이 결정된 시각이에요.

decidedBystringnull 가능

요청을 결정한 사용자 식별자예요.

holdobjectnull 가능

보류 처리 정보예요.

하위 필드 3개
heldAtstring

보류 처리 시각이에요.

reasonstringnull 가능

보류 사유예요.

typestring

보류 유형이에요.

허용 값 in_review, disputed
idstring

환불 요청 식별자예요.

kindstring

환불 요청 유형이에요.

허용 값 order, subscription_cancel
modestring

test 또는 live 환불 환경을 알려줘요.

허용 값 live, test
orderIdstring

환불 요청의 주문 식별자예요.

productIdstring

환불 요청의 상품 식별자예요.

rejectReasonstringnull 가능

거절 사유예요.

requestedAmountnumber

요청한 환불 금액을 원 단위로 알려줘요.

statusstring

환불 요청 상태예요.

허용 값 requested, on_hold, processing, approved, rejected, withdrawn
statutoryboolean

법정 청약 철회 요청인지 알려줘요.

subscriptionIdstringnull 가능

환불 요청의 구독 식별자예요.

updatedAtstring

환불 요청이 수정된 시각이에요.

warningsarray of object

환불 처리 전에 확인할 안내 목록이에요.

하위 필드 2개
codestring

환불 안내를 구분하는 코드예요.

허용 값 STATUTORY_LOCKED, SUBSCRIPTION_CANCEL_REFUND_RIGHT, POLICY_DECISION
messagestring

환불 처리 시 참고할 안내예요.

refundableAmountnumber

현재 환불 가능한 금액을 원 단위로 알려줘요.

periodEndobject

기간 종료 해지 미리보기예요.

하위 필드 1개
effectiveAtstring

기간 종료 해지 효력이 발생할 시각이에요.

오류

코드HTTP의미
SUBSCRIPTION_NOT_FOUND404구독이 없거나 키의 상품 범위 밖이에요.

표에 없는 공통 오류(인증·권한, 호출 한도, 서버 오류)는 에러 코드에서 확인해요.

구독 해지

기간 종료 시점 또는 즉시 해지해요.
timing은 필수예요.
Idempotency-Key는 24시간 보관해요.

권한 subscriptions:write·Idempotency-Key 헤더 필수

알아둘 점

  • period_end는 기간말 해지 예약, immediate는 즉시 종료예요.
  • 즉시 해지 환불액은 환불 정책으로 계산되고 금액은 지정할 수 없어요. 환불액이 있으면 환불된 주문마다 order.refunded가 온 뒤 subscription.ended가 와요.
  • immediate로 끝난 구독의 라이선스는 revoked가 돼요.

경로 파라미터

idstring필수

해지할 구독 식별자예요.

예 sub_123

헤더

Idempotency-Keystring필수

POST 요청의 중복 실행을 막는 키예요. 24시간 보관하며 본문이 다른 요청에는 같은 키를 쓸 수 없어요.

제약 1~255자

요청 본문

timingstring필수

기간 종료 시점 또는 즉시 해지 시점을 지정해요.

허용 값 period_end, immediate
reasonstring

해지 사유예요.

예 서비스 이용을 중단해요.

응답

성공하면 HTTP 201과 아래 필드를 돌려줘요.

currencystring

금액 통화를 알려줘요.

허용 값 KRW
refundAmountnumber

즉시 환불한 금액이에요.

refundOrderIdstringnull 가능

즉시 환불한 주문 식별자예요.

refundedOrderIdsarray of string

해지 처리 중 환불한 주문 식별자 목록이에요.

subscriptionobject

해지 후 구독 정보예요.

하위 필드 24개
amountnumber

갱신할 때 청구하는 주기당 금액의 상한을 원 단위 정수로 알려줘요. 상품 가격이 내려가면 다음 갱신부터 낮아지고, 인상은 고지 후 구매자가 동의해야 적용돼요.

billingIntervalstring

구독 결제 주기예요.

허용 값 monthly, yearly
buyerEmailstring

구매자 이메일 주소예요.

buyerNamestring

구매자 이름이에요.

cancelAtPeriodEndboolean

다음 기간 종료 시 해지하도록 예약했는지 알려줘요.

currencystring

금액 통화를 알려줘요.

허용 값 KRW
currentPeriodEndstring

현재 결제 기간 종료 시각이에요.

currentPeriodStartstring

현재 결제 기간 시작 시각이에요.

endReasonstringnull 가능

구독 종료 사유예요.

허용 값 canceled, refunded, payment_failed, product_unavailable, plan_unavailable, pg_canceled, price_increase_declined, null
endedAtstringnull 가능

구독이 종료된 시각이에요.

historyarray of objectnull 가능

구독 변경 이력이에요.

하위 필드 9개
atstring

변경이 기록된 시각이에요.

effectiveAtstringnull 가능

변경 효력이 발생하는 시각이에요.

extensionDaysnumbernull 가능

구독 기간 연장 일수예요.

fromobjectnull 가능

변경 전 플랜과 주기예요.

하위 필드 2개
billingIntervalstring

변경 전후 청구 주기예요.

허용 값 monthly, yearly
planIdstring

변경 전후 구독 플랜 식별자예요.

notestringnull 가능

이전 변경 기록의 메모예요.

orderIdstringnull 가능

변경과 연결된 주문 식별자예요.

prorationAmountnumbernull 가능

차액 결제 금액, 또는 갱신·가격 변경 이력의 금액을 원 단위로 알려줘요.

toobjectnull 가능

변경 후 플랜과 주기예요.

하위 필드 2개
billingIntervalstring

변경 전후 청구 주기예요.

허용 값 monthly, yearly
planIdstring

변경 전후 구독 플랜 식별자예요.

typestringnull 가능

내부 변경 기록 유형이에요.

허용 값 created, renewed, upgraded, downgrade_scheduled, downgrade_applied, interval_changed, cancel_scheduled, cancel_undone, ended, refunded, canceled_with_refund, comp_upgraded, period_extended, payment_failed, price_change_noticed, price_change_consented, null
idstring

구독 식별자예요.

modestring

test 또는 live 구독 환경을 알려줘요.

허용 값 live, test
pastDueSincestringnull 가능

결제 실패 상태가 시작된 시각이에요.

pendingPriceChangeobjectnull 가능

가격 인상 고지와 구매자 동의 상태예요.

하위 필드 5개
amountnumber

고지된 새 구독 금액을 원 단위로 알려줘요.

consentedAtstringnull 가능

구매자가 새 가격에 동의한 시각이에요.

currencystring

고지된 금액의 통화예요.

허용 값 KRW
effectiveFromstring

새 가격이 적용될 갱신일이에요.

noticedAtstring

가격 인상을 고지한 시각이에요.

planIdstring

구독 플랜 식별자예요.

productIdstring

상품 식별자예요.

productNamestring

상품 이름이에요.

refundEligibleUntilstring

최초 결제 환불 가능 기한이에요.

refundTermsobject

구독 환불 조건의 스냅샷이에요.

하위 필드 9개
dayRoundingstringnull 가능

일수 계산 방식이에요.

허용 값 ceil, floor, null
initialFullRefundDaysnumbernull 가능

최초 결제 전액 환불 가능 일수예요.

listAmountsobjectnull 가능

환불 계산에 사용하는 기준 금액이에요.

하위 필드 3개
currencystring

금액 통화를 알려줘요.

허용 값 KRW
monthlynumbernull 가능

월간 기준 금액이에요.

yearlynumbernull 가능

연간 기준 금액이에요.

penaltyobjectnull 가능

환불 위약금 조건이에요.

하위 필드 3개
currencystring

금액 통화를 알려줘요.

허용 값 KRW
fixedAmountnumbernull 가능

고정 위약금을 원 단위로 알려줘요.

rateBpsnumbernull 가능

위약금 비율을 1만분율로 알려줘요.

policyTypestringnull 가능

구독 환불 정책 유형이에요.

허용 값 no_refund, before_delivery, within_7days, custom, null
renewalFullRefundDaysnumbernull 가능

갱신 결제 전액 환불 가능 일수예요.

requireApprovalbooleannull 가능

환불 요청에 승인이 필요한지 알려줘요.

restrictRepeatFullRefundbooleannull 가능

반복 전액 환불 제한 여부예요.

yearlyDiscountClawbackbooleannull 가능

연간 할인 환수 여부예요.

scheduledChangeobjectnull 가능

예약된 구독 변경 정보예요.

하위 필드 4개
billingIntervalstringnull 가능

예약된 구독 청구 주기예요.

허용 값 monthly, yearly, null
effectiveAtstring

예약 변경 효력이 발생하는 시각이에요.

planIdstringnull 가능

예약된 구독 플랜 식별자예요.

typestring

예약 변경 유형이에요.

허용 값 downgrade, interval_change, cancel
startedAtstring

구독이 시작된 시각이에요.

statusstring

구독의 공개 상태예요. past_due 는 결제가 밀린 상태예요. 결제가 밀린 채 해지를 예약해도 past_due 이고 cancelAtPeriodEnd 가 true 예요.

허용 값 active, past_due, ended
testRenewalOutcomestringnull 가능

test 갱신 결과 설정이에요.

허용 값 succeed, fail, null
timingstring

해지 시점이에요.

허용 값 period_end, immediate

오류

코드HTTP의미
SUBSCRIPTION_NOT_FOUND404구독이 없거나 키의 상품 범위 밖이에요.
REFUND_REQUEST_PENDING409활성 환불 요청이 있어 주문을 환불할 수 없어요.
REFUND_IN_PROGRESS409이 주문과 관련한 환불이 처리 중이에요.
SUBSCRIPTION_REFUND_SETTLED409즉시 해지 환불 대상 주문이 정산 회차에 포함됐어요.
SUBSCRIPTION_REFUND_NONE_LEFT409구독 주문에 남은 환불 가능 금액이 없어요.
ORDER_NOT_FOUND404주문이 없거나 키의 상품 범위 밖이에요.
PG_REFUND_FAILED502결제 대행사가 환불 요청을 처리하지 못했어요.
PG_REFUND_AMBIGUOUS502결제 대행사의 환불 결과를 확인하지 못했어요. 실제 환불됐을 수 있으니 상태를 확인한 뒤 다시 처리해 주세요.
ALREADY_ENDED409이미 종료된 구독이에요.
ALREADY_CANCELED409이미 기간말 해지가 예약돼 있어요.

표에 없는 공통 오류(인증·권한, 호출 한도, 입력 검증, 멱등 키, 서버 오류)는 에러 코드에서 확인해요.

구독 객체

필드

amountnumber

갱신할 때 청구하는 주기당 금액의 상한을 원 단위 정수로 알려줘요. 상품 가격이 내려가면 다음 갱신부터 낮아지고, 인상은 고지 후 구매자가 동의해야 적용돼요.

billingIntervalstring

구독 결제 주기예요.

허용 값 monthly, yearly
buyerEmailstring

구매자 이메일 주소예요.

buyerNamestring

구매자 이름이에요.

cancelAtPeriodEndboolean

다음 기간 종료 시 해지하도록 예약했는지 알려줘요.

currencystring

금액 통화를 알려줘요.

허용 값 KRW
currentPeriodEndstring

현재 결제 기간 종료 시각이에요.

currentPeriodStartstring

현재 결제 기간 시작 시각이에요.

endReasonstringnull 가능

구독 종료 사유예요.

허용 값 canceled, refunded, payment_failed, product_unavailable, plan_unavailable, pg_canceled, price_increase_declined, null
endedAtstringnull 가능

구독이 종료된 시각이에요.

historyarray of objectnull 가능

구독 변경 이력이에요.

하위 필드 9개
atstring

변경이 기록된 시각이에요.

effectiveAtstringnull 가능

변경 효력이 발생하는 시각이에요.

extensionDaysnumbernull 가능

구독 기간 연장 일수예요.

fromobjectnull 가능

변경 전 플랜과 주기예요.

하위 필드 2개
billingIntervalstring

변경 전후 청구 주기예요.

허용 값 monthly, yearly
planIdstring

변경 전후 구독 플랜 식별자예요.

notestringnull 가능

이전 변경 기록의 메모예요.

orderIdstringnull 가능

변경과 연결된 주문 식별자예요.

prorationAmountnumbernull 가능

차액 결제 금액, 또는 갱신·가격 변경 이력의 금액을 원 단위로 알려줘요.

toobjectnull 가능

변경 후 플랜과 주기예요.

하위 필드 2개
billingIntervalstring

변경 전후 청구 주기예요.

허용 값 monthly, yearly
planIdstring

변경 전후 구독 플랜 식별자예요.

typestringnull 가능

내부 변경 기록 유형이에요.

허용 값 created, renewed, upgraded, downgrade_scheduled, downgrade_applied, interval_changed, cancel_scheduled, cancel_undone, ended, refunded, canceled_with_refund, comp_upgraded, period_extended, payment_failed, price_change_noticed, price_change_consented, null
idstring

구독 식별자예요.

modestring

test 또는 live 구독 환경을 알려줘요.

허용 값 live, test
pastDueSincestringnull 가능

결제 실패 상태가 시작된 시각이에요.

pendingPriceChangeobjectnull 가능

가격 인상 고지와 구매자 동의 상태예요.

하위 필드 5개
amountnumber

고지된 새 구독 금액을 원 단위로 알려줘요.

consentedAtstringnull 가능

구매자가 새 가격에 동의한 시각이에요.

currencystring

고지된 금액의 통화예요.

허용 값 KRW
effectiveFromstring

새 가격이 적용될 갱신일이에요.

noticedAtstring

가격 인상을 고지한 시각이에요.

planIdstring

구독 플랜 식별자예요.

productIdstring

상품 식별자예요.

productNamestring

상품 이름이에요.

refundEligibleUntilstring

최초 결제 환불 가능 기한이에요.

refundTermsobject

구독 환불 조건의 스냅샷이에요.

하위 필드 9개
dayRoundingstringnull 가능

일수 계산 방식이에요.

허용 값 ceil, floor, null
initialFullRefundDaysnumbernull 가능

최초 결제 전액 환불 가능 일수예요.

listAmountsobjectnull 가능

환불 계산에 사용하는 기준 금액이에요.

하위 필드 3개
currencystring

금액 통화를 알려줘요.

허용 값 KRW
monthlynumbernull 가능

월간 기준 금액이에요.

yearlynumbernull 가능

연간 기준 금액이에요.

penaltyobjectnull 가능

환불 위약금 조건이에요.

하위 필드 3개
currencystring

금액 통화를 알려줘요.

허용 값 KRW
fixedAmountnumbernull 가능

고정 위약금을 원 단위로 알려줘요.

rateBpsnumbernull 가능

위약금 비율을 1만분율로 알려줘요.

policyTypestringnull 가능

구독 환불 정책 유형이에요.

허용 값 no_refund, before_delivery, within_7days, custom, null
renewalFullRefundDaysnumbernull 가능

갱신 결제 전액 환불 가능 일수예요.

requireApprovalbooleannull 가능

환불 요청에 승인이 필요한지 알려줘요.

restrictRepeatFullRefundbooleannull 가능

반복 전액 환불 제한 여부예요.

yearlyDiscountClawbackbooleannull 가능

연간 할인 환수 여부예요.

scheduledChangeobjectnull 가능

예약된 구독 변경 정보예요.

하위 필드 4개
billingIntervalstringnull 가능

예약된 구독 청구 주기예요.

허용 값 monthly, yearly, null
effectiveAtstring

예약 변경 효력이 발생하는 시각이에요.

planIdstringnull 가능

예약된 구독 플랜 식별자예요.

typestring

예약 변경 유형이에요.

허용 값 downgrade, interval_change, cancel
startedAtstring

구독이 시작된 시각이에요.

statusstring

구독의 공개 상태예요. past_due 는 결제가 밀린 상태예요. 결제가 밀린 채 해지를 예약해도 past_due 이고 cancelAtPeriodEnd 가 true 예요.

허용 값 active, past_due, ended
testRenewalOutcomestringnull 가능

test 갱신 결과 설정이에요.

허용 값 succeed, fail, null

endReason 값

endReason 값의미
canceled해지로 종료됐어요.
refunded환불로 종료됐어요.
payment_failed갱신 결제 실패로 종료됐어요.
product_unavailable상품을 더 이상 제공할 수 없어 종료됐어요.
plan_unavailable플랜을 더 이상 제공할 수 없어 종료됐어요.
pg_canceledPG 측 취소로 종료됐어요.
price_increase_declined구매자가 가격 인상에 동의하지 않아 종료됐어요.
null종료 사유가 아직 없어요.

갱신 결제 실패

갱신 결제결과
1~3번째 실패past_due가 되고 24시간 뒤 다시 결제해요. 실패마다 subscription.payment_failed가 와요.
4번째 실패ended(endReason: payment_failed)로 끝나요. 첫 실패부터 약 72시간이에요.
past_due 중 기간말 해지 예약더 결제하지 않고 곧 ended(endReason: canceled)로 끝나요.

결제 수단은 구독을 시작할 때 정해지고 바꿀 수 없어요.

가격 변경

상품 가격을 올리면 구독자에게 고지되고, 구독 객체의 pendingPriceChange에 새 금액과 적용일(effectiveFrom)이 담겨요.

갱신결과
적용일 전기존 금액으로 결제돼요.
적용일, 구매자가 동의함새 금액으로 결제돼요.
적용일, 동의하지 않음결제 없이 ended(endReason: price_increase_declined)로 끝나요.

가격을 내리면 다음 갱신부터 내린 금액으로 결제돼요.

Last updated on
RefundsPortal Sessions