Delivery API

배달 API를 통해 토스 POS로 외부 배달 서비스 주문을 관리할 수 있어요. 주문 API와 함께 활용하여 배달 관련 정보를 토스 POS 주문에 추가할 수 있어요.

배달 주문, 즉 배달 정보가 존재하는 주문은 토스 POS에서 다음과 같은 추가 기능을 제공해요.

• 일반 주문서 대신 배달 주문서를 출력해요. 배달 주문서에는 배달 주소 등 배달 관련 정보를 추가로 표시해요.
• [현황], [결제내역], [매출 리포트] 등 기능에서 배달 주문을 구분하고, 관련 정보를 확인할 수 있어요.

Types

배달 정보 (Delivery)

배달 정보는 주문에 추가로 표시되는 정보로, 외부 배달사에서 제공해요. 이 정보는 아래 그림 설명과 같이 배달 주문서에 표기돼요.

Name	Type	Required	Description	Example
id	String	✅	배달 정보 ID	"42"
merchantId	Long	✅	매장 ID	42
orderId	String	✅	주문 ID	"620000000000000000"
type	String		배달 주문 유형 배달: DELIVERY 포장: PICKUP 매장 식사: HERE	"DELIVERY"
serviceName	String		배달 서비스명	"토스배달"
deliveryType	String		배달 유형 가게 자체배달: STORE 배달사: DELIVERY_COMPANY 배달대행사: AGENCY	"DELIVERY_COMPANY"
deliveryName	String		배달 유형명	"토스배달"
status	DeliveryStatus	✅	배달 상태	"ACCEPTED"
store	DeliveryStore		배달사에서 제공한 매장 정보
recipient	DeliveryRecipient		배달사에서 제공한 주문자 정보 개인정보 보호를 위해 일부 정보는 일정 기간 보관 후 파기됩니다.
paymentMethod	String		결제 방법	"만나서 카드결제"
customerChargedPrice	Long	✅	고객 부담 금액	10000
customerAppliedDiscounts	DeliveryCustomerAppliedDiscount[]		플랫폼 할인 정보 주문의 할인(discounts)와 달리, 배달사에서 제공하는 할인 정보에요. 이 정보는 배달 주문서에는 표시되나, 매장의 결제 내역이나 매출 리포트에는 할인 금액으로 표시되지 않아요.
origin	String		원산지 표기 정보	"커피원두: 브라질산"
preparationTimeMinutes	Int		준비 시간 (분)	10
reservedAt	timestamp		예약 시각	"2025-09-01T00:00:00"
memo	String		요청사항 개인정보 보호를 위해 일부 정보는 일정 기간 보관 후 파기됩니다.	"문 앞에 두고 벨 눌러주세요."

배달 정보 생성 요청 (Delivery.Create)

Name	Type	Required	Description	Example
type	String		배달 주문 유형 배달: DELIVERY 포장: PICKUP 매장 식사: HERE	"DELIVERY"
serviceName	String		배달 서비스명	"토스배달"
deliveryType	String		배달 유형 가게 자체배달: STORE 배달사: DELIVERY_COMPANY 배달대행사: AGENCY
deliveryName	String		배달 유형명	"토스배달"
status	DeliveryStatus	✅	배달 상태	"NEW"
store	DeliveryStore		배달사에서 제공한 매장 정보
recipient	DeliveryRecipient		배달사에서 제공한 주문자 정보
paymentMethod	String		결제 방법	"만나서 카드결제"
customerChargedPrice	Long	✅	고객 부담 금액	10000
customerAppliedDiscounts	DeliveryCustomerAppliedDiscount[]		플랫폼 할인 정보 주문의 할인(discounts)와 달리, 배달사에서 제공하는 할인 정보에요. 이 정보는 배달 주문서에는 표시되나, 매장의 결제 내역이나 매출 리포트에는 할인 금액으로 표시되지 않아요.
origin	String		원산지 표기 정보	"커피원두: 브라질산"
preparationTimeMinutes	Int		준비 시간 (분)	10
reservedAt	timestamp		예약 시각	"2025-09-01T00:00:00"
memo	String		요청사항	"문 앞에 두고 벨 눌러주세요."

배달 정보 수정 요청 (Delivery.Patch)

Name	Type	Required	Description	Example
type	String		배달 주문 유형 배달: DELIVERY 포장: PICKUP 매장 식사: HERE	"DELIVERY"
serviceName	String		배달 서비스명	"토스배달"
deliveryType	String		배달 유형 가게 자체배달: STORE 배달사: DELIVERY_COMPANY 배달대행사: AGENCY
deliveryName	String		배달 유형명	"토스배달"
status	DeliveryStatus		배달 상태	"ACCEPTED"
store	DeliveryStore		배달사에서 제공한 매장 정보
recipient	DeliveryRecipient		배달사에서 제공한 주문자 정보
paymentMethod	String		결제 방법	"만나서 카드결제"
customerChargedPrice	Long		고객 부담 금액	10000
customerAppliedDiscounts	DeliveryCustomerAppliedDiscount[]		플랫폼 할인 정보 주문의 할인(discounts)와 달리, 배달사에서 제공하는 할인 정보에요. 이 정보는 배달 주문서에는 표시되나, 매장의 결제 내역이나 매출 리포트에는 할인 금액으로 표시되지 않아요.
origin	String		원산지 표기 정보	"커피원두: 브라질산"
preparationTimeMinutes	Int		준비 시간 (분)	10
reservedAt	timestamp		예약 시각	"2025-09-01T00:00:00"
memo	String		요청사항	"문 앞에 두고 벨 눌러주세요."

