Skip to content

Open API 변경 이력

2026-09-15

ALPHA 기능으로 제공되는 콤보(세트상품)에 기타 속성(attributes) 필드가 추가되었어요.

2026-08-25

주문 취소 시 취소 사유를 입력할 수 있어요.

  • 주문
    • ALPHA 주문 취소 사유 (cancelledReason) 필드가 추가됩니다.
    • 주문 취소 API
      • ALPHA 주문 취소 사유 (cancelledReason) 필드를 입력할 수 있습니다.

2026-08-10

  • 주문
    • 주문 요청 정보 OrderRequestedInfo
      • ALPHA 주문 수락 시 선택 가능한 예상 준비 완료 시간 목록 (allowedEstimatedReadyDurations) 필드가 추가됩니다.
    • 주문 생성 API
      • 주문 요청 정보 생성 요청 OrderRequestedInfo.Create
        • ALPHA 주문 수락 시 선택 가능한 예상 준비 완료 시간 목록 (allowedEstimatedReadyDurations) 필드가 추가됩니다.

2026-08-05

고객 호출 웹훅 이벤트 payload에 주문 채널 (source) 필드가 추가되었어요.

  • 주문 - 웹훅
    • 이벤트: 고객 호출됨 (order.call.created.v1)
      • 주문 채널 (source) 필드가 추가됩니다.

2026-08-04

주문 상태 변경 웹훅 이벤트 payload에 주문 채널 (source) 필드가 추가되었어요.

  • 주문 - 웹훅
    • 이벤트: 주문 요청됨 (order.order.requested.v1)
      • 주문 채널 (source) 필드가 추가됩니다.
    • 이벤트: 주문 수락됨 (order.order.accepted.v1)
      • 주문 채널 (source) 필드가 추가됩니다.
    • 이벤트: 주문 거절됨 (order.order.declined.v1)
      • 주문 채널 (source) 필드가 추가됩니다.
    • 이벤트: 주문 만료됨 (order.order.expired.v1)
      • 주문 채널 (source) 필드가 추가됩니다.
    • 이벤트: 주문 시작됨 (order.order.opened.v1)
      • 주문 채널 (source) 필드가 추가됩니다.
    • 이벤트: 주문 완료됨 (order.order.completed.v1)
      • 주문 채널 (source) 필드가 추가됩니다.
    • 이벤트: 주문 취소됨 (order.order.cancelled.v1)
      • 주문 채널 (source) 필드가 추가됩니다.

2026-07-28

토스 POS로 외부 배달 서비스 주문을 관리할 수 있는 배달 API가 추가되었어요. 주문 API와 함께 활용하여 배달 관련 정보를 토스 POS 주문과 함께 확인할 수 있어요.

또한, 결제 정보를 등록할 때 승인 번호 (approvedNo) 필드를 입력하지 않아도 되도록 변경되었어요. 현금 결제 등 별도 승인 번호가 존재하지 않는 경우 활용하면 돼요.

  • 배달
    • [신규] 배달 정보 Delivery
    • [신규] 배달 정보 생성 요청 Delivery.Create
    • [신규] 배달 정보 수정 요청 Delivery.Patch
    • [신규] 배달 상태 DeliveryStatus
    • [신규] 배달 매장 정보 DeliveryStore
    • [신규] 배달 주문자 정보 DeliveryRecipient
    • [신규] 플랫폼 할인 정보 DeliveryPlatformAppliedDiscount
    • [신규] 배달 정보 단건 조회 API
    • [신규] 배달 정보 복수건 조회 API
    • [신규] 주문의 배달 정보 단건 조회 API
    • [신규] 주문의 배달 정보 복수건 조회 API
    • [신규] 배달 정보 등록 API
    • [신규] 배달 정보 수정 API
    • [신규] 배달 완료 처리 API
  • 주문
    • 주문 생성 API
      • 배달 정보 (delivery) 필드를 입력할 수 있어요.
  • 결제

2026-07-27

