연동가이드

주문 - 주문 생성 ​

개요 ​

주문 생성 API를 호출하여 토스 POS 주문을 생성할 수 있어요. 주문을 생성할 때는 주문 내역, 청구 금액, 결제 내역, 할인 내역, 적립 내역, 혜택 사용 내역 등 주문에 포함되는 구성 요소 정보를 전달해야 해요. Open API를 통해 생성한 토스 POS 주문과 결제 내역은 토스 POS [현황] 탭 및 [매출] - [결제내역] 메뉴에서 확인할 수 있어요.

WARNING

주문 생성 API는 추후 공지가 있을 때까지 승인을 받은 앱에서만 사용할 수 있어요.

아래 정보를 개발자센터 지원 이메일으로 보내주시면 검토 후 순차적으로 권한을 부여해 드려요.

  • 개발자센터 계정 이메일
  • 앱 이름
  • 설치(이용) 매장 정보
  • 주문 생성 기능 사용에 대해 매장이 인지하고 있는지 여부
  • 사용 목적

생성한 주문이 토스 POS에 보이지 않아요

주문 생성 API가 성공했지만 [현황] 탭에 주문이 보이지 않으면 아래 항목을 확인해 주세요.

  • 업종: 매장 업종이 카페 또는 음식점인지 확인해요. 도소매업과 서비스업은 [현황] 탭을 지원하지 않아요.
  • 토스 POS 실행 상태: 주문을 확인할 매장의 토스 POS가 정상 실행 중인지 확인해요.
  • 주문 표시 설정: [현황] > [주문표시] 메뉴에서 해당 Open API 앱이 선택되어 있는지 확인해요.
  • 주문 표시 범위: [현황] 탭에는 당일 생성한 주문만 표시돼요.

주문 기본 정보 ​

주문을 생성할 때 전달하는 기본 정보에 관한 설명이에요.

  • 주문 키 (식별자) (orderKey): 주문을 식별하는 고유한 값이에요. UUID 등 전역적으로 고유한 값 사용을 권장해요. 이미 존재하는 주문과 값이 중복될 경우 주문 생성이 거부돼요. 주문 생성 API를 사용할 때, 이 값에 호출 측의 식별자를 지정하면 중복 주문 생성을 방지할 수 있어요.
  • 주문번호 (orderNumber): 매장을 운영하거나 이용하는 사람이 주문을 확인하는 데 사용하는 주문번호예요. ("042번 주문" 과 같은 형태) 토스 POS 결제내역, 주문 현황, 주문서, 영수증 등에 표시되는 값이에요.
  • 주문 요청 정보 (requestedInfo): 매장에서 수락 또는 거절할 수 있는 주문의 경우 주문 요청 정보를 포함하여 전달하세요. 요청 정보를 전달하지 않는 경우 주문은 시작됨(OPENED) 상태로 생성돼요.
  • 주문 메모 (memo): 주문자 또는 매장 운영자가 주문에 대해 추가로 작성한 메모예요. 토스 POS의 [현황] 탭에서 확인할 수 있어요.
주문 기본 정보

주문 내역 구성 ​

주문 내역을 구성할 때는 카탈로그에 등록한 상품 및 옵션 정보를 활용하거나, 임의로 상품 및 옵션 정보를 작성하여 등록할 수 있어요. 카탈로그에 등록한 상품이나 옵션은 카탈로그 API를 통해 조회한 정보를 사용하세요. 주문 내역은 상품 및 수량, 선택한 옵션 정보, 가격 정보를 포함하고 있어요. 가격 정보는 고객이 주문한 시점에 확인하고 결제한 금액을 기준으로 작성해야 해요.

아래는 주문 생성 API 요청에 포함할 아메리카노 1잔과 HOT 옵션을 선택한 주문 내역 (OrderLineItem.Create 타입) 예시예요. 카탈로그에 등록된 상품 ID, 옵션 ID, 옵션 선택지 ID를 사용하는 것을 볼 수 있어요.

