개발자센터

구독 API

고객이 상품을 정기적으로 청구받는 구독에 관한 API 입니다.

조건에 맞는 구독 리스트를 조회합니다.

이미 등록된 고객에게 구독을 추가합니다. 청구 시작일이 오늘이면 첫 인보이스를 즉시 결제합니다.

결제수단 없이 구독을 미리 만듭니다. 구독 등록 SDK로 결제수단이 등록되면 그 시점에 구독이 시작되고 첫 회차를 결제합니다. 그 전까지 구독은 INCOMPLETE 상태이며 시작일이 없습니다. 고객이 없으면 함께 만들고, 있으면 입력한 필드만 갱신합니다.

주어진 아이디로 구독을 조회합니다. 붙어 있는 할인과 다음 청구 예정 시각이 함께 내려갑니다.

구독을 수정합니다. 입력하지 않은 필드는 기존 값을 유지하며, 변경은 다음 결제부터 반영됩니다. 일할 계산은 하지 않습니다.

구독을 해지합니다. 해지한 구독은 다시 살릴 수 없습니다.

테스트 고객의 구독을 지금 한 회차 청구합니다. 다음 청구 예정 회차를 앞당겨 청구하며, 결제 실패를 시험하려면 실패 시뮬레이션을 켭니다.

구독에 붙어 있는 할인을 남은 회차와 상태와 함께 조회합니다. 제거된 할인은 빠집니다.

구독에 할인을 붙입니다. 다음 결제부터 적용되며 결제 직전까지 추가할 수 있습니다. 개수 제한은 없고 같은 할인을 중복해서 붙일 수는 없습니다.

구독에서 할인을 제거합니다. 적용 범위를 지정하면 그 범위로 붙은 것만, 지정하지 않으면 그 할인이 붙은 모든 범위를 제거합니다. 다음 결제부터 그 할인이 적용되지 않습니다. 붙어 있지 않으면 아무 일도 하지 않습니다.

구독의 다음 회차가 어떻게 청구될지 미리 계산해 보여줍니다. 실제 인보이스를 만들지는 않습니다.

한 구독의 인보이스를 청구 일시 역순으로 조회합니다.

구독을 일시중지합니다. 중지 중에는 인보이스 생성과 결제가 없습니다.

일시중지한 구독을 재개합니다. 청구 기준일과 기준 시각을 유지하므로 원래 정기결제일에 다음 인보이스를 만듭니다.

타입 정의

API 요청/응답의 각 필드에서 사용되는 타입 정의들을 확인할 수 있습니다
AddSubscriptionDiscountBody: { storeId, discountId, appliesTo, ... }
구독 할인 추가 입력 정보
AddSubscriptionDiscountError: ForbiddenError | InvalidRequestError | SubscriptionDiscountAlreadyAppliedError | ...
AddSubscriptionDiscountResponse: { subscription }
구독 할인 추가 성공 응답
CancelSubscriptionError: ForbiddenError | InvalidRequestError | SubscriptionNotFoundError | ...
CancelSubscriptionResponse: { subscription }
구독 해지 성공 응답
ChargeTestSubscriptionBody: { storeId, simulateFailure }
테스트 구독 즉시 청구 입력 정보
ChargeTestSubscriptionError: ForbiddenError | InvalidRequestError | SubscriptionCustomerHasNoBillingKeyError | ...
ChargeTestSubscriptionResponse: { subscription, invoice }
테스트 구독 즉시 청구 성공 응답
Country: "AD" | "AE" | "AF" | ...
국가
CreateSubscriptionBody: { storeId, id, customerId, ... }
구독 생성 입력 정보
CreateSubscriptionError: ForbiddenError | InvalidRequestError | SubscriptionAlreadyExistsError | ...
CreateSubscriptionResponse: { subscription, firstInvoice }
구독 생성 성공 응답
Currency: "KRW" | "USD" | "JPY" | ...
통화
ForbiddenError: { type, message }
요청이 거절된 경우
GetSubscriptionDiscountUsagesError: ForbiddenError | InvalidRequestError | SubscriptionNotFoundError | ...
GetSubscriptionDiscountUsagesResponse: { items }
구독에 붙은 할인 조회 성공 응답
GetSubscriptionError: ForbiddenError | InvalidRequestError | SubscriptionNotFoundError | ...
GetSubscriptionInvoicesBody: { storeId, page, from, ... }
구독 인보이스 다건 조회 입력 정보
GetSubscriptionInvoicesError: ForbiddenError | InvalidRequestError | SubscriptionNotFoundError | ...
GetSubscriptionInvoicesResponse: { items, page }
구독 인보이스 다건 조회 성공 응답
GetSubscriptionResponse: { subscription }
구독 조회 성공 응답
GetSubscriptionsBody: { storeId, page, status, ... }
구독 다건 조회 입력 정보
GetSubscriptionsError: ForbiddenError | InvalidRequestError | UnauthorizedError
GetSubscriptionsResponse: { items, page }
구독 다건 조회 성공 응답
InvalidRequestError: { type, message }
요청된 입력 정보가 유효하지 않은 경우

