관리자 API템플릿 관리소유자 토큰

택배배송

택배배송 템플릿 — 배송비 방식 · 택배사 · 출고지 · 반품지를 관리합니다.

무엇인가요

택배배송 템플릿입니다. 배송비 방식과 택배사 · 출고지 · 반품지를 정합니다.

항목	내용
권한	읽기 `products:read` · 쓰기 `products:write` (소유자 토큰)
상품에서 쓰는 곳	상품의 `delivery` — `[{"method": "…", "template_id": "…"}]`
관리자 화면	상품 > 템플릿 관리 — 같은 검증 · 같은 저장

요청	경로	바로가기
GET	`https://api.mallstory.kr/v1/shop/{shop_unique}/templates/delivery?method=PARCEL`	목록
GET	`https://api.mallstory.kr/v1/shop/{shop_unique}/templates/delivery/{template_unique}`	상세
POST	`https://api.mallstory.kr/v1/shop/{shop_unique}/templates/delivery`	생성
PATCH	`https://api.mallstory.kr/v1/shop/{shop_unique}/templates/delivery/{template_unique}`	수정
DELETE	`https://api.mallstory.kr/v1/shop/{shop_unique}/templates/delivery/{template_unique}`	삭제

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

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

쿼리	형식	설명
`method`필수	string	`PARCEL` — 빼면 배송 템플릿 넷이 모두 나옵니다
`sort`	string	정렬 키. 빼면 등록일시 최신순(관리자 목록의 기본과 같음) 코드값
`order`	string	정렬 방향. 빼면 `name` 는 오름차순, 시각은 최신순. `sort` 와 함께 보냅니다 코드값

bash요청

curl 'https://api.mallstory.kr/v1/shop/{shop_unique}/templates/delivery?method=PARCEL' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'

json200 OK

{
  "items": [
    {
      "template_unique": "6acca48ec2ca90eedea620f6",
      "name": "기본 택배",
      "method": "PARCEL",
      "is_default": false,
      "fee_type": "CONDITIONAL_FREE",
      "base_fee": 3000,
      "free_condition_amount": 50000,
      "pay_type": "PREPAID",
      "unit_quantity": 0,
      "range_count": 2,
      "range_tiers": [],
      "extra_fee": {
        "jeju": 3000,
        "island": 5000
      },
      "return_fee": 3000,
      "exchange_fee": 6000,
      "courier_id": null,
      "outbound_address": null,
      "return_address": null,
      "notice": "평일 오후 2시 이전 주문은 당일 출고됩니다.",
      "delivery_area": null,
      "install": null,
      "pickup": null,
      "quick": null,
      "used_count": 0,
      "created": "2026-10-12T09:12:46.879Z",
      "updated": "2026-10-12T09:12:46.879Z"
    }
  ]
}

상세

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

bash요청

curl 'https://api.mallstory.kr/v1/shop/{shop_unique}/templates/delivery/6acca48ec2ca90eedea620f6' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'

json200 OK

{
  "template_unique": "6acca48ec2ca90eedea620f6",
  "name": "기본 택배",
  "method": "PARCEL",
  "is_default": false,
  "fee_type": "CONDITIONAL_FREE",
  "base_fee": 3000,
  "free_condition_amount": 50000,
  "pay_type": "PREPAID",
  "unit_quantity": 0,
  "range_count": 2,
  "range_tiers": [],
  "extra_fee": {
    "jeju": 3000,
    "island": 5000
  },
  "return_fee": 3000,
  "exchange_fee": 6000,
  "courier_id": null,
  "outbound_address": null,
  "return_address": null,
  "notice": "평일 오후 2시 이전 주문은 당일 출고됩니다.",
  "delivery_area": null,
  "install": null,
  "pickup": null,
  "quick": null
}

응답 필드