json
{
  "diningOption": "HERE", // 식사 옵션: 매장 식사
  "targetType": "ITEM",   // 주문 대상: 상품
  "targetId": "42",       // 상품 ID ("아메리카노")
  "itemPrice": {          // 상품 가격 (5500원, 부가세 포함)
    "title": "기본",
    "priceType": "FIXED",
    "priceUnit": 1,
    "priceValue": 5500,
    "isTaxFree": false,
    "taxInclusive": true
  },
  "quantity": 1,          // 주문 수량
  "optionChoices": [
    {
      "optionId": "42",       // 옵션 ID ("온도")
      "optionChoiceId": "37", // 옵션 선택지 ID ("HOT")
      "price": 0,             // 옵션 선택지 추가 가격
      "quantity": 1           // 옵션 선택지 수량
    }
  ]
}

토스 POS의 카탈로그에 등록되지 않은 상품도 주문 내역에 등록할 수 있어요. 아래는 카탈로그에 등록되지 않은 상품 및 옵션 정보를 임의로 작성하여 주문 내역에 포함하는 예시예요.

json
{
  "diningOption": "HERE", // 식사 옵션: 매장 식사
  "targetType": "AD_HOC", // 주문 대상: 임의 상품 (토스 POS 카탈로그에 등록되지 않은 상품 및 옵션)
  "item": {
    "title": "아메리카노",   // 상품명
    "code": "00000",      // 상품 코드
    "category": {
      "title": "커피",     // 카테고리명
      "code": "00000"     // 카테고리 코드
    }
  },
  "itemPrice": {
    "title": "기본",
    "priceType": "FIXED",
    "priceUnit": 1,
    "priceValue": 5500,
    "isTaxFree": false,
    "taxInclusive": true
  },
  "quantity": 1,
  "optionChoices": [
    {
      "title": "HOT",         // 선택지명
      "code": "00000",        // 선택지 코드
      "option": {
        "title": "온도"        // 옵션명
      },
      "price": 0,             // 옵션 추가 가격
      "quantity": 1           // 옵션 수량
    }
  ]
}

콤보(세트상품)을 주문하는 경우, 콤보 구성 상품을 해당 주문 내역에 포함해야 해요. 아래는 콤보 구성 상품을 주문 내역에 포함하는 예시예요.

콤보 기능이 보이지 않아요

ALPHA 콤보(세트) 기능은 현재 일부 매장에만 지원 중인 기능이에요.

json
{
  "diningOption": "HERE", // 식사 옵션: 매장 식사
  "targetType": "COMBO",  // 주문 대상: 콤보
  "targetId": "42",       // 콤보 ID ("음료+디저트 세트")
  "itemComponents": [     // 고객이 선택한 콤보 구성
    {
      "comboTargetId": "37", // 콤보 구성 ID ("음료")
      "addOnPriceAmount": 0, // 구성 상품 선택 추가금
      "quantity": 1,         // 구성 상품 수량
      "optionChoices": [     // 구성 상품에 선택한 옵션
        {
          "optionChoiceId": "37", // 옵션 선택지 ID ("HOT")
          "price": 0,             // 옵션 선택지 추가 가격
          "quantity": 1           // 옵션 선택지 수량
        }
      ]
    },
    {
      "comboTargetId": "38", // 콤보 구성 ID ("디저트")
      "addOnPriceAmount": 0, // 구성 상품 선택 추가금
      "quantity": 1,         // 구성 상품 수량
      "optionChoices": []
    }
  ],
  "itemPrice": { // 콤보 가격 (9000원, 부가세 포함)
    "title": "기본",
    "priceType": "FIXED",
    "priceUnit": 1,
    "priceValue": 9000,
    "isTaxFree": false,
    "taxInclusive": true
  },
  "quantity": 1 // 주문 수량
}

청구 금액 계산 ​

주문의 청구 금액은 주문 생성 API를 호출하는 측에서 계산해야 해요. 청구 금액은 실제로 고객이 결제한 금액을 기준으로 작성해요. 청구 금액이 주문 내역에 기록된 가격 정보와 일치하지 않더라도, 주문 생성 API는 요청을 거부하지 않아요.

아래는 500원 할인이 적용된 5000원 결제를 청구하는 주문의 청구 금액 (OrderChargePrice 타입) 예시예요.

json
{
  "listPrice": 5500,        // 원금액
  "discountAmount": -500,   // 할인금액
  "tipAmount": 0,           // 팁
  "serviceChargeAmount": 0, // 봉사료
  "taxAmount": 454,         // 세액
  "supplyAmount": 4546,     // 공급가액
  "taxExemptAmount": 0,     // 면세금액
  "totalAmount": 5000       // 최종금액
}

