주문 - 개념 상세

Types

주문 (Order)

주문은 매장에서 소비자가 상품을 구매하고 결제하는 것을 표현하는 개념이에요. 주문은 구매한 상품 목록, 결제 내역, 결제 금액 등 이 과정에서 기록되는 정보를 모두 포함하고 있어요.

Field	Type	Required	Description	Example
id	String	✅	주문 ID	"620000000000000000"
merchantId	Long	✅	매장 ID	42
source	String	✅	주문 채널 주문이 인입된 경로를 말해요. 예를 들어, 토스 POS로부터 인입된 주문은 "POS", 토스 키오스크로부터 인입된 주문은 "KIOSK" 등이에요. 주문 생성 API를 통해 생성한 주문의 경우 "PLUGIN_{appId.toUpperCase()}" 값을 가져요. (예: my-awesome-app 앱에서 생성한 주문의 source는 "PLUGIN_MY-AWESOME-APP")	"POS"
orderState	OrderState	✅	주문 상태	"OPENED"
orderKey	String	✅	주문 키 주문을 식별하는 용도로 사용하는 문자열이에요. 주문 채널에 따라 고유의 값 체계를 사용할 수 있어요.	"EXT-20260512-0001"
orderNumber	String		주문 번호 매장을 운영하거나 이용하는 사람이 주문을 확인하는 데 사용하는 주문번호예요. ("042번 주문" 과 같은 형태) 토스 POS 결제내역, 주문 현황, 주문서, 영수증 등에 표시되는 값이에요.	"A-001"
createdAt	timestamp	✅	생성 시각	"2025-09-01T00:00:00"
updatedAt	timestamp	✅	변경 시각	"2025-09-01T00:00:00"
openedAt	timestamp		주문 수락 시각	"2025-09-01T00:00:00"
completedAt	timestamp		주문 완료 시각	"2025-09-01T00:00:00"
cancelledAt	timestamp		주문 취소 시각	"2025-09-01T00:00:00"
lineItems	OrderLineItem[]	✅	주문 내역
requestedInfo	OrderRequestedInfo		주문 요청 정보 픽업 주문과 같이, 매장에서 수락 또는 거절할 수 있는 주문의 경우 주문 요청 정보를 포함하고 있어요.
memo	String		주문 메모 소비자 또는 매장 운영자가 주문에 대해 추가로 작성한 메모예요.	"얼음 적게"
cancelledReason	String		ALPHA 주문 취소 사유	"고객 요청으로 인한 취소"
payments	Payment[]	✅	결제 내역
discounts	Discount[]	✅	할인 내역
accruals	OrderAccrual[]		ALPHA 적립 내역
redemptions	OrderRedemption[]		ALPHA 혜택 사용 내역
chargePrice	OrderChargePrice	✅	청구 금액

주문 상태 (OrderState)

Value	Description
"REQUESTED"	주문 수락 전 (픽업 주문 등의 경우)
"OPENED"	시작됨
"COMPLETED"	완료됨 (결제까지 완료된 상태)
"CANCELLED"	취소됨
"UNDEFINED"

주문 내역 (OrderLineItem)

주문에 포함된 개별 상품 주문 건이에요.

Field	Type	Required	Description	Example
diningOption	OrderDiningOption	✅	식사 옵션	"HERE"
item	OrderItem	✅	상품
itemPrice	OrderItemPrice	✅	상품 가격
optionChoices	OrderItemOptionChoice[]	✅	선택한 옵션
appliedDiscounts	Discount[]	✅	항목별 적용 할인 내역
quantity	Long	✅	수량	1
memo	String		주문 내역 메모 주문자 또는 매장 운영자가 이 주문 내역에 대해 추가로 작성한 메모예요.	"얼음 적게"

주문 식사 옵션 (OrderDiningOption)

Value	Description
"HERE"	매장 식사
"TOGO"	포장
"DELIVERY"	배달
"PICKUP"	포장 (픽업)
"UNDEFINED"

상품 (OrderItem)

Field	Type	Required	Description	Example
title	String	✅	상품명	"아메리카노"
code	String		상품 코드	""
category	OrderItemCategory	✅	상품이 속한 카테고리

상품 가격 (OrderItemPrice)

Name	Type	Required	Description	Example
title	String	✅	가격명	"기본"
priceType	OrderItemPriceType	✅	가격 종류	"FIXED"
priceUnit	Long	✅	가격 단위	1
priceValue	Long	✅	가격	3000
isTaxFree	Boolean	✅	면세 여부	false
taxPercentage	Int		세율	10
taxInclusive	Boolean	✅	부가세 포함 여부	true

상품 가격 종류 (OrderItemPriceType)

Value	Description
"FIXED"	정가
"VARIABLE"	시가
"UNIT"	단위가격
"UNDEFINED"

카테고리 (OrderItemCategory)

Field	Type	Required	Description	Example
title	String	✅	카테고리명	"커피"
code	String		카테고리 코드	""

옵션 (OrderItemOption)

Field	Type	Required	Description	Example
title	String	✅	옵션명	"온도"

옵션 선택지 (OrderItemOptionChoice)

Field	Type	Required	Description	Example
title	String	✅	선택지명	"ICE"
code	String		선택지 코드	"ICE"
priceValue	Long	✅	가격	500
quantity	Long	✅	수량	1
option	OrderItemOption		선택지가 속한 옵션

주문 요청 정보 (OrderRequestedInfo)

배달 또는 픽업 주문과 같이, 매장에서 수락 또는 거절할 수 있는 주문의 경우 주문 요청 정보를 포함하고 있어요.

