관리자 API회원 관리소유자 토큰

회원 등급

회원 등급과 등급 할인 · 적립금 규칙을 만들고 고치고 지웁니다(회원등급 설정).

무엇인가요

쇼핑몰 관리자 > 회원 > 회원등급 설정과 같은 작업입니다. 등급마다 할인 · 적립금 규칙을 두고, 회원의 level_unique 로 등급을 겁니다(회원 수정). 등급 할인가는 쇼핑몰 조회의 final_price 에 바로 반영됩니다.

등급은 최대 30개입니다. 레벨(level)이 높을수록 높은 등급이고, 같은 레벨은 둘 수 없습니다.
비회원 등급(is_guest, 레벨 0) — 로그인하지 않은 손님의 등급입니다. 지울 수 없고 이름만 고칠 수 있습니다(할인 · 적립은 늘 비어 있음).
기본 등급(is_default) — 새로 가입한 회원이 받는 등급입니다. 지울 수 없습니다.
회원이 쓰고 있는 등급은 회원을 다른 등급으로 옮긴 뒤에 지울 수 있습니다.

요청	경로	바로가기	권한
GET	`/levels`	목록	`customers:read`
POST	`/levels`	생성	`customers:write`
PATCH	`/levels/{level_unique}`	수정	`customers:write`
DELETE	`/levels/{level_unique}`	삭제	`customers:write`

GEThttps://api.mallstory.kr/v1/shop/{shop_unique}/levels

권한 customers:read

bash요청

curl 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/levels' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'

json200 OK (두 줄만)

{
  "items": [
    {
      "name": "비회원",
      "level": 0,
      "sort_order": 0,
      "is_default": false,
      "is_guest": true,
      "discount": {
        "enabled": false,
        "threshold": 0,
        "value": 0,
        "unit": "WON",
        "max_amount": 0
      },
      "reward": {
        "enabled": false,
        "threshold": 0,
        "value": 0,
        "unit": "WON",
        "max_amount": 0
      },
      "level_unique": "6aa7ca8790b69e4421dc7de2",
      "created": "2026-09-14T10:20:55.701Z",
      "updated": "2026-09-21T08:39:39.809Z",
      "member_count": 0
    },
    {
      "name": "일반회원",
      "sort_order": 1,
      "is_default": true,
      "discount": {
        "enabled": false,
        "threshold": 0,
        "value": 25,
        "unit": "PERCENT"
      },
      "reward": {
        "enabled": false,
        "threshold": 0,
        "value": 15,
        "unit": "PERCENT"
      },
      "level": 1,
      "is_guest": false,
      "level_unique": "6a9fbdedfc6e77ca0e475eb2",
      "created": "2026-09-08T07:49:01.528Z",
      "updated": "2026-09-15T02:13:06.844Z",
      "member_count": 2
    }
  ]
}

응답 필드

필드	형식	설명
`level_unique`	string	등급 키. 회원의 level_unique 에 넣는 값
`name`	string	등급 이름
`level`	number	레벨 — 0 비회원 · 1 이상 회원(높을수록 높은 등급)
`sort_order`	number	목록 차례
`is_guest`	boolean	비회원 등급인가
`is_default`	boolean	새로 가입한 회원이 받는 등급인가
`discount.enabled`	boolean	등급 할인을 주는가
`discount.threshold`	number	이 금액(원) 이상 살 때만. 0 이면 조건 없음
`discount.value`	number	값 — unit 이 PERCENT 면 %(정수), WON 이면 원
`discount.unit`	string	단위 코드값
`discount.max_amount`	number	한 번에 줄 수 있는 최대 금액(원). 0 이면 제한 없음
`reward.enabled`	boolean	등급 적립금을 주는가
`reward.threshold`	number	이 금액(원) 이상 살 때만. 0 이면 조건 없음
`reward.value`	number	값 — unit 이 PERCENT 면 %(정수), WON 이면 원
`reward.unit`	string	단위 코드값
`reward.max_amount`	number	한 번에 줄 수 있는 최대 금액(원). 0 이면 제한 없음
`member_count`	number	이 등급의 회원 수
`created`	ISO	생성 시각
`updated`	ISO	마지막 수정 시각

오류

상태	code	언제
401	`MissingLoginSession`	Authorization 헤더에 Bearer 토큰이 없음
401	`InvalidAccessToken`	토큰이 틀리거나 만료 · 폐기됨
403	`InsufficientScope`	토큰에 customers:read 가 없음

생성

POSThttps://api.mallstory.kr/v1/shop/{shop_unique}/levels

권한 customers:write

요청 본문

필드	형식	설명
`name`필수	string	등급 이름(30자까지)
`level`	number	레벨(1 이상, 다른 등급과 겹치면 안 됨). 비우면 가장 높은 레벨 + 1
`discount`	object	등급 할인(아래 키). 비우면 쓰지 않음
`discount.enabled`	boolean	등급 할인을 주는가
`discount.threshold`	number	이 금액(원) 이상 살 때만. 0 이면 조건 없음
`discount.value`	number	값 — unit 이 PERCENT 면 %(정수), WON 이면 원
`discount.unit`	string	단위 코드값
`discount.max_amount`	number	한 번에 줄 수 있는 최대 금액(원). 0 이면 제한 없음
`reward`	object	등급 적립금(아래 키). 비우면 쓰지 않음
`reward.enabled`	boolean	등급 적립금을 주는가
`reward.threshold`	number	이 금액(원) 이상 살 때만. 0 이면 조건 없음
`reward.value`	number	값 — unit 이 PERCENT 면 %(정수), WON 이면 원
`reward.unit`	string	단위 코드값
`reward.max_amount`	number	한 번에 줄 수 있는 최대 금액(원). 0 이면 제한 없음

