v1 API 상세 명세
결제 주기, 위약금, 일시정지 허용 여부 등 구독 운영 규칙을 담는 구독 템플릿을 조회·생성·수정·삭제합니다. 상품 등록의 subscription_setting_id 가 이 템플릿의 ID입니다.
템플릿은 구독 모델 구조의 네 계층 중 맨 위 계층입니다. 템플릿을 만들고 상품에 붙이면, 고객이 신청할 때 계약이 생깁니다.
상품 등록에서 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 |
선택 |
재시도를 모두 실패하면 자동 해지할지 (기본 false) |
auto_unsubscribe_day |
Integer |
선택 |
결제 실패 후 다시 시도하기까지의 간격(일). 기본 3 |
auto_unsubscribe_retry_count |
Integer |
선택 |
결제 실패 후 재시도 횟수. 기본 3. 다 쓰면 자동 해지·자동 중단·다음 결제일 이월 중 하나로 넘어갑니다 |
use_auto_pause |
Boolean |
선택 |
재시도를 모두 실패하면 자동 중단(paused_due_to_issue)할지 (기본 false). use_auto_unsubscribe 와 함께 켜면 자동 해지가 적용됩니다 |
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)을 쓰는 상품이 없는지 먼저 확인합니다.
에러 코드
| 코드 |
메시지 |
대처 방법 |
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 이하로 보냅니다 |