결제 내역 기록 ​

이미 결제가 모두 완료된 주문을 생성하는 경우, 주문 생성 API 요청에 결제 내역을 포함하여 전달해야 해요. 결제 내역은 결제 수단, 결제 금액 등 상세 정보를 포함하고 있어요. Open API를 통해 생성한 주문에 포함된 결제건은 모두 외부결제수단으로 처리된다는 점에 유의하세요.

아래는 5000원을 현금으로 결제한 결제 내역 (Payment.Create 타입) 예시예요.

json
{
  "approvedAt": "2025-09-01T00:00:00Z", // 승인 시각
  "amount": 5000,                       // 결제 금액
  "taxAmount": 454,                     // 세액
  "supplyAmount": 4546,                 // 공급가액
  "taxExemptAmount": 0,                 // 면세금액
  "tipAmount": 0,                       // 봉사료
  "cashDetails": {                      // 현금결제 세부 내역
    "buyerSuppliedAmount": 5000,
    "changeBackAmount": 0
  },
  "cashReceipt": {                      // 현금영수증 세부 내역
    "identityNumber": "**********",
    "issuanceType": "PHONE",
    "issuanceNumber": "010********",
    "issuerType": "CONSUMER",
    "issueNumber": "000000000",
    "selfIssuance": false,
    "issuedAt": "2025-09-01T00:00:00Z",
    "amount": 5000
  }
}

할인 내역 기록 ​

할인 내역은 주문 전체에 대해 적용하거나, 주문 내역별로 적용할 수 있어요. 할인 내역을 기록하면 토스 POS 결제내역 및 매출리포트에서 관련 정보를 확인할 수 있어요.

'특별 행사 할인' 500원 할인이 적용된 주문의 할인 내역 (Discount 타입) 예시예요.

json
{
  "title": "특별 행사 할인",
  "type": "FIXED_AMOUNT",
  "code": "PROMOTION_00",
  "amount": 500,
  "percentage": 0.0,
  "fixedAmount": 500
}

ALPHA 적립 내역 기록 ​

적립 내역은 주문 생성 시 함께 전달하거나, 적립 추가 API로 이후에 추가할 수 있어요. 포인트·스탬프를 여러 건씩 적립할 수 있어요.

아래는 포인트 적립 내역 (OrderAccrual 타입) 예시예요.

json
[
  {
    "name": "포인트 적립", 
    "referenceType": "TOSSPOINT",
    "referenceId": "TP-001",
    "occurredAt": "2026-01-01T00:00:00+09:00",
    "pointDetails": {
      "provider": "TOSSPLACE",
      "amount": 100
    }
  }
]

ALPHA 혜택 사용 내역 기록 ​

혜택 사용 내역은 주문 생성 시 함께 전달하거나, 혜택 사용 추가 API로 이후에 추가할 수 있어요. 포인트·쿠폰 사용을 여러 건씩 기록할 수 있어요.

아래는 쿠폰 혜택 사용 내역 (OrderRedemption 타입) 예시예요.

json
[
  {
    "name": "쿠폰 사용",
    "referenceType": "TOSSCOUPON_REDEMPTION",
    "referenceId": "TC-001",
    "occurredAt": "2026-01-01T00:00:00+09:00",
    "couponDetails": {
      "provider": "TOSSPLACE",
      "couponNumber": "CPN-123456",
      "count": 1
    }
  }
]

주문 생성이 거부되는 경우 ​

주문 생성이 거부되는 대표적인 경우는 다음과 같아요. 주문 생성 API 응답의 에러 메시지를 확인하고 적절한 처리가 필요해요.

  • 주문 키 중복: 이미 존재하는 주문과 값이 중복될 경우 주문 생성이 거부돼요.
  • 유효하지 않은 주문 내역
    • 주문 내역에 담은 상품 ID, 옵션 ID, 선택지 ID가 실제로 매장 카탈로그에 존재하지 않는 경우
    • 품절 상태의 상품, 선택지 등을 주문 내역에 포함하는 경우
    • 옵션 선택지 최소, 최대 선택 가능 개수에서 벗어나는 경우

