Mall StoryDevelopers
Mall Story
관리자 API회원 관리소유자 토큰

회원 적립금

회원 한 명의 적립금 잔액 · 내역을 읽고, 지급 · 차감합니다.

업데이트됨 10.13 — 쿠폰 · 회원 적립금 · 상품 배지 API 를 열었습니다

무엇인가요

쇼핑몰 관리자 > 회원 > 회원 상세의 적립금 창과 같은 작업입니다. 잔액은 회원의 point(회원 상세)이고, 오간 기록이 내역에 쌓입니다. 둘은 한 번에 함께 바뀝니다.

  • 손으로 할 수 있는 것은 지급(MANUAL_EARN) · 차감(MANUAL_DEDUCT) 둘뿐입니다. 주문적립 · 주문사용 · 취소 · 소멸은 주문이 하는 일이라 열지 않습니다.
  • 내역은 지우지 않습니다. 잘못 준 적립금은 차감으로 덮습니다.
  • 지급 · 차감은 쇼핑몰 관리자 > 기록의 개인정보 처리 기록에 '앱 {client_id}' 로 남습니다.
같은 요청을 두 번 보내면 두 번 지급됩니다
시간 초과 등으로 응답을 못 받았다면 다시 보내기 전에 내역(GET)에서 그 사유 · 금액의 줄이 생겼는지 먼저 보세요.
요청경로바로가기권한
GET/members/{member_unique}/points잔액 · 내역customers:read
POST/members/{member_unique}/points지급 · 차감customers:write

잔액 · 내역

GEThttps://api.mallstory.kr/v1/shop/{shop_unique}/members/{member_unique}/points

권한 customers:read

쿼리형식설명
limitnumber내역 줄 수 1~200. 비우면 50. 최근 것이 위
bash요청
curl 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/members/6aa7b632a6b9163860b02ebc/points?limit=2' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'
json200 OK
{
  "member_unique": "6aa7b632a6b9163860b02ebc",
  "balance": 1000,
  "items": [
    {
      "point_unique": "6acdf41e4555cab633c38cb1",
      "kind": "MANUAL_EARN",
      "amount": 1000,
      "balance": 1000,
      "reason": "리뷰 이벤트 당첨",
      "by_login_id": "test3",
      "created": "2026-10-13T09:04:30.234Z"
    }
  ]
}

응답 필드

필드형식설명
balancenumber지금 잔액(원)
items[].point_uniquestring내역 한 줄의 키
items[].kindstring무엇 때문에 오갔나 코드값
items[].amountnumber쌓이면 양수, 빠지면 음수
items[].balancenumber이 줄을 적은 뒤의 잔액
items[].reasonstring사유
items[].by_login_idstring처리한 관리자 아이디(앱으로 한 일은 토큰을 승인한 소유자). 저절로 오간 줄은 빈 글자
items[].createdISO처리 시각

오류

상태code언제
400InvalidParameterValuelimit 범위 밖 · 회원 키 모양이 아님
404MemberNotExist이 쇼핑몰 회원이 아니거나 탈퇴
401MissingLoginSessionAuthorization 헤더에 Bearer 토큰이 없음
401InvalidAccessToken토큰이 틀리거나 만료 · 폐기됨
403InsufficientScope토큰에 customers:read 가 없음

지급 · 차감

POSThttps://api.mallstory.kr/v1/shop/{shop_unique}/members/{member_unique}/points

권한 customers:write

요청 본문

필드형식설명
kind필수stringMANUAL_EARN 지급 · MANUAL_DEDUCT 차감 코드값
amount필수number1 이상 정수(원). 한 번에 10,000,000원까지. 차감도 양수로 보냄
reason필수string사유. 내역 · 개인정보 처리 기록에 남음
bash요청
curl -X POST 'https://api.mallstory.kr/v1/shop/6a9515bdcb3ab5179ba767ad/members/6aa7b632a6b9163860b02ebc/points' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...' \
  -H 'Content-Type: application/json' \
  -d '{"kind":"MANUAL_EARN","amount":1000,"reason":"리뷰 이벤트 당첨"}'
json201 Created
{
  "member_unique": "6aa7b632a6b9163860b02ebc",
  "balance": 1000,
  "point_unique": "6acdf41e4555cab633c38cb1"
}
json요청 — 차감
{
  "kind": "MANUAL_DEDUCT",
  "amount": 1000,
  "reason": "리뷰 이벤트 중복 지급 회수"
}
json201 Created
{
  "member_unique": "6aa7b632a6b9163860b02ebc",
  "balance": 0,
  "point_unique": "6acdf41e4555cab633c38cb7"
}
json403 — 잔액보다 많이 차감
{
  "code": "PointExceed",
  "message": "회원의 적립금이 모자랍니다.",
  "request_id": "req_a660ab0ad2f04693a941510ebc287560"
}
json400 — 손으로 할 수 없는 갈래
{
  "code": "InvalidParameterValue",
  "message": "kind 는 MANUAL_EARN · MANUAL_DEDUCT 중 하나입니다.",
  "request_id": "req_06c681301bfe42e294dad5841faa1090"
}

오류

상태code언제
400InvalidParameterValuekind · amount · reason 이 없거나 틀림
403PointExceed차감할 금액이 잔액보다 많음 — 잔액은 그대로
404MemberNotExist이 쇼핑몰 회원이 아니거나 탈퇴
401MissingLoginSessionAuthorization 헤더에 Bearer 토큰이 없음
401InvalidAccessToken토큰이 틀리거나 만료 · 폐기됨
403InsufficientScope토큰에 customers:write 가 없음