주문 목록 조회 API의 설명을 정확하게 수정했어요. 기존에는 조회 결과가 주문 생성 시각을 기준으로 정렬되어 있다는 설명이었는데, 실제로는 주문에 결제 내역이 변동된 시각을 기준으로 정렬되어 있어요. 대부분의 경우에는 두 가지 시각이 일치하지만, 결제가 취소되거나 주문 생성 이후 뒤늦게 결제가 일어나는 경우에는 달라질 수 있어요. 실제 동작과 일치하도록 설명을 수정했어요.

2026-07-24

토스 POS 주문을 생성할 때, 카탈로그에 등록되지 않은 임의 상품 및 옵션을 입력하여 주문 내역을 구성할 수 있어요. 토스 POS 카탈로그과 연동하지 않는 경우에 유용하게 활용할 수 있어요. 또한, 주문 내역을 변경할 수 있는 주문 내역 변경 API가 추가되었어요.

2026-07-23

주문에 혜택 사용 내역을 추가하고 조회할 수 있어요. 적립과 혜택 사용 내역에 원천 구분 필드가 추가되어, 멱등성 보장에 사용해요.

또한, 주문 생성시에 결제 번들 필드를 입력할 수 있어요.

  • 주문
    • ALPHA 적립 내역 OrderAccrual

      • 원천 구분 (referenceType) 필드가 추가됩니다.
      • 멱등성 키가 referenceId에서 (referenceType, referenceId) 쌍으로 변경됩니다.
    • ALPHA [신규] 혜택 사용 내역 OrderRedemption

      • ALPHA 포인트 사용 상세 (pointDetails) 필드가 추가됩니다.
      • ALPHA 쿠폰 사용 상세 (couponDetails) 필드가 추가됩니다.
      • ALPHA 원천 구분 (referenceType) 필드가 추가됩니다.
      • ALPHA 구분 내 식별자 (referenceId) 필드가 추가됩니다.
      • ALPHA 혜택 사용 발생 시각 (occurredAt) 필드가 추가됩니다.
    • [신규] 주문 Order

      • ALPHA 혜택 사용 내역 (redemptions) 필드가 추가됩니다.
    • ALPHA 적립 추가 API

    • ALPHA [신규] 혜택 사용 추가 API

    • 주문 생성 Order.Create

      • ALPHA 혜택 사용 내역 (redemptions) 필드를 입력할 수 있습니다.
    • 결제 내역 생성 Payment.Create

      • ALPHA 결제 번들 (bundle) 필드를 입력할 수 있습니다.

2026-07-20

주문 조회, 수락 및 거절, 결제 내역 추가 기능을 지원해요.

2026-07-17

주문 생성, 주문 취소 시 토스 POS에 연결된 프린터에서 주문서 또는 취소 주문서를 출력할 수 있어요.

  • 주문
    • 주문 생성
      • 주문서 출력 여부 printOrderSheet 파라미터가 추가됩니다.
    • 주문 취소
      • 주문서 출력 여부 printOrderSheet 파라미터가 추가됩니다.

2026-07-15

한 번의 요청으로 여러 적립 내역을 추가할 수 있어요. 또한, 주문 생성 시 적립을 함께 입력할 수 있어요.

  • 주문
    • ALPHA 스탬프 적립 상세 OrderAccrualStampDetails
      • 스탬프 수량 필드명이 amount에서 count로 변경됩니다.
    • ALPHA 적립 추가 API
      • 요청 body가 단일 accrual에서 accruals 배열로 변경됩니다. 한 번에 여러 건의 적립을 추가할 수 있습니다.
    • ALPHA 주문 생성 Order.Create
      • ALPHA 적립 내역 (accruals) 필드를 입력할 수 있습니다.

2026-07-06

  • 주문
    • [신규] 주문 생성 API
      • ALPHA 주문 자동 처리 정보(scheduled)를 입력할 수 있습니다.

2026-07-03

  • 카탈로그
    • [신규] 전시 규칙 대상 종류 CatalogRuleResourceType
      • ITEM 값이 추가됩니다. 상품을 전시 규칙의 조건·효과 대상으로 사용할 수 있습니다.

2026-06-23

  • 카탈로그
    • [신규] 전시 규칙 효과 CatalogRuleEffectType
      • DISPLAY_EXCLUSIVE 값이 추가됩니다. 조건 만족 시 적용 대상만 화면에 노출하고 다른 대상은 숨깁니다.
    • [신규] 이벤트: ALPHA 전시 규칙 생성됨 (catalog.rule.created.v1)
    • [신규] 이벤트: ALPHA 전시 규칙 수정됨 (catalog.rule.updated.v1)
    • [신규] 이벤트: ALPHA 전시 규칙 삭제됨 (catalog.rule.deleted.v1)