주문서 출력 설정 ​

주문 생성 API 요청의 printOrderSheet 파라미터를 true로 설정하면 토스 POS와 연결된 프린터에서 주문서를 출력할 수 있어요. 매장에서 수락/거절할 수 있는 주문을 생성하는 경우 (주문 요청 정보 requestedInfo 필드를 사용하는 경우) 주문서가 출력되지 않고, 토스 POS에서 주문을 수락할 때 주문서가 자동으로 출력돼요.

토스 POS와 프린터를 연결하는 방법에 대한 자세한 내용은 아티클을 참고해주세요.

Types ​

주문 생성 요청 (Order.Create) ​

NameTypeRequiredDescriptionExample
orderKeyString✅주문 키

주문을 식별하는 용도로 사용하는 문자열이에요. 주문 채널에 따라 고유의 값 체계를 사용할 수 있어요. 최대 128자까지 사용할 수 있어요. UUID 등 전역적으로 고유한 값 사용을 권장해요.		"EXT-20260512-0001"
orderNumberString✅주문 번호

매장을 운영하거나 이용하는 사람이 주문을 확인하는 데 사용하는 주문번호예요. ("042번 주문" 과 같은 형태) 토스 POS 결제내역, 주문 현황, 주문서, 영수증 등에 표시되는 값이에요. 최대 64자까지 사용할 수 있어요. 매장 단위로 일자별 일련번호, 고객명 등 식별이 용이한 값을 권장해요.		"A-001"
lineItemsOrderLineItem.Create[]✅주문 내역
최소 1건 이상 포함해야 해요.
discountsDiscount[]할인 내역
accrualsOrderAccrual[]ALPHA 적립 내역
redemptionsOrderRedemption[]ALPHA 혜택 사용 내역
chargePriceOrderChargePrice✅청구 금액
requestedInfoOrderRequestedInfo.Create주문 요청 정보
입력 시 매장에서 수락/거절할 수 있는 요청 주문이 생성돼요. openedAt과 동시에 사용할 수 없으며, 두 값이 함께 입력된 경우 requestedInfo가 우선해요.
ordererOrderOrderer.CreateALPHA 주문자 정보
scheduledOrderScheduledALPHA 주문 자동 처리 정보
memoString주문 메모"얼음 적게"
openedAttimestamp주문 시작 시각"2025-09-01T00:00:00"

주문 생성 - 주문 내역 (OrderLineItem.Create) ​

  • 주문 대상이 상품(ITEM)인 경우, 상품 ID를 지정해야 해요.
  • 주문 대상이 콤보(COMBO)인 경우, 콤보 ID를 지정하고, 콤보 구성 상품을 작성해야 해요.
  • 주문 대상이 임의 상품(AD_HOC)인 경우, 상품 정보를 작성해야 해요.
NameTypeRequiredDescriptionExample
diningOptionOrderDiningOption✅식사 옵션"HERE"
targetTypeOrderLineItemTargetType주문 대상 (상품, 콤보, 임의 상품) 타입"ITEM"
targetIdString상품 ID
ALPHA: 콤보(세트상품) 주문 내역의 경우 콤보 ID		"42"
itemOrderItem.Create상품 정보
itemComponentsOrderItemComponent.Create[]ALPHA 콤보(세트상품) 구성
itemPriceOrderItemPrice✅상품 가격
quantityLong✅수량1
optionChoicesOrderItemOptionChoice.Create[]선택한 옵션
appliedDiscountsDiscount[]항목별 적용 할인 내역
memoString주문 내역 메모"얼음 적게"

주문 내역 대상 종류 (OrderLineItemTargetType) ​

ValueDescription
"ITEM"상품
"COMBO"콤보
"AD_HOC"임의 상품
"UNDEFINED"

주문 생성 - 주문 상품 정보 (OrderItem.Create) ​

NameTypeRequiredDescriptionExample
titleString✅상품명"아메리카노"
codeString상품 코드""
categoryOrderItemCategory.Create✅상품이 속한 카테고리

주문 생성 - 주문 카테고리 정보 (OrderItemCategory.Create) ​

NameTypeRequiredDescriptionExample
titleString✅카테고리명"커피"
codeString카테고리 코드""

