조정 항목 전체 변경

v1 API 상세 명세

구독 계약의 회차 금액 조정 항목을 한번에 변경합니다. 지정한 회차(duration)의 조정 항목을 요청한 항목으로 모두 대체​​합니다.

API 엔드포인트

PUThttps://api.bootapi.com/v1/order_subscriptions/:id/adjustmentsBasic Auth (supervisor 권한 필요)
관리자 권한 필요

이 API는 Basic 인증과 supervisor:order_subscription_adjustment_update scope가 필요합니다.

전체 대체 방식

지정한 회차(duration, 기본 1)의 기존 조정 항목이 모두 삭제되고 요청한 항목으로 대체됩니다. 다른 회차의 조정과 무제한(is_unlimited) 조정은 그대로 남습니다. 수정이 아닌 전체 교체입니다. 특정 항목만 삭제하려면 조정 항목 삭제를 사용합니다.

요청 파라미터

파라미터 타입 필수 설명
order_subscription_id String 필수 구독 계약 고유 번호 (URL 경로)
duration Integer 선택 대체 대상 회차. 요청 최상위 파라미터​​입니다 (기본 1)
adjustments Array 필수 해당 회차를 대체할 조정 항목 배열
  └─ name String 필수 조정 항목명
  └─ price Integer 필수 조정 금액
  └─ tax_free_price Integer 선택 면세 금액
  └─ type Integer 필수 조정 타입 숫자(아래 표의 값). 항목 안에 duration 을 넣어도 무시됩니다

코드 예제

curl -X PUT "https://api.bootapi.com/v1/order_subscriptions/{order_subscription_id}/adjustments" \
  -H "Authorization: Basic {base64(client_key:secret_key)}" \
  -H "Content-Type: application/json" \
  -d '{
    "duration": 1,
    "adjustments": [
      {
        "name": "설치비",
        "price": 50000,
        "type": 2
      },
      {
        "name": "프로모션 할인",
        "price": -10000,
        "type": 1
      }
    ]
  }'bash

응답

성공 응답

변경이 반영된 구독 계약 상세 전체를 돌려줍니다. 아래는 조정 항목 부분만 정리한 예시입니다.

{
  "order_subscription_id": "687a1b2c3d4e5f6789012345",
  "order_subscription_adjustments": [
    {
      "order_subscription_adjustment_id": "6965fc104cb8149d07712533",
      "name": "설치비",
      "price": 50000,
      "tax_free_price": 0,
      "type": "setup_price",
      "duration": 1,
      "is_unlimited": false
    },
    {
      "order_subscription_adjustment_id": "6965fc104cb8149d07712534",
      "name": "프로모션 할인",
      "price": -10000,
      "tax_free_price": 0,
      "type": "discount",
      "duration": 1,
      "is_unlimited": false
    }
  ]
}json

응답 파라미터

파라미터 타입 설명
order_subscription_id String 구독 계약 ID
order_subscription_adjustments Array 계약에 걸린 전체 조정 항목 목록 (다른 회차·무제한 조정 포함)
상태·유형 값은 문자열입니다

응답의 status 같은 코드값은 정수가 아니라 문자열(enum)로 내려옵니다. 전체 목록은 커머스 Enum에서 확인합니다.

조정 타입 (type)

값 키 설명
1 discount 회차별 할인 적용
2 setup_price 추가금액 (설치비 등)
3 cycle_discount 주기 할인 적용
4 cycle_additional_fee 추가 비용 적용
5 recurring_fee 매회차 추가비용 (모든 할인 적용 후)
10 coupon 구독 상품 금액 쿠폰
11 shipping_coupon 배송비 쿠폰

에러 코드

공통 에러

인증·권한 관련 에러는 에러 코드표를 참고합니다.

코드 메시지 대처 방법
ORDER_SUBSCRIPTION_INVALID 구독결제 정보가 올바르지 않습니다. 구독 계약 ID를 확인합니다
SUBSCRIPTION_ADJUSTMENT_PAYMENT_COMPLETED 이미 결제가 완료된 회차입니다. 가격조정을 할 수 없습니다. 미결제 회차에 대해서만 조정합니다
SUBSCRIPTION_ADJUSTMENT_NEGATIVE_PRICE 회차 가격 조정으로 인해 최종 결제 금액이 음수가 될 수 없습니다. 조정 금액을 다시 확인합니다

함께 보기