DraftOrder API

결제 전 임시 주문을 관리하는 API예요. 상품 추가/수정/삭제, 할인 적용, 결제 시작 등의 기능을 제공해요. 아래 이미지의 오른쪽 영역을 뜻해요.

Types

PluginDraftOrder

임시 주문 객체예요.

{
    id?: string;                        // 주문 ID (서버 주문으로 변환된 경우에만 존재)
    lineItems: PluginDraftOrderItem[];  // 주문 항목 목록
    memo?: string;                      // 주문 요청사항
    discounts: PluginDiscount[];        // 주문에 적용된 할인 목록
    price: PluginDraftOrderPrice;       // 가격 정보
    ignorePrint: boolean;               // 프린트 출력 무시 여부
    numGuests?: number;                 // 테이블 인원 수
}

필드	타입	설명
id	string | undefined	주문 ID. 서버 주문으로 변환된 경우에만 존재해요
lineItems	PluginDraftOrderItem[]	주문 항목 목록
memo	string | undefined	주문 요청사항
discounts	PluginDiscount[]	주문에 적용된 할인 목록
price	PluginDraftOrderPrice	가격 정보
ignorePrint	boolean	프린트 출력 무시 여부
numGuests	number | undefined	테이블 인원 수

PluginDraftOrderItem

임시 주문 항목 객체예요.

{
    key: string;                    // 항목 고유 키
    item: {                         // 상품 정보
        id: number;
        title: string;
        category: PluginCatalogCategory;
        options: PluginCatalogItemOption[];
        code?: string;
        type: OrderItemType;
    };
    itemPrice: {                    // 상품 가격 정보
        isTaxFree: boolean;
        priceType: PluginCatalogItemPriceType;
        priceUnit: number;
        priceValue: number;
        sku?: string;
        title: string;
    };
    discount: PluginDiscount[];     // 항목에 적용된 할인 목록
    memo: string;                   // 요청사항
    optionChoices: PluginOrderItemOptionChoice[];  // 선택된 옵션
    quantity: number;               // 수량
    diningOption: PluginOrderDiningOption;         // 식사 유형
    lineItemId?: string;            // 서버 lineItemId
    metadata?: {
        disableMemoEdit?: boolean;      // true: 유저가 메모 수정 불가
        disableOptionEdit?: boolean;    // true: 유저가 옵션 수정 불가
        disableQuantityEdit?: boolean;  // true: 유저가 수량 변경 불가
    };
}

필드	타입	설명
key	string	항목 고유 키
item.title	string	상품명
item.category	PluginCatalogCategory	카테고리
item.options	PluginCatalogItemOption[]	옵션 목록
itemPrice.priceType	'FIXED' | 'VARIABLE' | 'UNIT'	가격 유형
discount	PluginDiscount[]	항목에 적용된 할인 목록
optionChoices	PluginOrderItemOptionChoice[]	선택된 옵션
diningOption	'HERE' | 'TOGO' | 'DELIVERY' | 'PICKUP'	식사 유형
lineItemId	string | undefined	서버 lineItemId
metadata.disableMemoEdit	boolean | undefined	true: 유저가 메모 수정 불가
metadata.disableOptionEdit	boolean | undefined	true: 유저가 옵션 수정 불가
metadata.disableQuantityEdit	boolean | undefined	true: 유저가 수량 변경 불가

Methods

get

현재 임시 주문 정보를 조회해요.

import { posPluginSdk } from '@tossplace/pos-plugin-sdk';

const draftOrder = await posPluginSdk.draftOrder.get();

Parameters

파라미터가 없어요.

Response

Promise<PluginDraftOrder> — 현재 임시 주문이에요.

clear

임시 주문을 초기화해요.

import { posPluginSdk } from '@tossplace/pos-plugin-sdk';

await posPluginSdk.draftOrder.clear();

Parameters

파라미터가 없어요.

Response

반환값이 없어요.

addLineItem

임시 주문에 상품을 추가해요.

TIP

토스 POS에 등록되지 않은 상품을 추가하려면 item.id를 0으로 설정하세요.

import { posPluginSdk } from '@tossplace/pos-plugin-sdk';