허가되지 않은 값, 올바르지 않은 형식의 요청 등이 모두 해당됩니다.

Locale: "KO_KR" | "EN_US" | "ZH_CN" | ...
결제 언어
Map_String: { [key: string]: string }
PageInfo: { number, size, totalCount }
반환된 페이지 결과 정보
PageInput: { number, size }
다건 조회 API 에 사용되는 페이지 입력 정보
PauseSubscriptionError: ForbiddenError | InvalidRequestError | SubscriptionNotFoundError | ...
PauseSubscriptionResponse: { subscription }
구독 일시중지 성공 응답
PaymentProductType: "PHYSICAL" | "DIGITAL"
상품 유형
PreRegisterSubscriptionBody: { storeId, id, customer, ... }
구독 사전 등록 입력 정보
PreRegisterSubscriptionError: ForbiddenError | InvalidRequestError | SubscriptionAlreadyExistsError | ...
PreRegisterSubscriptionResponse: { subscription, customer, registrationSecret }
구독 사전 등록 성공 응답
PreviewSubscriptionInvoiceError: ForbiddenError | InvalidRequestError | SubscriptionNotFoundError | ...
PreviewSubscriptionInvoiceResponse: { preview }
다음 인보이스 미리보기 성공 응답
RemoveSubscriptionDiscountBody: { appliesTo }
구독 할인 제거 입력 정보
RemoveSubscriptionDiscountError: ForbiddenError | InvalidRequestError | SubscriptionNotFoundError | ...
RemoveSubscriptionDiscountResponse: { subscription }
구독 할인 제거 성공 응답
ResumeSubscriptionError: ForbiddenError | InvalidRequestError | SubscriptionNotFoundError | ...
ResumeSubscriptionResponse: { subscription }
구독 재개 성공 응답
Subscription: { id, customerId, items, ... }
구독
SubscriptionAlreadyExistsError: { type, message }
같은 아이디의 구독이 이미 존재하는 경우
SubscriptionCurrencyMismatchError: { type, message }
담긴 상품들의 통화가 다른 경우
SubscriptionCustomer: { id, name, email, ... }
구독 고객

구독 결제의 대상이 되는 고객입니다. 고객당 빌링키는 하나입니다.

SubscriptionCustomerBillingKeyMethod: "CARD" | "PAYPAL"
구독 고객 빌링키 결제수단
SubscriptionCustomerCard: { issuerName, number }
구독 고객 카드 정보
SubscriptionCustomerEmailRequiredError: { type, message }
인보이스 메일을 보내려는데 구독 고객의 이메일이 없는 경우
SubscriptionCustomerHasNoBillingKeyError: { type, message }
구독 고객에게 사용 가능한 빌링키가 없는 경우
SubscriptionCustomerNotFoundError: { type, message }
요청된 구독 고객이 존재하지 않는 경우
SubscriptionCustomerNotInTestModeError: { type, message }
구독 고객이 테스트 고객이 아닌 경우
SubscriptionCustomerStatus: "ACTIVE"
구독 고객 상태
SubscriptionDiscountAlreadyAppliedError: { type, message }
같은 구독 할인이 이미 붙어 있는 경우
SubscriptionDiscountApplication: { discountId, appliesTo, duration }
구독에 붙일 할인
SubscriptionDiscountAppliesTo: SubscriptionDiscountAppliesToProducts | SubscriptionDiscountAppliesToSubscription
SubscriptionDiscountAppliesToProducts: { type, productIds }
지정한 상품 항목에만 적용
SubscriptionDiscountAppliesToSubscription: { type }
인보이스 전체에 적용
SubscriptionDiscountArchivedError: { type, message }
구독 할인이 보관된 경우
SubscriptionDiscountCurrencyMismatchError: { type, message }
구독 할인의 통화가 구독의 통화와 다른 경우
SubscriptionDiscountDuration: SubscriptionDiscountDurationCycles | SubscriptionDiscountDurationForever | SubscriptionDiscountDurationOnce
SubscriptionDiscountDurationCycles: { type, count }
지정한 회차만큼 적용
SubscriptionDiscountDurationForever: { type }
소진 없이 계속 적용
SubscriptionDiscountDurationOnce: { type }
한 회차만 적용
SubscriptionDiscountNotFoundError: { type, message }
요청된 구독 할인이 존재하지 않는 경우
SubscriptionDiscountProductsNotInSubscriptionError: { type, message, productIds }
구독 할인의 적용 대상 상품이 구독에 담겨 있지 않은 경우
SubscriptionDiscountRedeemByPassedError: { type, message }
구독 할인의 적용 마감일이 지난 경우
SubscriptionDiscountType: "PERCENT" | "AMOUNT"
구독 할인 유형
SubscriptionDiscountUsage: { discountId, appliedAt, remainingCount, ... }
구독 할인 사용 현황

