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();

clear

임시 주문을 초기화합니다.

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

await posPluginSdk.draftOrder.clear();

addLineItem

임시 주문에 상품을 추가합니다.

TIP

토스포스에 등록되지 않은 상품을 추가하려면 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',
});

deleteLineItem

임시 주문에서 특정 항목을 삭제합니다.

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

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

updateItemQuantity

항목의 수량을 변경합니다.

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

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

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 },
]);

updateItemMemo

항목의 요청사항을 변경합니다.

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

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

updateIgnorePrint

주문의 프린트 출력 무시 여부를 설정합니다.

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

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

deleteDiscount

주문 전체에 적용된 할인을 삭제합니다.

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

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

deleteItemDiscount

특정 항목에 적용된 할인을 삭제합니다.

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

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

startPayment

임시 주문의 결제를 시작합니다. 결제 화면 페이지로 자동 전환됩니다.

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

await posPluginSdk.draftOrder.startPayment();

on

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

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

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

사용 예시

상품 추가 후 결제 시작

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}개 상품`);
});