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