구독에 붙어 있는 할인의 적용 범위·지속 방식과 남은 회차, 상태입니다. 할인 금액 조건은 할인 아이디로 조회합니다.

SubscriptionDiscountUsageStatus: "ACTIVE" | "EXHAUSTED" | "REMOVED"
구독 할인 사용 상태
SubscriptionEndReason: "CANCELED" | "ONE_TIME_EXHAUSTED" | "END_DATE_REACHED"
구독 종료 사유
SubscriptionInterval: { unit, count }
구독 주기
SubscriptionIntervalMismatchError: { type, message }
담긴 정기 상품들의 청구 주기가 서로 다르거나, 시작한 구독의 청구 주기와 다른 경우
SubscriptionIntervalUnit: "DAY" | "WEEK" | "MONTH" | ...
구독 주기 단위
SubscriptionInvoice: { id, subscriptionId, customerId, ... }
구독 인보이스
SubscriptionInvoiceDiscountLine: { discountId, name, type, ... }
구독 인보이스 할인 내역

인보이스 발행 시점의 할인 조건을 그대로 담습니다. 원본 할인이 이후에 바뀌어도 변하지 않습니다.

SubscriptionInvoiceItem: { productId, name, unitPrice, ... }
구독 인보이스 항목
SubscriptionInvoiceMethod: "CARD_BILLING" | "PAYPAL_BILLING"
구독 인보이스 결제 수단
SubscriptionInvoicePayment: { paymentId, billingKey, failure, ... }
구독 인보이스 결제 정보
SubscriptionInvoicePaymentFailure: { type, pgCode, pgMessage, ... }
구독 인보이스 결제 실패 정보
SubscriptionInvoicePaymentFailureReason: "INSUFFICIENT_FUNDS_OR_LIMIT_EXCEEDED" | "CARD_UNAVAILABLE" | "CARD_EXPIRED" | ...
구독 인보이스 결제 실패 사유 분류

결제사 실패 메시지를 단어로 묶은 것입니다.

SubscriptionInvoicePaymentFailureType: "PG_PROVIDER" | "BILLING_KEY_NOT_FOUND" | "BILLING_KEY_ALREADY_DELETED" | ...
구독 인보이스 결제 실패 유형
SubscriptionInvoicePreview: { billingAt, sequence, items, ... }
다음 인보이스 미리보기 결과
SubscriptionInvoiceRefund: { cancellationId, amount, refundedAt, ... }
구독 인보이스 환불

결제 건이 결제취소 API·콘솔로 취소된 한 건입니다. 부분 취소마다 한 건씩 쌓입니다.

SubscriptionInvoiceSettlement: { method }
구독 인보이스 수동 완납 정보
SubscriptionInvoiceSettlementMethod: "BANK_TRANSFER" | "CARD" | "OTHER"
구독 인보이스 수동 완납 방법
SubscriptionInvoiceSource: "AUTO" | "MANUAL"
구독 인보이스 생성 경로
SubscriptionInvoiceStatus: "PENDING" | "PAID" | "FAILED" | ...
구독 인보이스 상태
SubscriptionItem: { productId, quantity }
구독 항목
SubscriptionNotFoundError: { type, message }
요청된 구독이 존재하지 않는 경우
SubscriptionPaymentOptions: { locale, productType, installmentMonth, ... }
구독 결제 옵션

매 회차 결제 요청에 그대로 실리는 값입니다. 빌링키 결제 예약의 같은 이름 필드와 의미가 같습니다.

SubscriptionPreRegisterCustomerInput: { id, name, email, ... }
함께 등록할 구독 고객 정보
SubscriptionProductArchivedError: { type, message }
구독 상품이 보관되어 수정할 수 없는 경우
SubscriptionProductBillingPausedError: { type, message, productIds }
구독 상품의 청구가 중지된 경우
SubscriptionProductNotFoundError: { type, message }
요청된 구독 상품이 존재하지 않는 경우
SubscriptionStatus: "ACTIVE" | "INCOMPLETE" | "PAUSED" | ...
구독 상태
SubscriptionStatusNotAllowedError: { type, message, status }
현재 구독 상태에서 허용되지 않는 요청인 경우
UnauthorizedError: { type, message }
인증 정보가 올바르지 않은 경우
UpdateSubscriptionBody: { storeId, items, endDate, ... }
구독 수정 입력 정보
UpdateSubscriptionBodyPaymentOptions: { locale, productType, installmentMonth, ... }
구독 결제 옵션 수정 입력

입력한 필드만 고칩니다. null을 보내면 그 필드를 지웁니다.

UpdateSubscriptionError: ForbiddenError | InvalidRequestError | SubscriptionCurrencyMismatchError | ...
UpdateSubscriptionResponse: { subscription }
구독 수정 성공 응답