Mall StoryDevelopers
Mall Story
관리자 API템플릿 관리소유자 토큰

직접배송

직접배송 템플릿 — 배송비 · 배송가능 지역 · 상품 설치를 관리합니다.

업데이트됨 10.13 — 목록의 기본 순서를 관리자 목록에 맞췄습니다

무엇인가요

직접배송(판매자가 직접 배달) 템플릿입니다. 배송비와 배송가능 지역 · 상품 설치를 정합니다. 수량별 · 구간별 배송비와 착불은 없습니다.

항목내용
권한읽기 products:read · 쓰기 products:write (소유자 토큰)
상품에서 쓰는 곳상품의 delivery — [{"method": "…", "template_id": "…"}]
관리자 화면상품 > 템플릿 관리 — 같은 검증 · 같은 저장
요청경로바로가기
GEThttps://api.mallstory.kr/v1/shop/{shop_unique}/templates/delivery?method=DIRECT목록
GEThttps://api.mallstory.kr/v1/shop/{shop_unique}/templates/delivery/{template_unique}상세
POSThttps://api.mallstory.kr/v1/shop/{shop_unique}/templates/delivery생성
PATCHhttps://api.mallstory.kr/v1/shop/{shop_unique}/templates/delivery/{template_unique}수정
DELETEhttps://api.mallstory.kr/v1/shop/{shop_unique}/templates/delivery/{template_unique}삭제

목록

GEThttps://api.mallstory.kr/v1/shop/{shop_unique}/templates/delivery?method=DIRECT

이 쇼핑몰의 이 배송 방법의 템플릿 전부입니다(쪽 나눔 없음). 줄마다 이 템플릿을 쓰는 상품 수 used_count 가 붙습니다 — 관리자 목록의 "적용상품" 칸과 같습니다.

쿼리형식설명
method필수stringDIRECT — 빼면 배송 템플릿 넷이 모두 나옵니다
sortstring정렬 키. 빼면 등록일시 최신순(관리자 목록의 기본과 같음) 코드값
orderstring정렬 방향. 빼면 name 는 오름차순, 시각은 최신순. sort 와 함께 보냅니다 코드값
bash요청
curl 'https://api.mallstory.kr/v1/shop/{shop_unique}/templates/delivery?method=DIRECT' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'
json200 OK
{
  "items": [
    {
      "template_unique": "6acca48fc2ca90eedea620f7",
      "name": "직접배송 수도권",
      "method": "DIRECT",
      "is_default": false,
      "fee_type": "FREE",
      "base_fee": 0,
      "free_condition_amount": 0,
      "pay_type": "PREPAID",
      "unit_quantity": 0,
      "range_count": 2,
      "range_tiers": [],
      "extra_fee": {
        "jeju": 0,
        "island": 0
      },
      "return_fee": 0,
      "exchange_fee": 0,
      "courier_id": null,
      "outbound_address": null,
      "return_address": null,
      "notice": "",
      "delivery_area": {
        "use": true,
        "zones": [
          {
            "codes": [
              "11",
              "41",
              "28"
            ],
            "extra_fee": 0
          }
        ]
      },
      "install": {
        "use": true,
        "type": "FREE",
        "notice": "설치 기사가 방문합니다."
      },
      "pickup": null,
      "quick": null,
      "used_count": 0,
      "created": "2026-10-12T09:12:47.008Z",
      "updated": "2026-10-12T09:12:47.008Z"
    }
  ]
}

상세

