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=QUICK목록
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=QUICK

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

쿼리형식설명
method필수stringQUICK — 빼면 배송 템플릿 넷이 모두 나옵니다
sortstring정렬 키. 빼면 등록일시 최신순(관리자 목록의 기본과 같음) 코드값
orderstring정렬 방향. 빼면 name 는 오름차순, 시각은 최신순. sort 와 함께 보냅니다 코드값
bash요청
curl 'https://api.mallstory.kr/v1/shop/{shop_unique}/templates/delivery?method=QUICK' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'
json200 OK
{
  "items": [
    {
      "template_unique": "6acca48fc2ca90eedea620f8",
      "name": "서울 퀵",
      "method": "QUICK",
      "is_default": false,
      "fee_type": "PAID",
      "base_fee": 0,
      "free_condition_amount": 0,
      "pay_type": "COLLECT",
      "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"
            ],
            "extra_fee": 0
          }
        ]
      },
      "install": null,
      "pickup": null,
      "quick": {
        "collect_notice": "거리별 착불(기사님께 결제)",
        "time_use": true,
        "start": "10:00",
        "end": "17:00",
        "days": [
          "MON",
          "TUE",
          "WED",
          "THU",
          "FRI"
        ]
      },
      "used_count": 0,
      "created": "2026-10-12T09:12:47.136Z",
      "updated": "2026-10-12T09:12:47.136Z"
    }
  ]
}

상세

GEThttps://api.mallstory.kr/v1/shop/{shop_unique}/templates/delivery/{template_unique}
bash요청
curl 'https://api.mallstory.kr/v1/shop/{shop_unique}/templates/delivery/6acca48fc2ca90eedea620f8' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'
json200 OK
{
  "template_unique": "6acca48fc2ca90eedea620f8",
  "name": "서울 퀵",
  "method": "QUICK",
  "is_default": false,
  "fee_type": "PAID",
  "base_fee": 0,
  "free_condition_amount": 0,
  "pay_type": "COLLECT",
  "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"
        ],
        "extra_fee": 0
      }
    ]
  },
  "install": null,
  "pickup": null,
  "quick": {
    "collect_notice": "거리별 착불(기사님께 결제)",
    "time_use": true,
    "start": "10:00",
    "end": "17:00",
    "days": [
      "MON",
      "TUE",
      "WED",
      "THU",
      "FRI"
    ]
  }
}

응답 필드

필드형식설명
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배송안내 문구(상품 상세에 나옴)
quickobject퀵 설정 — collect_notice(착불 예상요금 안내) · time_use · start · end(주문가능 시간 HH:MM) · days(주문을 받는 요일) 코드값
delivery_areaobject배송가능 지역(직접배송과 같은 모양)
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배송안내 문구(상품 상세에 나옴)
quickobject퀵 설정 — collect_notice(착불 예상요금 안내) · time_use · start · end(주문가능 시간 HH:MM) · days(주문을 받는 요일) 코드값
delivery_areaobject배송가능 지역(직접배송과 같은 모양)
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":"QUICK","fee_type":"PAID","base_fee":0,"pay_type":"COLLECT","quick":{"collect_notice":"거리별 착불(기사님께 결제)","time_use":true,"start":"10:00","end":"17:00","days":["MON","TUE","WED","THU","FRI"]},"delivery_area":{"use":true,"zones":[{"codes":["11"],"extra_fee":0}]}}'
json201 Created
{
  "template_unique": "6acca48fc2ca90eedea620f8"
}

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

수정

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

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

bash요청
curl -X PATCH 'https://api.mallstory.kr/v1/shop/{shop_unique}/templates/delivery/6acca48fc2ca90eedea620f8' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...' \
  -H 'Content-Type: application/json' \
  -d '{"quick":{"collect_notice":"거리별 착불","time_use":true,"start":"09:00","end":"18:00","days":["MON","TUE","WED","THU","FRI","SAT"]}}'
json200 OK
{
  "template_unique": "6acca48fc2ca90eedea620f8"
}
json수정 뒤 상세
{
  "template_unique": "6acca48fc2ca90eedea620f8",
  "name": "서울 퀵",
  "method": "QUICK",
  "is_default": false,
  "fee_type": "PAID",
  "base_fee": 0,
  "free_condition_amount": 0,
  "pay_type": "COLLECT",
  "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"
        ],
        "extra_fee": 0
      }
    ]
  },
  "install": null,
  "pickup": null,
  "quick": {
    "collect_notice": "거리별 착불",
    "time_use": true,
    "start": "09:00",
    "end": "18:00",
    "days": [
      "MON",
      "TUE",
      "WED",
      "THU",
      "FRI",
      "SAT"
    ]
  }
}

삭제

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/6acca48fc2ca90eedea620f8' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'
json200 OK
{
  "affected": 0
}

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

오류

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

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