구독 설정

구독 설정은 정기구독 상품에 붙이는 정책 템플릿​​입니다. 결제 주기·결제일, 가입비·첫 결제 할인, 무료 체험, 일시정지·해지·인수·이전 허용 여부와 수수료, 만기 후 처리 같은 규칙을 한 묶음으로 저장하고, 여러 상품이 같은 설정을 함께 씁니다. 설정을 만들거나 바꿀 때마다 그 시점의 사본(스냅샷)이 따로 남습니다.

경로가 이 리소스만 밑줄(subscription_settings)을 씁니다. 대시(subscription-settings) 주소는 없습니다.

주요 코드값

응답에서는 아래 값이 문자열로 나갑니다. 요청에는 숫자​​로 보냅니다.

필드 숫자 → 응답 문자열
type 1 regular_subscription(정기), 4 delivery_subscription(정기배송), 5 rental_lease_subscription(렌탈·리스), 6 usage_based_subscription(사용량 기반), 7 on_demand_subscription(수시결제)
payment_cycle_type, delivery_cycle_type 11 1week, 12 2weeks, 13 3weeks, 14 4weeks, 16 6weeks, 21 1month, 22 2months, 23 3months, 26 6months, 31 1year
payment_date_type 1 fixed_day_of_period(주기 내 지정일), 2 subscription_start(가입일 기준)
fee_pay_type 1 collect(착불), 2 prepaid(선불), 3 collect_or_prepaid
setup_fee_type, first_discount_type, late_fee_value_type, expired_extend_sale_type, transfer_fee_type 1 percentage, 2 fixed_price, 3 count
late_fee_type 1 simple, 2 compound
expired_return_fee_type, expired_purchase_fee_type, expired_extend_fee_type, termination_fee_type, purchase_fee_calc_type 1 calc_type_fixed, 2 calc_type_rate, 3 calc_type_rental_based
status 1 active, 0 inactive

GET /v1/subscription_settings

프로젝트의 사용 중인 구독 설정 목록을 최신순으로 조회합니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:subscription_setting_list — Bootpay-Role 은 user(생략 가능)만 받습니다
  • 회원 JWT: 필요 없음

요청

위치 이름 타입 필수 기본값 설명
query keyword string 템플릿 이름(template_name) 부분 일치, 대소문자 무시
query page integer 1 페이지
query limit integer 24 페이지 크기

이 API 는 공통 페이지네이션 보정 규칙을 쓰지 않습니다. 기본 limit 이 24 이고 상한이 없습니다. 1 이상 100 이하로 보내세요.

응답

200 OK

{
  "list": [
    {
      "subscription_setting_id": "66b0...",
      "project_id": "5f...",
      "seller_id": "5e...",
      "template_name": "월간 기본",
      "type": "regular_subscription",
      "status": "active",
      "payment_cycle_type": "1month",
      "delivery_cycle_type": "1month",
      "use_payment_date": true,
      "payment_date_type": "fixed_day_of_period",
      "payment_date_value": [25],
      "fee_pay_type": "prepaid",
      "use_free_trial": false,
      "free_trial_day": 0,
      "use_pause": true,
      "use_pause_approval": true,
      "use_termination": true,
      "use_termination_fee": false,
      "subscription_periods": [],
      "created_at": "2026-09-01T10:00:00+09:00",
      "updated_at": "2026-09-10T10:00:00+09:00"
    }
  ],
  "count": 1
}json
필드 타입 설명
subscription_setting_id string 설정 ID
project_id / seller_id string 프로젝트·판매자 ID
product_snapshot_id string 연결된 상품 스냅샷 (있을 때)
template_name string 템플릿 이름
type, status 와 코드값 필드 string 위 주요 코드값 표
use_* boolean 각 기능 사용 여부 (아래 생성 API 의 요청 표와 같은 이름)
그 밖의 값 필드 생성 API 의 요청 표와 같은 이름·뜻
subscription_periods array 약정 기간 목록 (아래)
created_at / updated_at string 생성·수정 시각
count integer 전체 개수

subscription_periods[]

필드 타입 설명
subscription_period_id string 약정 기간 ID
label string 이름 (예: 12개월 약정)
duration / duration_type integer 기간 값 / 단위
cost_price / display_price / tax_free_price number 원가 / 판매가 / 비과세
use_discount / discount_price / discount_price_type 할인
use_times_benefit boolean 회차 혜택 사용
default_field boolean 기본 선택
times_benefits array 회차별 혜택 (있을 때)

