Appearance

주문 - 주문 생성 ​

개요 ​

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

WARNING

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

주문 기본 정보 ​

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

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

주문 내역 구성 ​

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

아래는 주문 생성 API 요청에 포함할 아메리카노 1잔과 HOT 옵션을 선택한 주문 내역 (OrderLineItem.Create 타입) 예시예요.

json
{
  "diningOption": "HERE", // 식사 옵션: 매장 식사
  "targetType": "ITEM",   // 주문 대상: 상품
  "targetId": "42",       // 상품 ID ("아메리카노")
  "itemPrice": {          // 상품 가격 (5500원, 부가세 포함)
    "priceType": "FIXED",
    "priceUnit": 1,
    "priceValue": 5500,
    "isTaxFree": false
  },
  "quantity": 1,          // 주문 수량
  "optionChoices": [
    {
      "optionChoiceId": "37", // 옵션 선택지 ID ("HOT")
      "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원, 부가세 포함)
    "priceType": "FIXED",
    "priceUnit": 1,
    "priceValue": 9000,
    "isTaxFree": false
  },
  "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
}

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

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

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

Types ​

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

NameTypeRequiredDescriptionExample
orderKeyString✅주문 키

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

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

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

NameTypeRequiredDescriptionExample
diningOptionOrderDiningOption✅식사 옵션"HERE"
targetTypeOrderLineItemTargetTypeALPHA 주문 대상 (상품, 콤보) 타입"ITEM"
targetIdString✅상품 ID
ALPHA: 콤보(세트상품) 주문 내역의 경우 콤보 ID		"42"
itemComponentsOrderItemComponent.Create[]ALPHA 콤보(세트상품) 구성
itemPriceOrderItemPrice✅상품 가격
quantityLong✅수량1
optionChoicesOrderItemOptionChoice.Create[]선택한 옵션
appliedDiscountsDiscount[]항목별 적용 할인 내역
memoString주문 내역 메모"얼음 적게"

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

NameTypeRequiredDescriptionExample
optionIdString✅옵션 ID"42"
optionChoiceIdString✅선택지 ID"42"
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"

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

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

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

결제 내역 생성 (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정산 관련 정보

Methods ​

주문 생성 ​

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

요청 파라미터

ParameterLocationTypeRequiredDefaultDescription
merchantIdPathLong✅-매장 ID
orderBodyOrder.Create✅-주문 생성 요청
paymentsBodyPayment.Create[]✅-결제 내역 생성 요청

요청 Body 예시

json
{
  "order": {
    "orderKey": "EXT-20260512-0001",
    "orderNumber": "A-001",
    "lineItems": [
      {
        "diningOption": "HERE",
        "targetType": "ITEM",
        "targetId": "42",
        "itemPrice": {
          "priceType": "FIXED",
          "priceUnit": 1,
          "priceValue": 5500,
          "isTaxFree": false
        },
        "quantity": 1,
        "optionChoices": [
          {
            "optionChoiceId": "37",
            "price": 0,
            "quantity": 1
          }
        ]
      }
    ],
    "discounts": [
      {
        "title": "특별 행사 할인",
        "type": "FIXED_AMOUNT",
        "code": "PROMOTION_00",
        "amount": 500,
        "percentage": 0.0,
        "fixedAmount": 500
      }
    ],
    "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
      }
    }
  ]
}