주문 - 혜택 사용 추가

개요

혜택 사용 추가 API를 호출하여 주문에 혜택 사용 내역을 추가할 수 있어요.

혜택 사용 기본 정보

• referenceType은 혜택 사용의 원천 구분, referenceId는 그 구분 안에서 특정 사용건을 식별하는 ID예요.
• (referenceType, referenceId) 쌍으로 멱등성을 보장하며, 동일 값으로 재요청 시 중복 사용을 방지해요.
• 사용·취소는 pointDetails.amount, couponDetails.count 부호로 구분해요.
• 한 번의 요청으로 여러 건을 추가할 수 있어요. 요청당 전달할 수 있는 사용 건수는 제한이 있어요.

혜택 사용 내역의 상세한 필드 정의는 혜택 사용 내역 (OrderRedemption) 타입을 참고하세요.

Methods

ALPHA 혜택 사용 추가

Property	Value
Method	POST
Path	/api-public/openapi/v1/merchants/{merchantId}/order/orders/{orderId}/redemptions
Response Type	Order
Description	주문에 혜택 사용 내역을 추가해요. 한 번에 여러 건을 추가할 수 있어요. 주문 생성 API를 통해 생성한 주문만 처리할 수 있어요.

요청 파라미터

Parameter	Location	Type	Required	Default	Description
merchantId	Path	Long	✅	-	매장 ID
orderId	Path	String	✅	-	주문 ID
redemptions	Body	OrderRedemption[]	✅	-	추가할 혜택 사용 내역 목록 (최대 100건)

요청 Body 예시

포인트 사용:

{
    "redemptions": [
        {
            "name": "포인트 사용",
            "referenceType": "TOSSPOINT_REDEMPTION",
            "referenceId": "TP-001",
            "occurredAt": "2026-01-01T00:00:00+09:00",
            "pointDetails": {
                "provider": "TOSSPLACE",
                "amount": 500
            }
        }
    ]
}

쿠폰 사용:

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