Order API

개요

주문을 다루는 API예요. 주문은 매장에서 이루어지는 핵심적인 활동으로, 주문 내역, 구매한 상품 정보, 결제 내역, 할인 내역 등 관련된 모든 정보를 추적하는 단위예요. 고객이 오프라인 매장에 직접 방문해 주문하는 경우 이외에도, 배달, 픽업 주문 등 온라인 채널을 통해 주문이 이루어질 수 있어요.

구성 요소

주문을 이루는 구성 요소는 다음과 같아요.

• 주문은 주문과 관련된 다른 모든 정보를 포괄하는 단위예요. 예를 들어, 손님이 식당에 방문하여 음식을 주문하고, 식사를 마친 뒤 결제를 완료하고 떠나는 것을 1회의 주문이라고 이해하면 적절해요.
• 주문 내역은 주문에 포함된 개별 상품 주문 건이에요. 예를 들어, 손님이 아메리카노 1잔과 카페라떼 1잔을 주문한 경우, 아메리카노 1잔과 카페라떼 1잔을 의미하는 주문 내역이 존재해요. 내역별로 고객이 선택한 상세 옵션, 수량, 할인 내역 등 부가 정보를 포함해요.
• 청구 금액은 주문에 대해 청구되는 금액 정보를 표현해요. 고객이 결제해야 하는 총 금액과 더불어 할인 금액, 세액, 봉사료, 팁 등 부가 정보를 포함해요.
• 결제 내역은 주문에 대해 결제된 내역을 표현해요. 결제 내역은 결제 수단, 결제 금액 등 상세 정보를 포함하고 있어요. 결제가 취소되었다가 재결제되는 경우, 분할 결제가 이루어지는 경우 등 다양한 상황에서 결제 내역을 추적할 수 있어요.
• 할인 내역은 주문에 적용된 할인 정책과 금액을 표현해요.

다른 개념과의 관계

결제

결제는 항상 주문에 대해 이루어지는 행위예요. 상품을 주문하면서 함께 결제를 완료하는 선불 주문, 먼저 주문을 하고 나중에 결제를 하는 후불 주문 등 다양한 방식으로 결제가 이루어질 수 있어요. 결제 API를 통해 주문에 대한 결제 내역을 조회할 수 있어요.

카탈로그

카탈로그는 매장에서 판매하는 상품 목록을 표현하는 개념이에요. 카탈로그에서 정의한 상품은 주문 내역에 포함되어 주문이 이루어져요.

카탈로그 API를 주문 API와 함께 다음과 같은 방법으로 활용할 수 있어요.

• 매장에서 판매하는 상품 정보를 확인하여 주문 API에서 조회한 내역과 결합하여 사용해요.
• 메뉴 구성을 카탈로그 API를 통해 관리하고, 주문 내역에 상품 정보를 담아 주문 추가 · 수정 API를 통해 토스 POS 주문을 생성해요. 픽업, 배달 등 온라인으로 사용자가 메뉴를 확인하고 주문하는 서비스를 토스 POS와 통합하고자 할 때 활용할 수 있어요.

활용

주문 이력 확인하기

주문 조회 HTTP API를 통해 매장에서 이루어진 주문 이력을 조회할 수 있어요.

활용 예시:

• 과거 주문 내역을 조회하여 매출 분석 및 상품별 판매 통계 수집
• 일정 주기마다 최근 주문 내역을 조회하여 실시간 현황 확인

주문 알림 받기

새로운 주문이 인입되거나, 매장에서 조리를 완료하여 고객을 호출할 때 주문 웹훅을 통해 이벤트를 수신할 수 있어요.

이벤트명	이벤트 타입	설명
주문 생성됨	order.order.created.v1	새로운 주문이 생성되었어요.
고객 호출됨	order.call.created.v1	매장에서 주문 준비를 완료하여 고객을 호출했어요.

주문 상태 추적하기

주문은 고객이 온라인/오프라인으로 매장에 방문했는지, 선불/후불로 결제를 하는지 등 다양한 형태로 이루어질 수 있어요. 주문 속성 중 주문 상태와 주문 웹훅을 통해 주문의 상태를 추적할 수 있어요.

주문 상태는 주문의 현재 상태를 표현해요.

상태	코드	설명
주문 수락 전	REQUESTED	픽업 주문 등, 매장에서 주문을 수락/거절할 수 있는 주문이 인입되었을 때 가지는 상태예요.
시작됨	OPENED	주문이 매장에서 수락되어 상품이 준비 중인 상태예요.
완료됨	COMPLETED	결제까지 완료한 상태예요.
취소됨	CANCELLED	매장에서 주문을 거절하거나, 환불 처리되어 주문이 정상적으로 완료되지 않은 상태예요.

주문 상태가 변경되는 사건이 일어날 때 주문 웹훅을 통해 이벤트를 수신할 수 있어요.

이벤트명	이벤트 타입	설명
주문 요청됨	order.order.requested.v1	새로운 주문이 요청되어 매장의 수락을 기다리고 있어요.
주문 수락됨	order.order.accepted.v1	매장에서 주문을 수락했어요.
주문 거절됨	order.order.declined.v1	매장에서 주문을 거절했어요.
주문 만료됨	order.order.expired.v1	요청된 주문을 매장에서 일정 시간 내에 수락/거절하지 않아 자동으로 만료 처리되었어요.
주문 시작됨	order.order.opened.v1	주문이 시작되어 준비 중이에요.
주문 완료됨	order.order.completed.v1	주문이 완료되었어요.
주문 취소됨	order.order.cancelled.v1	주문이 취소되었어요.

일반적인 매장에서 자주 볼 수 있는 활용 사례에서 주문 상태가 어떻게 이동하는지 알아볼게요.

• 선불 주문
  1. 주문과 동시에 결제까지 완료돼요. 주문은 OPENED를 거쳐 곧바로 COMPLETED 상태가 돼요. (주문 시작됨, 주문 완료됨 이벤트 발생)
• 후불 주문
  1. 손님이 자리에 앉아 주문을 하면 OPENED 상태가 돼요. (주문 시작됨 이벤트 발생)
  2. 손님이 식사를 마치고 결제를 완료하면 COMPLETED 상태가 돼요. (주문 완료됨 이벤트 발생)
• 픽업 주문:
  1. 픽업 주문이 인입되면 REQUESTED 상태가 돼요. (주문 요청됨 이벤트 발생)
  2. 매장에서 주문을 수락하거나 거절해요.
     • 주문을 수락하면 OPENED 상태가 돼요. (주문 수락됨 이벤트 발생)
     • 주문을 거절하면 CANCELLED 상태가 돼요. (주문 거절됨 이벤트 발생)
  3. 매장에서 조리를 끝내고 손님이 픽업을 완료하면 COMPLETED 상태가 돼요. (주문 완료됨 이벤트 발생)

주문 연동하기

주문 생성 API를 통해 토스 POS 주문을 생성할 수 있어요. 외부 시스템에서 받은 주문 정보를 토스 POS 주문으로 생성하여 주문 이력을 관리할 수 있어요.