Field	Type	Required	Description	Example
requestedAt	timestamp		주문 요청 시각	"2025-09-01T00:00:00"
expiredAt	timestamp		주문 요청 만료 시각	"2025-09-01T00:00:00"
expectedReadyAt	timestamp		주문의 예상 완료 시각 손님 기준에서의 예상 완료 시각을 의미해요. (예: 손님이 15분 뒤 픽업 예정)	"2025-09-01T00:00:00"
estimatedReadyAt	timestamp		주문의 예상 준비 완료 시각 매장 기준에서의 예상 완료 시각을 의미해요. (예: 20분 뒤 픽업 가능)	"2025-09-01T00:00:00"
allowedEstimatedReadyDurations	Duration[]		ALPHA 주문 수락 시 선택 가능한 예상 준비 완료 시간 목록 (예: 토스 POS에서 예상 준비 시간을 10분, 20분 중 하나로 선택 가능)	["PT10M", "PT20M"]
acceptedAt	timestamp		주문 수락 시각	"2025-09-01T00:00:00"
declinedAt	timestamp		주문 거절 시각	"2025-09-01T00:00:00"
declinedReason	String		ALPHA 주문 거절 사유	"메뉴 품절"
declinedCode	String		ALPHA 주문 거절 사유 코드 예시: - 고객 요청 ("CUSTOMER_REQUEST") - 메뉴 품절 ("MENU_SOLD_OUT") - 주문 밀림 ("COOKING_DELAY") - 요청사항 불가 ("REQUEST_UNAVAILABLE")	"MENU_SOLD_OUT"

주문 청구 금액 (OrderChargePrice)

Name	Type	Required	Description	Example
listPrice	Long	✅	원금액	3500
discountAmount	Long	✅	할인금액	-300
tipAmount	Long	✅	팁	0
serviceChargeAmount	Long	✅	봉사료	0
taxAmount	Long	✅	세액	291
supplyAmount	Long	✅	공급가액	2909
taxExemptAmount	Long	✅	면세금액	0
totalAmount	Long	✅	최종금액	3200

할인 내역 (Discount)

할인 정책이 주문에 적용된 결과예요. 주문 조회 시 할인 관련 필드를 통해 적용 결과를 함께 확인할 수 있어요.

Name	Type	Required	Description	Example
title	String	✅	할인명	"PROMOTION"
type	String		할인 종류 (예: "FIXED_AMOUNT", "FIXED_PERCENTAGE")	"FIXED_AMOUNT"
code	String		할인 코드	"PROMOTION_00"
amount	Long	✅	할인 적용 금액	1000
percentage	Double	✅	정률할인 비율 (정률할인이 아닌 경우 0.0)	0.0
fixedAmount	Long	✅	정액할인 금액 (정액할인이 아닌 경우 0)	1000
precedence	Int		할인 적용 우선순위 (값이 작을수록 높은 우선순위)	1
couponDetails	DiscountCouponDetails		ALPHA 할인 쿠폰 상세 정보

ALPHA 할인 쿠폰 상세 정보 (DiscountCouponDetails)

Name	Type	Required	Description	Example
provider	String	✅	쿠폰 제공자	"토스플레이스"
couponNumber	String		쿠폰 번호	"123456"
balance	Long		쿠폰 잔액	1000

ALPHA 적립 내역 (OrderAccrual)

Name	Type	Required	Description	Example
name	String	✅	적립명	"토스플레이스 적립"
referenceType	String	✅	원천 구분자. 멱등성 보장에 사용해요.	"TOSSPOINT"
referenceId	String	✅	구분 내 식별자. 멱등성 보장에 사용해요.	"TP-001"
occurredAt	timestamp	✅	적립 발생 시각	"2026-01-01T00:00:00+09:00"
pointDetails	OrderAccrualPointDetails		포인트 적립 세부 내역
stampDetails	OrderAccrualStampDetails		스탬프 적립 세부 내역

ALPHA 포인트 적립 상세 (OrderAccrualPointDetails)

Name	Type	Required	Description	Example
provider	String	✅	적립 제공처	"TOSSPLACE"
amount	Int	✅	적립 포인트. 적립이면 양수, 회수면 음수.	100
balance	Int		적립 후 누적 잔액	1000

ALPHA 스탬프 적립 상세 (OrderAccrualStampDetails)

Name	Type	Required	Description	Example
provider	String	✅	적립 제공처	"TOSSPLACE"
count	Int	✅	적립 스탬프 수. 적립이면 양수, 회수면 음수.	1
balance	Int		적립 후 누적 스탬프 수	5

ALPHA 혜택 사용 내역 (OrderRedemption)

Name	Type	Required	Description	Example
name	String	✅	혜택 사용명	"포인트 사용"
referenceType	String	✅	원천 구분자. 멱등성 보장에 사용해요.	"TOSSPOINT_REDEMPTION"
referenceId	String	✅	구분 내 식별자. 멱등성 보장에 사용해요.	"TP-001"
occurredAt	timestamp	✅	혜택 사용 발생 시각	"2026-01-01T00:00:00+09:00"
pointDetails	OrderRedemptionPointDetails		포인트 사용 세부 내역
couponDetails	OrderRedemptionCouponDetails		쿠폰 사용 세부 내역

ALPHA 포인트 사용 상세 (OrderRedemptionPointDetails)

Name	Type	Required	Description	Example
provider	String	✅	혜택 제공처	"TOSSPLACE"
amount	Int	✅	사용 포인트. 사용이면 양수, 취소면 음수.	500
balance	Int		사용 후 잔액	500

ALPHA 쿠폰 사용 상세 (OrderRedemptionCouponDetails)

Name	Type	Required	Description	Example
provider	String	✅	혜택 제공처	"TOSSPLACE"
couponNumber	String		쿠폰 번호	"CPN-123456"
count	Int	✅	사용 쿠폰 수. 사용이면 양수, 취소면 음수.	1