bash요청

curl -X POST 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/levels' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...' \
  -H 'Content-Type: application/json' \
  -d '{"name":"골드","level":5,"discount":{"enabled":true,"threshold":30000,"value":10,"unit":"PERCENT","max_amount":5000},"reward":{"enabled":true,"threshold":0,"value":2,"unit":"PERCENT"}}'

json201 Created

{
  "name": "골드",
  "level": 5,
  "sort_order": 5,
  "is_default": false,
  "is_guest": false,
  "discount": {
    "enabled": true,
    "threshold": 30000,
    "value": 10,
    "unit": "PERCENT",
    "max_amount": 5000
  },
  "reward": {
    "enabled": true,
    "threshold": 0,
    "value": 2,
    "unit": "PERCENT",
    "max_amount": 0
  },
  "level_unique": "6accb438c2ca90eedea62121",
  "created": "2026-10-12T10:19:36.716Z",
  "updated": "2026-10-12T10:19:36.716Z",
  "member_count": 0
}

위 예시는 '3만 원 이상 살 때 10% 할인(최대 5,000원), 2% 적립' 인 골드 등급입니다.

json400 — 이미 쓰는 레벨

{
  "code": "LevelDuplicated",
  "message": "레벨 5은(는) 이미 [골드] 등급이 쓰고 있습니다. 다른 값을 입력하세요."
}

오류

상태	code	언제
400	`LevelDuplicated`	다른 등급이 쓰는 레벨
400	`LevelLimit`	등급이 30개를 넘음
400	`InvalidParameterValue`	이름이 없음 · 레벨이 0 이하 · 비율이 100% 초과 · 음수
401	`MissingLoginSession`	Authorization 헤더에 Bearer 토큰이 없음
401	`InvalidAccessToken`	토큰이 틀리거나 만료 · 폐기됨
403	`InsufficientScope`	토큰에 customers:write 가 없음

수정

PATCHhttps://api.mallstory.kr/v1/shop/{shop_unique}/levels/{level_unique}

권한 customers:write

보낸 필드만 바뀝니다. discount · reward 도 안의 키 하나만 보내면 나머지는 그대로입니다. 필드는 생성과 같습니다.

bash요청

curl -X PATCH 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/levels/6accb438c2ca90eedea62121' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...' \
  -H 'Content-Type: application/json' \
  -d '{"discount":{"value":15}}'

json200 OK

{
  "name": "골드",
  "level": 5,
  "sort_order": 5,
  "is_default": false,
  "is_guest": false,
  "discount": {
    "enabled": true,
    "threshold": 30000,
    "value": 15,
    "unit": "PERCENT",
    "max_amount": 5000
  },
  "reward": {
    "enabled": true,
    "threshold": 0,
    "value": 2,
    "unit": "PERCENT",
    "max_amount": 0
  },
  "level_unique": "6accb438c2ca90eedea62121",
  "created": "2026-10-12T10:19:36.716Z",
  "updated": "2026-10-12T10:19:37.726Z",
  "member_count": 0
}

할인율만 10% → 15% 로 바뀌고 조건 · 최대 금액 · 적립금은 그대로입니다.

비회원 등급은 이름만 바뀝니다 — discount · reward 를 보내도 늘 비어 있습니다(400 이 아님).

오류

상태	code	언제
400	`LevelDuplicated`	다른 등급이 쓰는 레벨로 바꿈
404	`LevelNotExist`	없는 키이거나 지운 등급
401	`MissingLoginSession`	Authorization 헤더에 Bearer 토큰이 없음
401	`InvalidAccessToken`	토큰이 틀리거나 만료 · 폐기됨
403	`InsufficientScope`	토큰에 customers:write 가 없음

삭제

DELETEhttps://api.mallstory.kr/v1/shop/{shop_unique}/levels/{level_unique}

권한 customers:write

소프트 삭제입니다 — 지난 주문에 그때의 등급이 남습니다.

bash요청

curl -X DELETE 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/levels/6accb438c2ca90eedea62121' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'

json200 OK

{
  "deleted": true,
  "level_unique": "6accb438c2ca90eedea62121"
}

json400 — 회원이 쓰는 등급

{
  "code": "LevelInUse",
  "message": "이 등급을 쓰는 회원이 1명 있습니다. 다른 등급으로 옮긴 뒤에 지워 주세요."
}

json400 — 기본 등급

{
  "code": "LevelDefaultLocked",
  "message": "기본 등급은 지울 수 없습니다. 새로 가입한 회원이 받을 등급입니다."
}

json400 — 비회원 등급

{
  "code": "LevelGuestLocked",
  "message": "비회원 등급은 지울 수 없습니다. 로그인하지 않은 손님에게 적용하는 등급입니다."
}

오류

상태	code	언제
400	`LevelInUse`	이 등급을 쓰는 회원이 있음 — 다른 등급으로 옮긴 뒤 지움
400	`LevelDefaultLocked`	기본 등급
400	`LevelGuestLocked`	비회원 등급
404	`LevelNotExist`	없는 키이거나 이미 지운 등급
401	`MissingLoginSession`	Authorization 헤더에 Bearer 토큰이 없음
401	`InvalidAccessToken`	토큰이 틀리거나 만료 · 폐기됨
403	`InsufficientScope`	토큰에 customers:write 가 없음

무엇인가요#

목록#

응답 필드

오류

생성#

요청 본문

오류

수정#

오류

삭제#

오류

무엇인가요

목록

생성

수정

삭제