2026-06-22

주문에 포인트·스탬프 적립 내역을 추가하고 조회할 수 있어요. 또한, 결제 조회 시 복합 결제를 묶는 번들 정보를 확인할 수 있어요.

  • 주문 -ALPHA [신규] 적립 내역 OrderAccrual
    • ALPHA 포인트 적립 상세 (pointDetails) 필드가 추가됩니다.
    • ALPHA 스탬프 적립 상세 (stampDetails) 필드가 추가됩니다.
    • ALPHA 외부 참조 키 (referenceId) 필드가 추가됩니다.
    • ALPHA 적립 발생 시각 (occurredAt) 필드가 추가됩니다.
    • [신규] 주문 Order
      • ALPHA 적립 내역 (accruals) 필드가 추가됩니다.
    • ALPHA [신규] 적립 추가 API
  • 결제
    • ALPHA [신규] 결제 번들 PaymentBundle
      • ALPHA 번들 식별자 (key) 필드가 추가됩니다.
    • [신규] 결제 Payment
      • ALPHA 결제 번들 (bundle) 필드가 추가됩니다.

2026-06-15

  • 주문
    • [신규] 주문 생성 Order.Create
      • ALPHA 주문자 정보(orderer)를 입력할 수 있습니다.
    • [신규] 결제 내역 생성 Payment.Create
      • PG사 결제 상세 정보 (pgDetails) 필드가 추가됩니다.
    • [신규] 할인 내역 Discount
      • ALPHA 쿠폰 상세 정보 (couponDetails) 필드가 추가됩니다.
  • 결제
    • [신규] 결제 Payment
      • PG사 결제 상세 정보 (pgDetails) 필드가 추가됩니다.
  • 카탈로그
    • [신규] 상품 CatalogItem
      • ALPHA 상품 활성화 및 노출 시간·일자 설정 (enableSchedule) 필드가 추가됩니다.
      • ALPHA 주문 맥락에 따라 동적으로 변경되는 가격 정보 (priceVariations) 필드가 추가됩니다.
      • ALPHA 상품을 제공하는 식사 옵션 목록 (diningOptions) 필드가 추가됩니다.
      • 기타 속성 (attributes) 필드가 추가됩니다.

2026-06-12

토스 POS에서 주문 준비를 완료하여 고객을 호출할 때 수신할 수 있는 이벤트(고객 호출됨; order.call.created.v1)를 지원합니다. 예를 들어, 토스 POS [현황] 화면에서 주문 카드의 호출 버튼을 누르면 이 이벤트가 발생합니다. 또한, 거절된 주문에 대해 거절 사유 등 추가로 확인할 수 있는 정보를 제공합니다.

  • 주문
    • [신규] 이벤트: 고객 호출됨 (order.call.created.v1)
    • [신규] 주문 요청 정보 OrderRequestedInfo
      • ALPHA 거절 사유 (declinedReason) 필드가 추가됩니다.
      • ALPHA 거절 사유 코드 (declinedCode) 필드가 추가됩니다.
    • [신규] 주문 거절됨 (order.order.declined.v1)
      • ALPHA 거절 사유 (declinedReason) 필드가 추가됩니다.
      • ALPHA 거절 사유 코드 (declinedCode) 필드가 추가됩니다.

2026-06-10

카탈로그 - ALPHA 기능으로 전시 규칙 기능이 제공됩니다. 전시 규칙은 주문 과정에서 특정 상품이나 선택지를 골랐을 때 그에 맞추어 동적으로 전시 화면을 변경하는 정책을 표현합니다. 일부 매장에서 활용할 수 있는 기능입니다.

  • 카탈로그
    • ALPHA [신규] 전시 규칙 CatalogRule
    • ALPHA [신규] 전시 규칙 대상 CatalogRuleResourceTarget
    • ALPHA [신규] 전시 규칙 대상 종류 CatalogRuleResourceType
    • ALPHA [신규] 전시 규칙 조건 CatalogRuleCondition
    • ALPHA [신규] 전시 규칙 조건 연산자 CatalogRuleConditionOperator
    • ALPHA [신규] 전시 규칙 효과 CatalogRuleEffectType
    • ALPHA [신규] 전시 규칙 단건 조회
    • ALPHA [신규] 전시 규칙 복수건 조회
    • ALPHA [신규] 전시 규칙 목록 조회

