Discount API

토스 POS의 [상품] - [상품 · 할인] - [할인] 메뉴를 통해 할인 정책을 관리할 수 있어요. Discount API를 통해 매장 내의 할인 정책을 조회할 수 있어요.

Types

할인 정책 (DiscountPolicy)

할인 정책은 특정 주문에 대해 할인 적용 여부, 어떤 상품에 할인이 적용되는지, 적용 금액을 정의하는 규칙이에요.

Name	Type	Required	Description	Example
id	String	✅	할인 정책 ID	"42"
title	String	✅	할인명	"PROMOTION"
type	String	✅	할인 종류 (예: "FIXED_AMOUNT", "FIXED_PERCENTAGE")	"FIXED_AMOUNT"
code	String		할인 코드	"PROMOTION_00"
amount	Long	✅	정액할인 금액 (정액할인이 아닌 경우 0)	1000
percentage	Double	✅	정률할인 비율 (정률할인이 아닌 경우 0.0)	0.0
maxAmount	Long		최대 할인 금액	3000
autoApply	DiscountAutoApply		할인 자동 적용 규칙

할인 자동 적용 규칙 (DiscountAutoApply)

Name	Type	Required	Description	Example
condition	DiscountAutoApplyCondition	✅	할인 자동 적용 조건
targets	DiscountAutoApplyTarget[]		할인 자동 적용 대상

할인 자동 적용 조건 (DiscountAutoApplyCondition)

Name	Type	Required	Description	Example
appliedToAll	Boolean	✅	모든 주문에 할인 적용 여부	true
diningOptions	OrderDiningOption[]		할인을 적용할 식사 옵션 (매장 식사, 포장 등)	["HERE", "TOGO"]
schedule	DiscountAutoApplySchedule		할인 자동 적용 스케줄

할인 자동 적용 스케줄 (DiscountAutoApplySchedule)

Name	Type	Required	Description	Example
dayOfWeeks	String[]		할인 자동 적용 요일	["SATURDAY", "SUNDAY"]
dateRange	{ "start": LocalDate, "end": LocalDate }		할인 자동 적용 기간 (inclusive)	{ "start": "2025-09-01", "end": "2025-09-30" }
timeRange	{ "start": LocalTime, "end": LocalTime }		할인 자동 적용 시간대 (inclusive)	{ "start": "10:00:00", "end": "17:59:59" }

할인 적용 대상 (DiscountAutoApplyTarget)

Name	Type	Required	Description	Example
targetType	DiscountAutoApplyTargetType	✅	할인 적용 대상 종류 (카테고리, 상품)	"ITEM"
targetId	String	✅	할인 적용 대상 ID	"42"

할인 적용 대상 종류 (DiscountAutoApplyTargetType)

Value	Description
"ITEM"	상품
"CATEGORY"	카테고리
"UNDEFINED"

할인 정책 자동 적용 요청 (DiscountPolicyAutoApplyRequest)

Name	Type	Required	Description	Example
itemId	String		상품 ID 상품은 할인 정책의 자동 적용 대상 (DiscountAutoApplyTarget) 에 따라 할인이 적용돼요. 상품 또는 상품이 속한 카테고리를 대상으로 하는 할인 정책이 자동 적용돼요.	"42"

Methods

할인 정책 단건 조회

Property	Value
Method	GET
Path	/api-public/openapi/v1/merchants/{merchantId}/discount/discount-policies/{discountPolicyId}
Response Body	DiscountPolicy
Description	매장의 할인 정책 하나를 조회해요. 정책 정의를 확인하는 용도로 사용해 주세요. 실제 할인 적용 여부와 금액은 주문 결과를 통해 확인하는 것을 권장해요. 할인 자동 적용 규칙은 계속 추가·변경될 수 있어요.

요청 파라미터

Parameter	Location	Type	Required	Description
merchantId	Path	Long	✅	매장 ID
discountPolicyId	Path	String	✅	할인 정책 ID

할인 정책 복수건 조회

Property	Value
Method	GET
Path	/api-public/openapi/v1/merchants/{merchantId}/discount/discount-policies/by-ids
Response Body	DiscountPolicy[]
Description	ID를 통해 매장의 할인 정책 여러 건을 조회해요. 최대 25건까지 조회 가능해요. 정책 정의를 확인하는 용도로 사용해 주세요. 실제 할인 적용 여부와 금액은 주문 결과를 통해 확인하는 것을 권장해요. 할인 자동 적용 규칙은 계속 추가·변경될 수 있어요.

요청 파라미터

Parameter	Location	Type	Required	Description
merchantId	Path	Long	✅	매장 ID
ids	Query	String[]	✅	할인 정책 ID 목록

할인 정책 목록 조회

Property	Value
Method	GET
Path	/api-public/openapi/v1/merchants/{merchantId}/discount/discount-policies
Response Body	DiscountPolicy[]
Description	매장에 등록된 할인 정책 목록을 조회해요. 정책 정의를 확인하는 용도로 사용해 주세요. 실제 할인 적용 여부와 금액은 주문 결과를 통해 확인하는 것을 권장해요. 할인 자동 적용 규칙은 계속 추가·변경될 수 있어요.

요청 파라미터

Parameter	Location	Type	Required	Default	Description
merchantId	Path	Long	✅	-	매장 ID
page	Query	Int		1	조회할 페이지
size	Query	Int		100	페이지 크기

할인 정책 자동 적용

Property	Value
Method	POST
Path	/api-public/openapi/v1/merchants/{merchantId}/discount/discount-policies/auto-apply
Response Body	DiscountPolicy[]
Description	주어진 요청에 자동 적용될 수 있는 할인 정책을 확인해요.

요청 파라미터

Parameter	Location	Type	Required	Description
merchantId	Path	Long	✅	매장 ID

요청 Body (DiscountPolicyAutoApplyRequest)

Name	Type	Required	Description	Example
itemId	String		상품 ID 상품은 할인 정책의 자동 적용 대상 (DiscountAutoApplyTarget) 에 따라 할인이 적용돼요. 상품 또는 상품이 속한 카테고리를 대상으로 하는 할인 정책이 자동 적용돼요.	"42"

할인 정책 자동 적용 (묶음 요청)

Property	Value
Method	POST
Path	/api-public/openapi/v1/merchants/{merchantId}/discount/discount-policies/batch-auto-apply
Response Body	DiscountPolicy[][]
Description	주어진 요청에 자동 적용될 수 있는 할인 정책을 확인해요. - 묶음 요청은 최대 100건까지 가능해요. - 응답은 묶음 요청의 순서 그대로 반환돼요.

요청 파라미터

Parameter	Location	Type	Required	Description
merchantId	Path	Long	✅	매장 ID

요청 Body

Name	Type	Required	Description	Example
batch	DiscountPolicyAutoApplyRequest[]	✅	묶음 요청