값이 없는(null) 필드는 빠집니다.

오류

공통 오류만 있습니다. 오류를 봅니다.

변경 이력

  • 2026-09-23 문서 최초 작성
  • 2026-09-29 scope 검사 추가 — 이전에는 Basic 인증만 통과하면 어떤 키로도 호출됐습니다. supervisor 가 아닌 키체인은 해당 scope 를 부여받아야 합니다

POST /v1/subscription_settings

구독 설정을 만듭니다.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:subscription_setting_create — Bootpay-Role 은 user(생략 가능)만 받습니다
  • 회원 JWT: 필요 없음

요청

모두 body 입니다. 보내지 않은 값은 기본값이 적용됩니다. 금액·비율은 숫자, 유형은 숫자 코드​​로 보냅니다.

이름 타입 필수 설명
type integer O 구독 유형 (위 표)
template_name string 템플릿 이름
is_default boolean true 면 프로젝트 기본 구독 설정으로 지정
use_approval_auto boolean 가입 자동 승인
use_payment_timing_request boolean 결제 시점 요청 사용
expose_auto_charge_consent boolean 결제창 구독 동의 노출. 수시결제(7) 일 때만 반영, 다른 유형은 무시
payment_cycle_type integer 결제 주기
delivery_cycle_type integer 배송 주기. 없으면 payment_cycle_type 과 같게
use_payment_date / payment_date_type / payment_date_value boolean / integer / integer[] 결제일 지정
use_subscription_times / subscription_times_label boolean / string 약정(회차) 사용 / 표시 이름
subscription_periods array 약정 기간 목록. 항목: _id(기존 항목 수정 시), label, duration, duration_type, cost_price, display_price, tax_free_price, use_discount, discount_price, discount_price_type, use_times_benefit, default_field, times_benefits. use_subscription_times 가 참이면 duration 이 0 보다 큰 항목만, 거짓이면 duration 이 -1 인 항목만 저장됩니다
use_setup_fee / setup_fee_type / setup_fee_value / setup_fee_name / setup_fee_text 가입비
fee_pay_type integer 배송비 지불 방식. 보내지 않으면 0 으로 저장​​됩니다
use_first_discount / first_discount_type / first_discount_value 첫 결제 할인
use_times_benefit / times_benefit boolean / array 회차 혜택. times_benefit[]: times, type, value
use_apply_coupon / use_apply_point / use_backup_payment / use_change_product_option boolean 쿠폰·포인트 적용, 예비 결제수단, 옵션 변경 허용
use_free_trial / free_trial_day boolean / integer 무료 체험 (최대 365일)
use_auto_unsubscribe / auto_unsubscribe_day / auto_unsubscribe_retry_count 결제 실패 시 자동 해지
use_auto_pause boolean 결제 실패 시 자동 일시정지
use_late_fee / late_fee_type / late_fee_value / late_fee_value_type / late_fee_date / late_fee_text 연체료
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 / fixed_cancel_fee_name / fixed_cancel_fee_value / fixed_cancel_fee_type 취소 수수료
use_delivery_change_address / delivery_after / use_delivery_change_day / use_delivery_change_times_delay / use_delivery_change_times_urgent 배송 변경 허용
use_delivery_rest / delivery_rest boolean / integer[] 배송 휴무
use_expired_return / use_expired_return_fee_auto / expired_return_fee_type / expired_return_fee_value 만기 후 반납
use_expired_purchase / use_expired_purchase_fee_auto / expired_purchase_fee_type / expired_purchase_fee_value 만기 후 구매
use_expired_extend / use_expired_extend_fee / use_expired_extend_fee_auto / expired_extend_fee_type / expired_extend_fee_value / use_expired_extend_sale / expired_extend_sale_type / expired_extend_sale_value 만기 후 연장
use_pause / use_pause_approval / pause_max_count / pause_max_duration 일시정지
use_transfer / use_transfer_fee / transfer_fee_type / transfer_fee_value 이전·승계
use_purchase / use_purchase_fee_auto / purchase_fee_calc_type / purchase_fee_rate / purchase_depreciation_rate 중도 인수
use_termination / use_termination_approval / use_termination_reason / use_termination_fee / termination_free_cancellation_days / termination_fee_label / termination_fee_type / termination_fee_value / use_last_bill_refund 중도 해지