const updatedOrder = await posPluginSdk.draftOrder.addLineItem({
    key: 'item-1',          // 생략 시 자동 생성
    item: { /* PluginCatalogItem 기반 */ },
    itemPrice: { /* 가격 정보 */ },
    quantity: 1,
    memo: '',
    discount: [],
    optionChoices: [],
    diningOption: 'HERE',
});

Parameters

PluginDraftOrderItem에서 key만 선택 항목으로 바뀐 객체 하나를 넘겨요.

파라미터	타입	필수	설명
key	string	X	항목 고유 키. 생략하면 POS가 자동으로 만들어요
item.id	number	O	상품 ID. 토스 POS에 등록되지 않은 상품은 0을 넣어요
item.title	string	O	상품명
item.category	PluginCatalogCategory	O	카테고리
item.options	PluginCatalogItemOption[]	O	상품에서 선택할 수 있는 옵션 목록
item.code	string	X	플러그인에서 만든 상품 코드
item.type	'ITEM' | 'DELIVERY_FEE' | 'PREPAID_CARD' | 'MULTI_USE_TICKET' | 'COMBO' | 'GIFT_CARD'	O	상품 유형
itemPrice.title	string	O	상품 가격명
itemPrice.priceType	'FIXED' | 'VARIABLE' | 'UNIT'	O	가격 유형
itemPrice.priceUnit	number	O	가격의 기본 개수
itemPrice.priceValue	number	O	부가가치세(VAT)가 포함된 가격
itemPrice.isTaxFree	boolean	O	비과세 여부
itemPrice.sku	string	X	재고 관리 코드
discount	PluginDiscount[]	O	항목에 적용할 할인 목록. 없으면 빈 배열을 넣어요
memo	string	O	요청사항. 없으면 빈 문자열을 넣어요
optionChoices	PluginOrderItemOptionChoice[]	O	선택된 옵션 목록. 없으면 빈 배열을 넣어요
quantity	number	O	수량
diningOption	'HERE' | 'TOGO' | 'DELIVERY' | 'PICKUP'	O	식사 유형
lineItemId	string	X	서버에서 만들어진 lineItemId
metadata.disableMemoEdit	boolean	X	true면 유저가 요청사항을 수정할 수 없어요
metadata.disableOptionEdit	boolean	X	true면 유저가 옵션을 수정할 수 없어요
metadata.disableQuantityEdit	boolean	X	true면 유저가 수량을 변경할 수 없어요

Response

Promise<PluginDraftOrder> — 상품이 추가된 임시 주문 전체예요.

deleteLineItem

임시 주문에서 특정 항목을 삭제해요.

import { posPluginSdk } from '@tossplace/pos-plugin-sdk';

const updatedOrder = await posPluginSdk.draftOrder.deleteLineItem('item-key');

Parameters

파라미터	타입	필수	설명
itemKey	string	O	삭제할 항목의 key

Response

Promise<PluginDraftOrder> — 변경된 임시 주문 전체예요.

updateItemQuantity

항목의 수량을 변경해요.

import { posPluginSdk } from '@tossplace/pos-plugin-sdk';

const updatedOrder = await posPluginSdk.draftOrder.updateItemQuantity('item-key', 3);

Parameters

파라미터	타입	필수	설명
itemKey	string	O	수량을 바꿀 항목의 key
quantity	number	O	변경할 수량

Response

Promise<PluginDraftOrder> — 변경된 임시 주문 전체예요.

updateItemOptionChoice

항목의 선택 옵션을 변경해요.

import { posPluginSdk } from '@tossplace/pos-plugin-sdk';

const updatedOrder = await posPluginSdk.draftOrder.updateItemOptionChoice('item-key', [
    { id: 1, title: '샷 추가', priceValue: 500, imageUrl: null, state: 'ON_SALE', quantityInputEnabled: false },
]);

Parameters

파라미터	타입	필수	설명
itemKey	string	O	옵션을 바꿀 항목의 key
choices	PluginCatalogItemOptionChoice[]	O	새로 선택할 옵션 목록. 기존 선택을 모두 덮어써요

Response

Promise<PluginDraftOrder> — 변경된 임시 주문 전체예요.