2026-06-08

매장 상세 정보가 보강돼요. 매장 주소, 위경도, 운영시간 등 상세정보를 조회하고 변경될 때마다 웹훅 이벤트(merchant.merchant.updated.v1)를 수신할 수 있어요.

  • 매장
    • [신규] 매장 Merchant
      • 사업주명 (ownerName) 필드가 추가돼요.
      • 매장 표시명 (displayName) 필드가 추가돼요.
      • 매장 전화번호 (phoneNumber) 필드가 추가돼요.
      • 주소 (address) 필드가 추가돼요.
      • 위도 (latitude) 필드가 추가돼요.
      • 경도 (longitude) 필드가 추가돼요.
      • 영업 시간 (operatingHours) 필드가 추가돼요.
      • 기타 속성 (attributes) 필드가 추가돼요.

2026-06-01

토스 POS 주문을 취소 상태로 변경할 수 있는 주문 취소 API와, 취소된 결제건을 기록할 수 있는 취소된 결제 기록 API가 추가되었어요. 결제 승인 또는 취소 시 웹훅 이벤트를 수신할 수 있어요. 주문 취소, 취소된 결제 기록 API는 추후 공지가 있을 때까지 승인을 받은 앱에서만 사용할 수 있어요. 문의사항이 있으신 경우 개발자센터 지원 이메일로 문의해주세요.

2026-05-28

토스 POS 주문을 등록할 수 있는 주문 생성 API가 추가되었어요. 주문 생성 API는 추후 공지가 있을 때까지 승인을 받은 앱에서만 사용할 수 있어요. 문의사항이 있으신 경우 개발자센터 지원 이메일로 문의해주세요.

또한, 결제 내역 관련 세부 필드가 보강되었어요.

  • 주문
  • 결제
    • [신규] 결제 Payment
      • 결제수단 대분류(PaymentSourceType)에 선불지급수단 (PREPAID_VALUE)가 추가되고, 관련 세부 내역 (prepaidValueDetails) 정보를 제공해요.
    • [신규] 현금결제 상세 PaymentCashDetails
      • 고객이 지불한 금액 (buyerSuppliedAmount) 필드가 추가돼요.
      • 거스름돈 (changeBackAmount) 필드가 추가돼요.
    • [신규] 카드결제 상세 PaymentCardDetails
      • 승인번호 (approvalNo) 필드가 추가돼요.
      • 결제 금액 (amount) 필드가 추가돼요.
    • [신규] 선불지급수단 결제 상세 PaymentPrepaidValueDetails
    • [신규] 계좌이체 상세 PaymentAccountTransferDetails
      • 은행 코드 (bankCode) 필드가 추가돼요.
      • 계좌번호 (마스킹 적용) (accountNumber) 필드가 추가돼요.
    • [신규] 간편결제 상세 PaymentEasyPayDetails
      • 결제 금액 (amount) 필드가 추가돼요.
    • [신규] 현금영수증 상세 PaymentCashReceipt
      • 식별번호 (identityNumber) 필드 설명을 정확하게 수정했어요.
      • 발급 번호 (issueNumber) 필드가 추가돼요.
      • 발급 시각 (issuedAt) 필드가 추가돼요.
      • 발급 금액 (amount) 필드가 추가돼요.
    • [신규] 결제 정산 정보 PaymentSettlement
    • [신규] 정산 주체 종류 PaymentSettlementType

2026-05-26