배달 상태 (DeliveryStatus)

제공하는 상태값 중 적절한 값을 선택해 사용해 주세요.

Value	Description
"NEW"	신규
"ACCEPTED"	수락됨
"REJECTED"	거절됨
"PARTIALLY_CANCELLED"	부분 취소됨
"CANCELLED"	취소됨
"RIDER_ASSIGNED"	라이더 배정됨
"RIDER_ARRIVE_SOON"	라이더 도착 임박
"RIDER_PICKUP_COMPLETED"	라이더 픽업 완료
"DONE"	완료됨

배달 매장 정보 (DeliveryStore)

Name	Type	Required	Description	Example
key	String		매장 식별자	"store-1234567890"
name	String		매장명	"플레이스 베이커리"

배달 주문자 정보 (DeliveryRecipient)

개인정보 보호를 위해 일부 정보는 일정 기간 보관 후 파기됩니다.

Name	Type	Required	Description	Example
contact	String		연락처	"05000000000"
lotNumberAddress	String		지번 주소	"서울특별시 서초구 서초동 1303-34"
roadNameAddress	String		도로명 주소	"서울특별시 서초구 강남대로 459 (서초동)"

플랫폼 할인 정보 (DeliveryPlatformAppliedDiscount)

Name	Type	Required	Description	Example
type	String		할인 종류 "DELIVERY_FEE": 배달비 할인 "ETC": 그 외 할인 (메뉴, 옵션 할인 등)	"DELIVERY_FEE"
title	String		할인명	"배달료"
amount	Long		할인 금액	1000

Methods

배달 정보 단건 조회

Property	Value
Method	GET
Path	/api-public/openapi/v1/merchants/{merchantId}/delivery/deliveries/{deliveryId}
Response Type	Delivery
Description	배달 정보 하나를 조회해요.

요청 파라미터

Parameter	Location	Type	Required	Default	Description
merchantId	Path	Long	✅	-	매장 ID
deliveryId	Path	String	✅	-	배달 정보 ID

배달 정보 복수건 조회

Property	Value
Method	GET
Path	/api-public/openapi/v1/merchants/{merchantId}/delivery/deliveries/by-ids
Response Type	Delivery[]
Description	배달 정보 여러 건을 조회해요. 최대 25건까지 조회 가능해요.

요청 파라미터

Parameter	Location	Type	Required	Default	Description
merchantId	Path	Long	✅	-	매장 ID
ids	Query	String[]	✅	-	배달 정보 ID 목록

요청 파라미터

주문의 배달 정보 단건 조회

Property	Value
Method	GET
Path	/api-public/openapi/v1/merchants/{merchantId}/delivery/deliveries/by-order-id/{orderId}
Response Type	Delivery
Description	주어진 주문 ID에 해당하는 배달 정보를 조회해요.

요청 파라미터

Parameter	Location	Type	Required	Default	Description
merchantId	Path	Long	✅	-	매장 ID
orderId	Path	String	✅	-	주문 ID

주문의 배달 정보 복수건 조회

Property	Value
Method	GET
Path	/api-public/openapi/v1/merchants/{merchantId}/delivery/deliveries/by-order-ids
Response Type	Delivery[]
Description	주어진 주문 ID 목록에 해당하는 배달 정보를 조회해요. 최대 25건까지 조회 가능해요.

요청 파라미터

Parameter	Location	Type	Required	Default	Description
merchantId	Path	Long	✅	-	매장 ID
orderIds	Query	String[]	✅	-	주문 ID 목록

배달 정보 등록

Property	Value
Method	POST
Path	/api-public/openapi/v1/merchants/{merchantId}/delivery/deliveries
Response Type	Delivery
Description	주문에 배달 정보를 등록해요. 주문 생성 API를 통해 생성한 주문에 대해서만 배달 정보를 등록할 수 있어요.

요청 파라미터

Parameter	Location	Type	Required	Default	Description
merchantId	Path	Long	✅	-	매장 ID
orderId	Body	String	✅	-	주문 ID
delivery	Body	Delivery.Create	✅	-	배달 정보 생성 요청

배달 정보 수정

Property	Value
Method	PATCH
Path	/api-public/openapi/v1/merchants/{merchantId}/delivery/deliveries/{deliveryId}
Response Type	Delivery
Description	주문의 배달 정보를 수정해요. 주문 생성 API를 통해 생성한 주문에 대해서만 배달 정보를 수정할 수 있어요.

요청 파라미터

Parameter	Location	Type	Required	Default	Description
merchantId	Path	Long	✅	-	매장 ID
deliveryId	Path	String	✅	-	배달 정보 ID
delivery	Body	Delivery.Patch	✅	-	배달 정보 수정 요청 요청에 명시된 필드만 수정돼요.

배달 완료 처리

Property	Value
Method	POST
Path	/api-public/openapi/v1/merchants/{merchantId}/delivery/deliveries/{deliveryId}/complete
Response Type	Delivery
Description	배달을 완료 처리해요. 주문 생성 API를 통해 생성한 주문에 대해서만 배달을 완료 처리할 수 있어요.

요청 파라미터

Parameter	Location	Type	Required	Default	Description
merchantId	Path	Long	✅	-	매장 ID
deliveryId	Path	String	✅	-	배달 정보 ID