검증 규칙

  • 사용량 기반(6)은 결제 주기가 월 단위(1month 등)여야 하고, 첫 회차 선결제를 쓸 수 없습니다.
  • 수시결제(7)는 주기·결제일·회차 값을 쓰지 않습니다.

응답

200 OK, 본문 없음. 만든 설정의 ID 가 필요하면 목록 API 로 조회하세요.

오류

HTTP error_code 언제
400 SUBSCRIPTION_SETTING_TYPE_INVALID type 이 없거나 지원하지 않는 값
400 SUBSCRIPTION_SETTING_PREPAID_ON_USAGE_NOT_ABLE 사용량 기반인데 첫 회차 선결제
400 SUBSCRIPTION_SETTING_USAGE_CYCLE_MONTHLY_ONLY 사용량 기반인데 결제 주기가 월 단위가 아님
400 SUBSCRIPTION_SETTING_FREE_TRIAL_DAY_EXCEED 무료 체험이 365일 초과

변경 이력

  • 2026-09-23 문서 최초 작성
  • 2026-09-29 scope 검사 추가 — 이전에는 Basic 인증만 통과하면 어떤 키로도 호출됐습니다. supervisor 가 아닌 키체인은 해당 scope 를 부여받아야 합니다

PUT /v1/subscription_settings/:id

구독 설정을 수정합니다. 보낸 값만 바꾸고, 수정 결과로 새 스냅샷이 남습니다. PATCH 도 같습니다.

대상은 경로의 :id 가 아니라 본문의 subscription_setting_id 로 찾습니다. 본문에 넣지 않으면 404 SUBSCRIPTION_SETTING_NOT_FOUND 입니다. 두 값을 같게 보내세요.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:subscription_setting_update — Bootpay-Role 은 user(생략 가능)만 받습니다
  • 회원 JWT: 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 설정 ID (현재 대상 선택에는 쓰이지 않음)
body subscription_setting_id string O 수정할 설정 ID
body type integer 구독 유형. 보내지 않으면 기존 값 유지
body fee_pay_type integer 보내지 않으면 0 으로 덮어씁니다. 현재 값을 유지하려면 다시 보내세요
body 그 밖의 필드 POST /v1/subscription_settings 요청 표와 같음

subscription_periods 를 보내면 약정 기간 목록을 보낸 내용으로 맞춥니다. 기존 항목을 유지하려면 그 항목의 _id 를 함께 보내세요.

응답

200 OK, 본문 없음

오류

HTTP error_code 언제
404 SUBSCRIPTION_SETTING_NOT_FOUND subscription_setting_id 가 없거나 이 프로젝트의 설정이 아님
400 INVALID_SUBSCRIPTION_SETTING 설정의 판매자·프로젝트가 인증 정보와 다름
400 SUBSCRIPTION_SETTING_TYPE_INVALID 외 생성 API 와 같은 검증 오류

변경 이력

  • 2026-09-23 문서 최초 작성
  • 2026-09-29 scope 검사 추가 — 이전에는 Basic 인증만 통과하면 어떤 키로도 호출됐습니다. supervisor 가 아닌 키체인은 해당 scope 를 부여받아야 합니다

DELETE /v1/subscription_settings/:id

구독 설정을 삭제합니다. 복구할 수 없습니다.

상품이 이 설정을 쓰고 있어도 삭제를 막지 않습니다. 사용 중인 상품이 없는지 먼저 확인하세요.

인증

  • Authorization: Basic base64(clientKey:secretKey) 필수 — 인증
  • 필요한 scope: user:subscription_setting_delete — Bootpay-Role 은 user(생략 가능)만 받습니다
  • 회원 JWT: 필요 없음

요청

위치 이름 타입 필수 기본값 설명
path id string O 설정 ID

응답

200 OK, 본문 없음

오류

HTTP error_code 언제
404 SUBSCRIPTION_SETTING_NOT_FOUND 없는 설정 ID 또는 다른 프로젝트의 설정 ID

변경 이력

  • 2026-09-23 문서 최초 작성
  • 2026-09-28 인증된 프로젝트의 설정만 삭제 — 다른 프로젝트 설정 ID 는 404
  • 2026-09-29 scope 검사 추가 — 이전에는 Basic 인증만 통과하면 어떤 키로도 호출됐습니다. supervisor 가 아닌 키체인은 해당 scope 를 부여받아야 합니다

함께 보기