구독

구독 템플릿

구독의 규칙은 상품이 아니라 템플릿에 적어 두고 재사용해요.

v1 API 상세 명세

결제 주기, 위약금, 일시정지 허용 여부처럼 구독이 어떻게 굴러갈지​​를 담는 설정이에요. 상품 등록의 subscription_setting_id 가 여기서 나와요.

구독 모델 구조에서 설명한 네 계층 중 맨 위 계층이에요. 템플릿을 먼저 만들고, 상품에 붙이고, 고객이 신청하면 계약이 생겨요.

상품에 붙일 때는 `save_by: 3` 이 필요해요

상품 등록에서 use_subscription: true 와 subscription_setting_id 를 넘겨도 save_by: 3 이 없으면 템플릿이 연결되지 않아요. 오류 없이 저장되기 때문에 알아채기 어려워요.

목록 조회

GEThttps://api.bootapi.com/v1/subscription_settingsBasic Auth
파라미터 타입 필수 설명
keyword String 선택 템플릿 이름 검색
page Integer 선택 페이지 번호 (기본: 1)
limit Integer 선택 페이지당 데이터 수 (기본: 24)

목록은 사용 중인 설정만 최신순으로 돌려줘요. 이 API에는 페이지 크기 상한이 없으므로 limit을 1~100으로 보내요.

생성

POSThttps://api.bootapi.com/v1/subscription_settingsBasic Auth

파라미터가 많아 기능 단위로 묶어 봐요. 넘기지 않은 값은 모델 기본값이 쓰여요.

기본

파라미터 타입 필수 설명
template_name String 선택 템플릿 이름
type Integer 필수 구독 유형. 구독 유형 참고. 빠지거나 지원하지 않는 값이면 오류가 나요
is_default Boolean 선택 프로젝트 기본 템플릿으로 지정할지
use_approval_auto Boolean 선택 신청을 자동 승인할지. false 면 구독 승인이 필요해요
use_payment_timing_request Boolean 선택 결제 시점을 고객이 고르게 할지
use_backup_payment Boolean 선택 예비 결제수단 사용
use_apply_coupon Boolean 선택 쿠폰 적용 허용
use_apply_point Boolean 선택 적립금 사용 허용
use_change_product_option Boolean 선택 구독 중 옵션 변경 허용
expose_auto_charge_consent Boolean 선택 자동결제 동의 노출. 수시결제(type: 7)에서만 적용​​되고 다른 유형에서는 무시돼요

결제 주기

파라미터 타입 필수 설명
payment_cycle_type Integer 선택 결제 주기. 결제 주기 참고. 종량제에는 월 단위만 쓸 수 있어요
delivery_cycle_type Integer 선택 배송 주기. 비우면 payment_cycle_type 을 따라가요
use_payment_date Boolean 선택 결제일 고정 사용
payment_date_type Integer 선택 결제일 지정 방식
payment_date_value Array 선택 결제일 값
use_subscription_times Boolean 선택 회차 수 제한 사용
subscription_times_label String 선택 회차 표기 문구
subscription_periods Array 선택 회차별 가격표

설치비·할인

파라미터 타입 필수 설명
use_setup_fee Boolean 선택 설치비 사용
setup_fee_value Number 선택 설치비 금액
setup_fee_type Integer 선택 설치비 부과 방식
setup_fee_name String 선택 설치비 항목명
setup_fee_text String 선택 설치비 안내 문구
fee_pay_type Integer 선택 배송비 지불 방식. 생략하면 0으로 저장돼요
use_first_discount Boolean 선택 첫 회차 할인 사용
first_discount_type Integer 선택 첫 회차 할인 방식
first_discount_value Number 선택 첫 회차 할인 값
use_times_benefit Boolean 선택 회차별 혜택 사용
times_benefit Array 선택 회차별 혜택 정의
use_free_trial Boolean 선택 무료 체험 사용
free_trial_day Integer 선택 무료 체험 일수

미납·연체

파라미터 타입 필수 설명
use_auto_unsubscribe Boolean 선택 결제 실패가 이어지면 자동 해지할지
auto_unsubscribe_day Integer 선택 자동 해지까지 유예 일수
auto_unsubscribe_retry_count Integer 선택 자동 해지 전 재시도 횟수
use_auto_pause Boolean 선택 결제 실패 시 자동 일시정지
use_late_fee Boolean 선택 연체료 사용
late_fee_type / late_fee_value / late_fee_value_type / late_fee_date — 선택 연체료 방식·값·기준일
late_fee_text String 선택 연체료 안내 문구
자동 중단은 웹훅으로 알려줘요

use_auto_pause 로 멈춘 구독은 subscription.hold_on 웹훅이 나가요. 처리 기준은 웹훅 처리 가이드를 봐요.

일시정지·해지