updateItemMemo

항목의 요청사항을 변경해요.

import { posPluginSdk } from '@tossplace/pos-plugin-sdk';

const updatedOrder = await posPluginSdk.draftOrder.updateItemMemo('item-key', '덜 맵게 해주세요');

Parameters

파라미터	타입	필수	설명
itemKey	string	O	요청사항을 바꿀 항목의 key
memo	string	O	변경할 요청사항

Response

Promise<PluginDraftOrder> — 변경된 임시 주문 전체예요.

updateIgnorePrint

주문의 프린트 출력 무시 여부를 설정해요.

import { posPluginSdk } from '@tossplace/pos-plugin-sdk';

const updatedOrder = await posPluginSdk.draftOrder.updateIgnorePrint(true);

Parameters

파라미터	타입	필수	설명
ignorePrint	boolean	O	true면 이 주문의 프린트 출력을 무시해요. 다른 POS에서도 함께 무시돼요

Response

Promise<PluginDraftOrder> — 변경된 임시 주문 전체예요.

deleteDiscount

주문 전체에 적용된 할인을 삭제해요.

import { posPluginSdk } from '@tossplace/pos-plugin-sdk';

// discounts 배열의 인덱스를 전달합니다
const updatedOrder = await posPluginSdk.draftOrder.deleteDiscount(0);

Parameters

파라미터	타입	필수	설명
indexOfDiscount	number	O	임시 주문의 discounts 배열에서 삭제할 할인의 인덱스

Response

Promise<PluginDraftOrder> — 변경된 임시 주문 전체예요.

deleteItemDiscount

특정 항목에 적용된 할인을 삭제해요.

import { posPluginSdk } from '@tossplace/pos-plugin-sdk';

// 항목 키와 discounts 배열의 인덱스를 전달합니다
const updatedOrder = await posPluginSdk.draftOrder.deleteItemDiscount('item-key', 0);

Parameters

파라미터	타입	필수	설명
itemKey	string	O	할인을 삭제할 항목의 key
indexOfDiscount	number	O	해당 항목의 discount 배열에서 삭제할 할인의 인덱스

Response

Promise<PluginDraftOrder> — 변경된 임시 주문 전체예요.

startPayment

임시 주문의 결제를 시작해요. 결제 화면 페이지로 자동 전환돼요.

import { posPluginSdk } from '@tossplace/pos-plugin-sdk';

await posPluginSdk.draftOrder.startPayment();

Parameters

파라미터가 없어요.

Response

반환값이 없어요.

on

임시 주문 변경 이벤트를 구독해요. 코드로 수정 했을 때, 유저가 직접 UI로 수정했을때 모두 발행돼요.

import { posPluginSdk } from '@tossplace/pos-plugin-sdk';

posPluginSdk.draftOrder.on('update', (draftOrder) => {
    console.log('임시 주문 변경됨:', draftOrder);
});

Parameters

파라미터	타입	필수	설명
event	'update'	O	구독할 이벤트. 현재 'update'만 지원해요
callback	(draftOrder: PluginDraftOrder) => void	O	변경된 임시 주문 전체를 받아 실행돼요

Response

반환값이 없어요.

사용 예시

상품 추가 후 결제 시작

import { posPluginSdk } from '@tossplace/pos-plugin-sdk';

async function addItemAndPay(catalogItem: PluginCatalogItem) {
    await posPluginSdk.draftOrder.addLineItem({
        item: {
            id: catalogItem.id,
            title: catalogItem.title,
            category: catalogItem.category,
            options: catalogItem.options,
            code: catalogItem.code,
            type: 'ITEM',
        },
        itemPrice: catalogItem.price,
        quantity: 1,
        memo: '',
        discount: [],
        optionChoices: [],
        diningOption: 'HERE',
    });

    await posPluginSdk.draftOrder.startPayment();
}

임시 주문 변경 감지

import { posPluginSdk } from '@tossplace/pos-plugin-sdk';

posPluginSdk.draftOrder.on('update', (draftOrder) => {
    const totalItems = draftOrder.lineItems.reduce((sum, item) => sum + item.quantity, 0);
    console.log(`총 ${totalItems}개 상품`);
});