주문 - 개념 상세

Types

주문 (Order)

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

Field	Type	Required	Description	Example
`id`	`String`	✅	주문 ID	`"620000000000000000"`
`merchantId`	`Long`	✅	매장 ID	`42`
`source`	`String`	✅	주문 채널 주문이 인입된 경로를 말해요. 예를 들어, 토스 POS로부터 인입된 주문은 `"POS"`, 토스 키오스크로부터 인입된 주문은 `"KIOSK"` 등이에요.	`"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`		주문 메모 소비자 또는 매장 운영자가 주문에 대해 추가로 작성한 메모예요.	`"얼음 적게"`
`payments`	`Payment[]`	✅	결제 내역
`discounts`	`Discount[]`	✅	할인 내역
`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`		주문 내역 메모 주문자 또는 매장 운영자가 이 주문 내역에 대해 추가로 작성한 메모예요.	`"얼음 적게"`

주문 내역 대상 종류 (OrderLineItemTargetType)

Value	Description
`"ITEM"`	상품
`"COMBO"`	콤보
`"UNDEFINED"`

주문 식사 옵션 (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"`
`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`