주문 생성 - 주문 내역 옵션 정보 (OrderItemOption.Create) ​

NameTypeRequiredDescriptionExample
titleString✅옵션명"온도"

주문 생성 - 주문 내역 옵션 선택지 (OrderItemOptionChoice.Create) ​

  • 주문 대상이 상품(ITEM)인 경우, 옵션 ID 및 선택지 ID를 지정하여 토스 POS 카탈로그에 등록된 옵션을 사용해요.
  • 주문 대상이 임의 상품(AD_HOC)인 경우, 옵션 정보를 작성해야 해요.
NameTypeRequiredDescriptionExample
optionIdString옵션 ID"42"
optionChoiceIdString선택지 ID"42"
optionOrderItemOption.Create옵션 정보
titleString선택지명"HOT"
codeString선택지 코드""
priceLong✅선택지 가격0
quantityLong✅선택지 수량1

ALPHA 주문 생성 - 콤보(세트상품) 구성 (OrderItemComponent.Create) ​

NameTypeRequiredDescriptionExample
comboTargetIdString✅콤보 구성 ID"42"
addOnPriceAmountLong✅구성 상품 선택 추가금0
quantityLong✅구성 상품 수량1
optionChoicesOrderItemOptionChoice.Create[]구성 상품에 선택한 옵션

주문 생성 - 주문 요청 정보 (OrderRequestedInfo.Create) ​

NameTypeRequiredDescriptionExample
requestedAttimestamp주문 요청 시각"2025-09-01T00:00:00"
expiredAttimestamp주문 요청 만료 시각"2025-09-01T00:00:00"
expectedReadyAttimestamp주문의 예상 완료 시각
손님 기준에서의 예상 완료 시각을 의미합니다. (예: 손님이 15분 뒤 픽업 예정)		"2025-09-01T00:00:00"
estimatedReadyAttimestamp주문의 예상 준비 완료 시각
매장 기준에서의 예상 완료 시각을 의미합니다. (예: 20분 뒤 픽업 가능)		"2025-09-01T00:00:00"
allowedEstimatedReadyDurationsDuration[]ALPHA 주문 수락 시 선택 가능한 예상 준비 완료 시간 목록 (예: 토스 POS에서 예상 준비 시간을 10분, 20분 중 하나로 선택 가능)["PT10M", "PT20M"]

ALPHA 주문 생성 - 주문자 정보 (OrderOrderer.Create) ​

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

NameTypeRequiredDescriptionExample
nameString주문자명"김토스"
phoneNumberString주문자 전화번호"01000000000"
nicknameString주문자 별명"김토스"

ALPHA 주문 자동 처리 정보 (OrderScheduled) ​

NameTypeRequiredDescriptionExample
completionOrderScheduledCompletionALPHA 주문 자동 완료 처리 정책
토스 POS [현황] 화면에서 주문을 완료 처리하지 않아도 자동으로 처리하도록 설정할 수 있어요.

ALPHA 주문 자동 완료 처리 정책 (OrderScheduledCompletion) ​

NameTypeRequiredDescriptionExample
triggerAttimestamp✅주문 자동 완료 처리 설정 시각
주문은 해당 시각에 자동 완료 처리됩니다.		"2025-09-01T00:00:00"

결제 내역 생성 요청 (Payment.Create) ​

NameTypeRequiredDescriptionExample
approvedNoString승인 번호"00000000"
approvedAttimestamp✅승인 시각"2025-09-01T00:00:00"
amountLong✅결제 금액5000
taxAmountLong✅세액454
supplyAmountLong✅공급가액4546
taxExemptAmountLong✅면세금액0
tipAmountLong✅봉사료0
cashDetailsPaymentCashDetails현금결제 세부 내역
cardDetailsPaymentCardDetails카드결제 세부 내역
prepaidValueDetailsPaymentPrepaidValueDetails선불지급수단 결제 세부 내역
accountTransferDetailsPaymentAccountTransferDetails계좌이체 세부 내역
easyPayDetailsPaymentEasyPayDetails간편결제 세부 내역
pgDetailsPaymentPgDetailsPG사 결제 세부 내역
cashReceiptPaymentCashReceipt현금영수증 세부 내역
settlementPaymentSettlement정산 관련 정보
bundlePaymentBundleALPHA 결제 번들 정보