상품옵션 선택지의 품절 상태 속성을 제공해요. 또한, ALPHA 기능으로 제공되는 콤보(세트상품) 관련 웹훅 이벤트를 제공해요.

  • 카탈로그
    • [신규] 상품 CatalogItem
      • 품절 상태 (state) 필드가 추가돼요.
    • [신규] 옵션 선택지 CatalogOptionChoice
      • 품절 상태 (state) 필드가 추가돼요.
    • [신규] 이벤트: ALPHA 콤보 생성됨 (catalog.combo.created.v1)
    • [신규] 이벤트: ALPHA 콤보 수정됨 (catalog.combo.updated.v1)
    • [신규] 이벤트: ALPHA 콤보 삭제됨 (catalog.combo.deleted.v1)

2026-05-21

주문 웹훅이 지원돼요. 새로운 주문이 생성되거나, 주문 상태가 변경될 때 이벤트를 수신할 수 있어요.

  • 주문 - 웹훅
    • [신규] 이벤트: 주문 생성됨 (order.order.created.v1)
    • [신규] 이벤트: 주문 요청됨 (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)

2026-05-18

주문 정보에 몇 가지 추가 속성을 제공해요.

  • 주문
    • [신규] 주문 Order
      • 주문 키 (orderKey) 필드가 추가돼요.
      • 주문 번호 (orderNumber) 필드가 추가돼요.
      • 주문 요청 정보 (requestedInfo) 필드가 추가돼요.
      • 주문 메모 (memo) 필드가 추가돼요.
    • [신규] 주문 내역 OrderLineItem
      • 주문 내역 메모 (memo) 필드가 추가돼요.
    • [신규] 주문 요청 정보 OrderRequestedInfo

2026-05-14

카탈로그 - ALPHA 기능으로 콤보(세트상품) 기능이 제공돼요. 콤보는 여러 상품을 한 번에 할인된 가격으로 묶어 판매할 수 있는 상품종이에요. 일부 매장에서 활용할 수 있는 기능이에요. 또한, 상품•카테고리•옵션•옵션 선택지에 노출 활성화 여부 및 정렬 순서를 표현하는 속성을 제공해요.

  • 카탈로그
    • ALPHA [신규] 콤보 CatalogCombo, 콤보 구성 상품군 CatalogComboTargetGroup, 콤보 구성 CatalogComboTarget
    • ALPHA [신규] 콤보 단건 조회
    • ALPHA [신규] 콤보 복수건 조회
    • ALPHA [신규] 콤보 목록 조회
    • [신규] 상품 CatalogItem
      • 노출 활성화 여부 (enabled) 필드가 추가돼요.
      • 카테고리 내 노출 정렬 순서 (order) 필드가 추가돼요.
    • [신규] 카테고리 CatalogCategory
      • 노출 활성화 여부 (enabled) 필드가 추가돼요.
      • 정렬 순서 (order) 필드가 추가돼요.
    • [신규] 옵션 CatalogOption
      • 노출 활성화 여부 (enabled) 필드가 추가돼요.
      • 정렬 순서 (order) 필드가 추가돼요.
    • [신규] 옵션 선택지 CatalogOptionChoice
      • 노출 활성화 여부 (enabled) 필드가 추가돼요.
      • 옵션 내 정렬 순서 (order) 필드가 추가돼요.

2026-05-08

카탈로그 - 옵션 (CatalogOption) 조회 및 웹훅 이벤트가 추가되었어요.

  • 카탈로그
    • [신규] 상품 CatalogItem
      • 상품에 지정할 수 있는 옵션 목록 (options) 필드가 추가돼요.
    • [신규] 옵션 CatalogOption, 옵션 선택지 CatalogOptionChoice
    • [신규] 옵션 단건 조회
    • [신규] 옵션 복수건 조회
    • [신규] 옵션 목록 조회
    • [신규] 이벤트: 옵션 생성됨 (catalog.option.created.v1)
    • [신규] 이벤트: 옵션 수정됨 (catalog.option.updated.v1)
    • [신규] 이벤트: 옵션 삭제됨 (catalog.option.deleted.v1)

2026-05-06

카탈로그 - 카테고리 (CatalogCategory) 조회 및 웹훅 이벤트가 추가되었어요.

  • 카탈로그
    • [신규] 상품 CatalogItem
      • 상품의 카테고리 (category) 필드가 추가돼요.
    • [신규] 카테고리 CatalogCategory
    • [신규] 상품 검색
    • [신규] 카테고리 단건 조회
    • [신규] 카테고리 복수건 조회
    • [신규] 카테고리 목록 조회
    • [신규] 이벤트: 카테고리 생성됨 (catalog.category.created.v1)
    • [신규] 이벤트: 카테고리 수정됨 (catalog.category.updated.v1)
    • [신규] 이벤트: 카테고리 삭제됨 (catalog.category.deleted.v1)