필드	형식	설명
`template_unique`	string	키. 상세 · 수정 · 삭제 경로에 넣습니다
`name`	string	템플릿명
`method`	string	배송 방법. 이 쪽은 아래 값으로 고정입니다 코드값
`is_default`	boolean	이 배송 방법의 기본 템플릿인가(상품 등록 때 먼저 고름)
`fee_type`	string	배송비를 매기는 방식. 방식에 따라 아래 금액 칸 가운데 쓰이는 칸이 달라집니다 코드값
`base_fee`	number	기본 배송비(원)
`free_condition_amount`	number	이 금액 이상이면 무료(조건부 무료)
`pay_type`	string	배송비를 주문할 때 내는가, 받을 때 내는가, 손님이 고르는가 코드값
`unit_quantity`	number	수량별 — 몇 개마다 base_fee 를 더 받는가
`range_count`	number	구간별 — 구간 수(2 또는 3)
`range_tiers`	array	구간별 — 구간마다 `{up_to, extra_fee}`(이 수량까지 · 더 받는 배송비)
`extra_fee`	object	제주 · 도서산간 추가 배송비 `{jeju, island}`
`return_fee`	number	반품 배송비. 0 이면 "무료반품" 으로 안내됩니다
`exchange_fee`	number	교환 배송비. 0 이면 "무료교환" 으로 안내됩니다
`notice`	string	배송안내 문구(상품 상세에 나옴)
`courier_id`	string	택배사 키
`outbound_address`	object	출고지 `{zipcode, address1, address2}`
`return_address`	object	반품 · 교환지 `{zipcode, address1, address2}`
`delivery_area`	null	택배배송에서는 null
`install`	null	택배배송에서는 null
`pickup`	null	택배배송에서는 null
`quick`	null	택배배송에서는 null
`created`	ISO	생성 시각
`updated`	ISO	마지막 수정 시각
`used_count`	number	이 템플릿을 쓰는 상품 수(목록에만)

생성

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

요청 본문

필드	형식	설명
`name`필수	string	템플릿명
`method`필수	string	배송 방법. 이 쪽은 아래 값으로 고정입니다 코드값
`is_default`	boolean	이 배송 방법의 기본 템플릿인가(상품 등록 때 먼저 고름)
`fee_type`필수	string	배송비를 매기는 방식. 방식에 따라 아래 금액 칸 가운데 쓰이는 칸이 달라집니다 코드값
`base_fee`	number	기본 배송비(원)
`free_condition_amount`	number	이 금액 이상이면 무료(조건부 무료)
`pay_type`	string	배송비를 주문할 때 내는가, 받을 때 내는가, 손님이 고르는가 코드값
`unit_quantity`	number	수량별 — 몇 개마다 base_fee 를 더 받는가
`range_count`	number	구간별 — 구간 수(2 또는 3)
`range_tiers`	array	구간별 — 구간마다 `{up_to, extra_fee}`(이 수량까지 · 더 받는 배송비)
`extra_fee`	object	제주 · 도서산간 추가 배송비 `{jeju, island}`
`return_fee`	number	반품 배송비. 0 이면 "무료반품" 으로 안내됩니다
`exchange_fee`	number	교환 배송비. 0 이면 "무료교환" 으로 안내됩니다
`notice`	string	배송안내 문구(상품 상세에 나옴)
`courier_id`	string	택배사 키
`outbound_address`	object	출고지 `{zipcode, address1, address2}`
`return_address`	object	반품 · 교환지 `{zipcode, address1, address2}`

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":"PARCEL","fee_type":"CONDITIONAL_FREE","base_fee":3000,"free_condition_amount":50000,"pay_type":"PREPAID","extra_fee":{"jeju":3000,"island":5000},"return_fee":3000,"exchange_fee":6000,"notice":"평일 오후 2시 이전 주문은 당일 출고됩니다."}'

json201 Created

{
  "template_unique": "6acca48ec2ca90eedea620f6"
}

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

수정

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

보낸 필드만 바뀝니다. 나머지는 지금 값 그대로입니다. 필드는 생성과 같습니다. 배송비만 바꾸려면 base_fee 만 보내면 됩니다.

bash요청

curl -X PATCH 'https://api.mallstory.kr/v1/shop/{shop_unique}/templates/delivery/6acca48ec2ca90eedea620f6' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...' \
  -H 'Content-Type: application/json' \
  -d '{"base_fee":3500}'

json200 OK

{
  "template_unique": "6acca48ec2ca90eedea620f6"
}

json수정 뒤 상세

{
  "template_unique": "6acca48ec2ca90eedea620f6",
  "name": "기본 택배",
  "method": "PARCEL",
  "is_default": false,
  "fee_type": "CONDITIONAL_FREE",
  "base_fee": 3500,
  "free_condition_amount": 50000,
  "pay_type": "PREPAID",
  "unit_quantity": 0,
  "range_count": 2,
  "range_tiers": [],
  "extra_fee": {
    "jeju": 3000,
    "island": 5000
  },
  "return_fee": 3000,
  "exchange_fee": 6000,
  "courier_id": null,
  "outbound_address": null,
  "return_address": null,
  "notice": "평일 오후 2시 이전 주문은 당일 출고됩니다.",
  "delivery_area": null,
  "install": null,
  "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/6acca48ec2ca90eedea620f6' \
  -H 'Authorization: Bearer msat_8Hk2wQ7...'

json200 OK

{
  "affected": 0
}

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

오류

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

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

무엇인가요#

목록#

상세#

응답 필드

생성#

요청 본문

수정#

삭제#

오류#

무엇인가요

목록

상세

생성

수정

삭제

오류