파라미터 타입 필수 설명
use_pause Boolean 선택 일시정지 허용
use_pause_approval Boolean 선택 일시정지에 관리자 승인이 필요한지
pause_max_count Integer 선택 최대 일시정지 횟수
pause_max_duration Integer 선택 최대 일시정지 기간
use_cancel / use_cancel_approval / use_cancel_collect_reason Boolean 선택 취소 허용·승인 필요·사유 수집
use_cancel_condition / cancel_condition_type / cancel_condition_value — 선택 취소 가능 조건
use_cancel_fee / use_fixed_cancel_fee Boolean 선택 취소 수수료 사용
fixed_cancel_fee_name / fixed_cancel_fee_value / fixed_cancel_fee_type — 선택 고정 취소 수수료
use_termination Boolean 선택 중도 해지 허용
use_termination_approval Boolean 선택 해지에 관리자 승인이 필요한지
use_termination_reason Boolean 선택 해지 사유 수집
use_termination_fee Boolean 선택 위약금 사용
termination_free_cancellation_days Integer 선택 위약금 없이 해지 가능한 초기 일수
termination_fee_label / termination_fee_type / termination_fee_value — 선택 위약금 표기·방식·값
use_last_bill_refund Boolean 선택 마지막 회차 환불 허용

중도인수·승계 (렌탈·리스)

파라미터 타입 필수 설명
use_transfer / use_transfer_fee Boolean 선택 승계 허용·수수료 사용
transfer_fee_type / transfer_fee_value — 선택 승계 수수료 방식·값
use_purchase Boolean 선택 중도 인수 허용
use_purchase_fee_auto Boolean 선택 인수 금액 자동 계산
purchase_fee_calc_type Integer 선택 인수 금액 계산 방식 (1 고정 / 2 비율 / 3 렌탈 기준)
purchase_fee_rate Number 선택 인수 비율
purchase_depreciation_rate Number 선택 감가상각률

만기 처리 (렌탈·리스)

파라미터 타입 필수 설명
use_expired_return / use_expired_return_fee_auto Boolean 선택 만기 반납 허용·수수료 자동 계산
expired_return_fee_type / expired_return_fee_value — 선택 반납 수수료
use_expired_purchase / use_expired_purchase_fee_auto Boolean 선택 만기 인수 허용·수수료 자동 계산
expired_purchase_fee_type / expired_purchase_fee_value — 선택 만기 인수 수수료
use_expired_extend / use_expired_extend_fee / use_expired_extend_fee_auto Boolean 선택 만기 연장 허용·수수료
expired_extend_fee_type / expired_extend_fee_value — 선택 연장 수수료
use_expired_extend_sale / expired_extend_sale_type / expired_extend_sale_value — 선택 연장 시 할인

배송 (정기배송)

파라미터 타입 필수 설명
use_delivery_change_address Boolean 선택 배송지 변경 허용
delivery_after Integer 선택 결제 후 발송까지 일수
use_delivery_change_day Boolean 선택 배송일 변경 허용
use_delivery_change_times_delay Boolean 선택 배송 미루기 허용
use_delivery_change_times_urgent Boolean 선택 배송 당기기 허용
use_delivery_rest Boolean 선택 배송 쉬는 요일 사용
delivery_rest Array 선택 배송 불가 요일

수정

PUThttps://api.bootapi.com/v1/subscription_settings/:idBasic Auth
파라미터 타입 필수 설명
subscription_setting_id String 필수 수정할 템플릿 ID. 본문에 넣어요 — 경로의 :id 는 읽지 않아요

나머지는 생성과 같아요. fee_pay_type은 수정할 때도 생략하면 0으로 덮어써요. 기존 값을 유지하려면 다시 보내요. subscription_periods를 보내면 약정 기간 목록을 보낸 내용으로 맞추므로, 기존 항목을 유지하려면 해당 항목의 _id도 보내요.

수정해도 진행 중인 계약은 안 바뀌어요

템플릿을 고치면 스냅샷이 새로 만들어지고, 이후 새로 생기는 계약​​부터 적용돼요. 이미 굴러가는 계약의 조건을 바꾸려면 플랜 변경을 써요.

삭제

DELETEhttps://api.bootapi.com/v1/subscription_settings/:idBasic Auth
알려진 문제 — 사용 중인 템플릿도 지금은 삭제돼요

현재는 사용 여부를 확인하지 않고 바로 삭제해요. 삭제하기 전에 상품 목록에서 이 템플릿(subscription_setting_id)을 쓰는 상품이 없는지 먼저 확인해요.

에러 코드

공통 에러

인증·권한 관련 에러는 커머스 API 인증 에러를 참고해요.

코드 메시지 대처 방법
SUBSCRIPTION_SETTING_NOT_FOUND 구독 템플릿을 찾을 수 없어요 subscription_setting_id 와 프로젝트를 확인해요
INVALID_SUBSCRIPTION_SETTING 올바른 구독설정이 아니에요 다른 프로젝트의 템플릿인지 확인해요
SUBSCRIPTION_SETTING_TYPE_INVALID 구독 유형 설정이 잘못되었어요 type 을 1·4·5·6·7 중 하나로 보내요
SUBSCRIPTION_SETTING_PREPAID_ON_USAGE_NOT_ABLE 사용량 과금 기반 구독은 선불 결제를 설정할 수 없어요 종량제는 후불로 설정해요
SUBSCRIPTION_SETTING_USAGE_CYCLE_MONTHLY_ONLY 사용량 과금 기반 구독은 월 단위 결제 주기만 설정할 수 있어요 payment_cycle_type 을 월 단위로 보내요
SUBSCRIPTION_SETTING_FREE_TRIAL_DAY_EXCEED 무료체험 기간은 최대 365일까지 설정할 수 있어요 free_trial_day 를 365 이하로 보내요

함께 보기

최신 글구독 용어 사전 이전 글구독 계약 개요