GEThttps://api.mallstory.kr/v1/shop/{shop_unique}/templates/delivery/{template_unique}
bash요청
curl 'https://api.mallstory.kr/v1/shop/{shop_unique}/templates/delivery/6acca48fc2ca90eedea620f7' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'
json200 OK
{
  "template_unique": "6acca48fc2ca90eedea620f7",
  "name": "직접배송 수도권",
  "method": "DIRECT",
  "is_default": false,
  "fee_type": "FREE",
  "base_fee": 0,
  "free_condition_amount": 0,
  "pay_type": "PREPAID",
  "unit_quantity": 0,
  "range_count": 2,
  "range_tiers": [],
  "extra_fee": {
    "jeju": 0,
    "island": 0
  },
  "return_fee": 0,
  "exchange_fee": 0,
  "courier_id": null,
  "outbound_address": null,
  "return_address": null,
  "notice": "",
  "delivery_area": {
    "use": true,
    "zones": [
      {
        "codes": [
          "11",
          "41",
          "28"
        ],
        "extra_fee": 0
      }
    ]
  },
  "install": {
    "use": true,
    "type": "FREE",
    "notice": "설치 기사가 방문합니다."
  },
  "pickup": null,
  "quick": null
}

응답 필드

필드형식설명
template_uniquestring키. 상세 · 수정 · 삭제 경로에 넣습니다
namestring템플릿명
methodstring배송 방법. 이 쪽은 아래 값으로 고정입니다 코드값
is_defaultboolean이 배송 방법의 기본 템플릿인가(상품 등록 때 먼저 고름)
fee_typestring배송비를 매기는 방식. 방식에 따라 아래 금액 칸 가운데 쓰이는 칸이 달라집니다 코드값
base_feenumber기본 배송비(원)
free_condition_amountnumber이 금액 이상이면 무료(조건부 무료)
pay_typestring배송비를 주문할 때 내는가, 받을 때 내는가, 손님이 고르는가 코드값
unit_quantitynumber수량별 — 몇 개마다 base_fee 를 더 받는가
range_countnumber구간별 — 구간 수(2 또는 3)
range_tiersarray구간별 — 구간마다 {up_to, extra_fee}(이 수량까지 · 더 받는 배송비)
extra_feeobject제주 · 도서산간 추가 배송비 {jeju, island}
return_feenumber반품 배송비. 0 이면 "무료반품" 으로 안내됩니다
exchange_feenumber교환 배송비. 0 이면 "무료교환" 으로 안내됩니다
noticestring배송안내 문구(상품 상세에 나옴)
delivery_areaobject배송가능 지역 — use · zones[codes(지역 코드 — 시도 2자리 11 서울 · 시군구 5자리 · 읍면동 10자리) · extra_fee(그 권역의 추가 배송비)]
installobject상품 설치 — use · type(설치를 누가 · 어떻게 하는가) · notice(손님에게 보일 설치 안내) 코드값
courier_idstring택배사 키 — 택배배송에서만, 다른 배송 방법은 null
outbound_addressobject | null출고지 — 택배배송에서만
return_addressobject | null반품 · 교환지 — 택배배송에서만
delivery_areaobject | null배송가능 지역 — 직접배송 · 퀵배송에서만
installobject | null상품 설치 — 직접배송에서만
pickupobject | null매장 · 영업시간 — 방문수령에서만
quickobject | null퀵 설정 — 퀵배송에서만
createdISO생성 시각
updatedISO마지막 수정 시각
used_countnumber이 템플릿을 쓰는 상품 수(목록에만)

생성

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

요청 본문

필드형식설명
name필수string템플릿명
method필수string배송 방법. 이 쪽은 아래 값으로 고정입니다 코드값
is_defaultboolean이 배송 방법의 기본 템플릿인가(상품 등록 때 먼저 고름)
fee_type필수string배송비를 매기는 방식. 방식에 따라 아래 금액 칸 가운데 쓰이는 칸이 달라집니다 코드값
base_feenumber기본 배송비(원)
free_condition_amountnumber이 금액 이상이면 무료(조건부 무료)
pay_typestring배송비를 주문할 때 내는가, 받을 때 내는가, 손님이 고르는가 코드값
unit_quantitynumber수량별 — 몇 개마다 base_fee 를 더 받는가
range_countnumber구간별 — 구간 수(2 또는 3)
range_tiersarray구간별 — 구간마다 {up_to, extra_fee}(이 수량까지 · 더 받는 배송비)
extra_feeobject제주 · 도서산간 추가 배송비 {jeju, island}
return_feenumber반품 배송비. 0 이면 "무료반품" 으로 안내됩니다
exchange_feenumber교환 배송비. 0 이면 "무료교환" 으로 안내됩니다
noticestring배송안내 문구(상품 상세에 나옴)
delivery_areaobject배송가능 지역 — use · zones[codes(지역 코드 — 시도 2자리 11 서울 · 시군구 5자리 · 읍면동 10자리) · extra_fee(그 권역의 추가 배송비)]
installobject상품 설치 — use · type(설치를 누가 · 어떻게 하는가) · notice(손님에게 보일 설치 안내) 코드값
bash요청
curl -X POST 'https://api.mallstory.kr/v1/shop/{shop_unique}/templates/delivery' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...' \
  -H 'Content-Type: application/json' \
  -d '{"name":"직접배송 수도권","method":"DIRECT","fee_type":"FREE","base_fee":0,"pay_type":"PREPAID","delivery_area":{"use":true,"zones":[{"codes":["11","28","41"],"extra_fee":0}]},"install":{"use":true,"type":"FREE","notice":"설치 기사가 방문합니다."}}'