Methods ​

주문 생성 ​

PropertyValue
MethodPOST
Path/api-public/openapi/v1/merchants/{merchantId}/order/orders
Response TypeOrder
Description주문을 생성해요.
생성한 주문은 주문 요청 정보 유무, 결제 완료 여부에 따라 요청됨(REQUESTED), 시작됨(OPENED), 혹은 완료됨(COMPLETED) 상태로 생성돼요. 유효하지 않은 정보를 입력한 경우 주문 생성이 거부돼요.

요청 파라미터

ParameterLocationTypeRequiredDefaultDescription
merchantIdPathLong✅-매장 ID
orderBodyOrder.Create✅-주문 생성 요청
paymentsBodyPayment.Create[]✅-결제 내역 생성 요청
deliveryBodyDelivery.Create-배달 정보 생성 요청
printOrderSheetQueryBooleanfalse주문서 출력 여부

토스 POS와 연결된 프린터에서 주문서를 출력해요.

요청 Body 예시

json
{
  "order": {
    "orderKey": "EXT-20260512-0001",
    "orderNumber": "A-001",
    "lineItems": [
      {
        "diningOption": "HERE",
        "targetType": "ITEM",
        "targetId": "42",
        "itemPrice": {
          "title": "기본",
          "priceType": "FIXED",
          "priceUnit": 1,
          "priceValue": 5500,
          "isTaxFree": false,
          "taxInclusive": true
        },
        "quantity": 1,
        "optionChoices": [
          {
            "optionChoiceId": "37",
            "price": 0,
            "quantity": 1
          }
        ]
      }
    ],
    "discounts": [
      {
        "title": "특별 행사 할인",
        "type": "FIXED_AMOUNT",
        "code": "PROMOTION_00",
        "amount": 500,
        "percentage": 0.0,
        "fixedAmount": 500
      }
    ],
    "accruals": [
      {
        "name": "포인트 적립",
        "referenceType": "TOSSPOINT",
        "referenceId": "ACC-20260101-0001",
        "occurredAt": "2026-01-01T00:00:00+09:00",
        "pointDetails": {
          "provider": "TOSSPLACE",
          "amount": 100
        }
      }
    ],
    "chargePrice": {
      "listPrice": 5500,
      "discountAmount": -500,
      "tipAmount": 0,
      "serviceChargeAmount": 0,
      "taxAmount": 454,
      "supplyAmount": 4546,
      "taxExemptAmount": 0,
      "totalAmount": 5000
    },
    "memo": "개인컵",
    "openedAt": "2025-09-01T00:00:00"
  },
  "payments": [
    {
      "approvedAt": "2025-09-01T00:00:00Z",
      "amount": 5000,
      "taxAmount": 454,
      "supplyAmount": 4546,
      "taxExemptAmount": 0,
      "tipAmount": 0,
      "cashDetails": {
        "buyerSuppliedAmount": 5000,
        "changeBackAmount": 0
      },
      "cashReceipt": {
        "identityNumber": "**********",
        "issuanceType": "PHONE",
        "issuanceNumber": "010********",
        "issuerType": "CONSUMER",
        "issueNumber": "000000000",
        "selfIssuance": false,
        "issuedAt": "2025-09-01T00:00:00Z",
        "amount": 5000
      }
    }
  ]
}

주문 내역 변경 ​

PropertyValue
MethodPUT
Path/api-public/openapi/v1/merchants/{merchantId}/order/orders/{orderId}/update-line-items
Response TypeOrder
Description주문 내역을 변경해요. 주문 내역이 변경됨에 따라 다시 계산한 청구 금액, 할인 내역을 같이 반영해야 해요. 주문 생성 API를 통해 생성한 주문만 내역을 변경할 수 있어요.

요청 파라미터

ParameterLocationTypeRequiredDefaultDescription
merchantIdPathLong✅-매장 ID
orderIdPathString✅-주문 ID
lineItemsBodyOrderLineItem.Create[]✅-변경할 주문 내역
최소 1건 이상 포함해야 해요. 기존 내역은 모두 취소 처리되고, 새로운 내역으로 대체돼요.
discountsBodyDiscount[]-변경할 할인 내역
chargePriceBodyOrderChargePrice-변경할 청구 금액