2026-04-28

앱 설치 및 설치 해제 웹훅 이벤트가 추가되었어요. 이벤트를 수신하여 매장에서 앱을 설치한 시점에 초기화를 수행하거나, 설치 해제 시 데이터를 파기하는 등 적절한 행동을 취할 수 있어요.

  • 웹훅
    • [신규] 이벤트: 매장에 앱 설치됨 (app.installation.created.v1)
    • [신규] 이벤트: 매장에서 앱 설치 해제됨 (app.installation.deleted.v1)

2026-04-17

웹훅 설정이 개발자센터에서 직접 가능하도록 변경되었어요. 기존에 담당자 수기 설정으로 진행되던 웹훅 등록/변경을 셀프 서비스로 처리할 수 있어요.

  • 웹훅
    • [변경] 웹훅 설정 방식: 담당자 수기 설정 → 개발자센터 직접 설정 지원

2026-03-31

자동 적용되는 할인 정책을 묶음으로 조회할 수 있는 API가 추가돼요.

  • 할인
    • [신규] 할인 정책 자동 적용 (묶음 요청)

2026-03-23

웹훅(Webhook) 이벤트가 추가되었어요. 매장 정보 변경 및 상품 생성·수정·삭제 시 이벤트를 수신할 수 있어요.

  • 웹훅
    • [신규] 웹훅 공통 안내 추가
  • 매장
    • [신규] 이벤트: 매장 정보 변경됨 (merchant.merchant.updated.v1)
  • 카탈로그
    • [신규] 이벤트: 상품 생성됨 (catalog.item.created.v1)
    • [신규] 이벤트: 상품 수정됨 (catalog.item.updated.v1)
    • [신규] 이벤트: 상품 삭제됨 (catalog.item.deleted.v1)

2026-03-19

카탈로그 - 상품 (CatalogItem) 모델에 labels 필드가 추가돼요. "신규", "인기" 등 토스 POS에서 상품에 지정할 수 있는 라벨을 확인할 수 있어요.

  • 카탈로그
    • [신규] 상품 CatalogItem
      • 상품 라벨 목록 (labels) 필드가 추가돼요.

2026-02-20

주문 목록 조회 시, 결제가 아직 하나도 이루어지지 않은 OPENED(시작됨) 및 REQUESTED(주문 수락 전) 상태의 주문을 조회할 수 있도록 허용해요.

  • 주문
    • [변경] 주문 목록 조회
      • 기존 동작: 결제가 아직 하나도 이루어지지 않은 주문은 조회할 수 없어요. (orderStates 파라미터를 사용해도 이러한 제한이 적용되었어요.)
      • 변경 동작: 결제가 아직 하나도 이루어지지 않은 주문도 조회할 수 있어요. orderStates 파라미터에 OPENED 또는 REQUESTED 상태를 지정하면 이러한 주문도 목록에서 반환돼요.
      • 유의: orderStates 파라미터를 사용하지 않는 경우 결과는 기존과 동일해요. orderStates 파라미터의 기본값이 ["COMPLETED", "CANCELLED"] 인 것처럼 동작한다고 볼 수 있어요.

2025-11-28

카탈로그와 할인 관련 API가 추가되었어요.

  • 카탈로그
    • [신규] 상품 단건 조회
    • [신규] 상품 복수건 조회
    • [신규] 상품 목록 조회
  • 할인
    • [신규] 할인 정책 자동 적용
  • 주문
    • Discount 모델이 할인 하위 모델로 이동했어요.

2025-09-01

Open API의 초기 버전이에요.

  • 일반
    • [신규] Open API 버전 정보 조회
  • 매장
    • [신규] 매장 정보 조회
  • 주문
    • [신규] 주문 단건 조회
    • [신규] 주문 복수건 조회
    • [신규] 주문 목록 조회
  • 결제
    • [신규] 결제 단건 조회
    • [신규] 주문의 결제건 모두 조회