json201 Created
{
  "template_unique": "6acca48fc2ca90eedea620f7"
}

새 템플릿의 키를 돌려줍니다.

수정

PATCHhttps://api.mallstory.kr/v1/shop/{shop_unique}/templates/delivery/{template_unique}

보낸 필드만 바뀝니다. 나머지는 지금 값 그대로입니다. 필드는 생성과 같습니다. 객체 필드(install 등)는 그 객체를 통째로 보냅니다.

bash요청
curl -X PATCH 'https://api.mallstory.kr/v1/shop/{shop_unique}/templates/delivery/6acca48fc2ca90eedea620f7' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...' \
  -H 'Content-Type: application/json' \
  -d '{"install":{"use":true,"type":"PAID","notice":"설치비 별도"}}'
json200 OK
{
  "template_unique": "6acca48fc2ca90eedea620f7"
}
json수정 뒤 상세
{
  "template_unique": "6acca48fc2ca90eedea620f7",
  "name": "직접배송 수도권",
  "method": "DIRECT",
  "is_default": false,
  "fee_type": "FREE",
  "base_fee": 0,
  "free_condition_amount": 0,
  "pay_type": "PREPAID",
  "unit_quantity": 0,
  "range_count": 2,
  "range_tiers": [],
  "extra_fee": {
    "jeju": 0,
    "island": 0
  },
  "return_fee": 0,
  "exchange_fee": 0,
  "courier_id": null,
  "outbound_address": null,
  "return_address": null,
  "notice": "",
  "delivery_area": {
    "use": true,
    "zones": [
      {
        "codes": [
          "11",
          "41",
          "28"
        ],
        "extra_fee": 0
      }
    ]
  },
  "install": {
    "use": true,
    "type": "PAID",
    "notice": "설치비 별도"
  },
  "pickup": null,
  "quick": null
}

삭제

DELETEhttps://api.mallstory.kr/v1/shop/{shop_unique}/templates/delivery/{template_unique}
bash요청
curl -X DELETE 'https://api.mallstory.kr/v1/shop/{shop_unique}/templates/delivery/6acca48fc2ca90eedea620f7' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'
json200 OK
{
  "affected": 0
}

지운 템플릿을 쓰던 상품은 그 배송 방식이 정리됩니다. affected 는 바뀐 상품 수입니다.

오류

상태code언제
400InvalidParameterValue필수 값이 없거나 값이 올바르지 않음(예: 배송비 유형 값이 올바르지 않습니다)
404DeliveryTemplateNotExist없는 키이거나 지운 템플릿
400InvalidParameterValue권역끼리 지역이 겹침(예: 서울 11 과 종로구 11110)
401MissingLoginSessionAuthorization 헤더에 Bearer 토큰이 없음
401InvalidAccessToken토큰이 틀리거나 만료 · 폐기됨
403InsufficientScope토큰에 products:read · products:write 가 없음

오류 본문은 {code, message, request_id} 이고, message 는 관리자 화면과 같은 문구라 사용자에게 그대로 보여 줄 수 있습니다.