@sayren/store-sdk 0.55.1 → 0.56.0

package/dist/index.mjs

@@ -4015,6 +4015,7 @@ const POINT_ENTRY_TYPES = [
 	"EARN_REVIEW",
 	"REVOKE_REVIEW",
 	"EARN_PURCHASE",
+	"REVOKE_PURCHASE",
 	"USE_RESERVE",
 	"USE_RELEASE",
 	"REFUND_RESTORE",
@@ -4047,7 +4048,7 @@ const updatePointPolicyRequestSchema = strictRequest(z$1.object({
 	expiryDays: expiryDays.optional()
 }));
 /** 응답의 원장 유형 — 값이 추가될 수 있어 문자열로 받는다 */
-const responsePointEntryTypeSchema = z$1.union([z$1.enum(POINT_ENTRY_TYPES), z$1.string()]).describe("유형. `EARN_REVIEW` 리뷰 적립 · `REVOKE_REVIEW` 리뷰 삭제 회수 · `EARN_PURCHASE` 구매 적립 · `EXPIRE` 소멸 · `ADJUST` 셀러 지급·차감 · `OPENING` 기존 잔액 이전 · `USE_RESERVE` 결제 사용(결제 시작 때 빠짐) · `USE_RELEASE` 결제가 실패·만료되어 되돌림 · `REFUND_RESTORE` 취소·반품 환불로 반환 · `EARN_COUPON` 적립금 지급 쿠폰. 값이 추가될 수 있어 문자열로 받는다");
+const responsePointEntryTypeSchema = z$1.union([z$1.enum(POINT_ENTRY_TYPES), z$1.string()]).describe("유형. `EARN_REVIEW` 리뷰 적립 · `REVOKE_REVIEW` 리뷰 삭제 회수 · `EARN_PURCHASE` 구매 적립 · `REVOKE_PURCHASE` 판매자 취소의 구매 적립 회수 · `EXPIRE` 소멸 · `ADJUST` 셀러 지급·차감 · `OPENING` 기존 잔액 이전 · `USE_RESERVE` 결제 사용(결제 시작 때 빠짐) · `USE_RELEASE` 결제가 실패·만료되어 되돌림 · `REFUND_RESTORE` 취소·반품 환불로 반환 · `EARN_COUPON` 적립금 지급 쿠폰. 값이 추가될 수 있어 문자열로 받는다");
 /** 원장 항목 — 셀러 조회용(사유·행위자 포함) */
 const pointEntrySchema = z$1.object({
 	entryId: z$1.string(),
@@ -4987,12 +4988,13 @@ const orderCanceledWebhookEventDataSchema = z$1.object({
 	reason: z$1.string().describe("취소 사유 코드 — 판매자 취소 요청의 `reason`(`OUT_OF_STOCK`·`PRICE_ERROR`·`DELIVERY_IMPOSSIBLE`·`ETC`). 사유가 늘어날 수 있어 문자열이다. 모르는 값은 `ETC`처럼 다룬다"),
 	quantity: z$1.number().int().describe("이번에 취소한 수량"),
 	canceledQuantity: z$1.number().int().describe("취소 후 누적 취소 수량"),
-	refundAmount: z$1.number().int().describe("환불액 (원). 수량 비율 상품 실결제 금액(쿠폰 배분을 뺀 금액) + 배송비 환불 − 조건부 무료배송 미달 차감 + 되돌린 쿠폰 차감(`couponChargeRefundAmount`)이다. 결제사 환불 결과는 결제 내역(`GET /v1/payments/{paymentId}`)으로 확인한다"),
+	refundAmount: z$1.number().int().describe("환불액 (원). 수량 비율 상품 실결제 금액(쿠폰 배분을 뺀 금액) + 배송비 환불 − 조건부 무료배송 미달 차감 − 쿠폰 조건 미달 차감 + 되돌린 쿠폰 차감(`couponChargeRefundAmount`) − 추가 차감(`deductAmount`)이다. 결제사 환불 결과는 결제 내역(`GET /v1/payments/{paymentId}`)으로 확인한다"),
 	deliveryFeeRefundAmount: z$1.number().int().describe("환불액에 포함된 배송비 (원)"),
 	deliveryFeeChargeAmount: z$1.number().int().describe("환불액에서 뺀 배송비 (원) — 조건부 무료배송 기준 미달 차감"),
-	couponChargeAmount: z$1.number().int().optional().default(0).describe("환불액에서 뺀 쿠폰 조건 미달 차감 (원). 판매자 취소는 차감하지 않으므로 늘 0이다. 이 필드가 없는 이전 이벤트는 0으로 읽는다"),
+	couponChargeAmount: z$1.number().int().optional().default(0).describe("환불액에서 뺀 쿠폰 조건 미달 차감 (원). 판매자 귀책 취소는 차감하지 않으므로 0이고, 구매자 귀책(`responsibility: BUYER`)이면 생길 수 있다. 이 필드가 없는 이전 이벤트는 0으로 읽는다"),
 	couponChargeRefundAmount: z$1.number().int().optional().default(0).describe("환불액에 더한 금액 (원) — 앞선 환불에서 뺀 쿠폰 조건 미달 차감을 되돌린 몫이다. 전량 취소면 누적 차감이 모두 되돌아간다. 이 필드가 없는 이전 이벤트는 0으로 읽는다"),
 	pointRefundAmount: z$1.number().int().optional().default(0).describe("돌려준 적립금 (원, #93) — 결제에 쓴 적립금 중 이번 취소·반품 수량의 몫이다. 현금 환불(`refundAmount`)과 별개다. 차감은 현금에서 먼저 빼고 모자란 몫만 여기서 뺀다. 적립금을 쓰지 않은 주문과 이 필드가 없는 이전 응답·이벤트는 0으로 읽는다"),
+	deductAmount: z$1.number().int().optional().default(0).describe("환불액에서 뺀 추가 차감 (원, #301) — 판매자가 취소 요청에 넣은 `deductAmount`다. 배송비 차감과 따로 싣는다. 이 필드가 없는 이전 이벤트는 0으로 읽는다"),
 	currency: z$1.string().optional().describe("주문 통화(ISO 4217, 이슈 #130). 이 이벤트의 금액은 모두 이 통화의 최소 단위다. 외화 주문이 생기면 이 값을 확인한다. 이 필드가 없는 이전 이벤트는 KRW다"),
 	testPayment: z$1.boolean().describe("테스트 결제(샌드박스 결제) 주문인가. true면 실제로 돈이 오가지 않았다")
 });
@@ -7214,13 +7216,14 @@ const orderItemFlowSchema = z$1.object({
 		key: z$1.string(),
 		label: z$1.string().describe("셀러용 상태 이름"),
 		coreStatus: orderItemStatusSchema.nullable()
-	})).optional().describe("상태 직접 이동으로 옮길 수 있는 상태(셀러 보기). 흐름이 끝났으면 빈 배열"),
+	})).optional().describe("상태 직접 이동으로 옮길 수 있는 상태(셀러 보기). 흐름이 끝났으면 빈 배열. `coreStatus`가 `CANCELED`인 상태로 옮기면 판매자 취소와 같이 환불한다(#301)"),
 	branches: z$1.array(flowStateSchema).optional().describe("활성 위치가 둘 이상(병렬 가지·하위 흐름)이면 각 위치의 상태. `flowState`는 그 가운데 가장 앞 단계다")
 });
 /** 상태 직접 이동(#115) — 연결선을 지나지 않고 다른 상태로 옮긴다. 블록(재고·환불·송장)은 실행하지 않는다 */
 const moveFlowStateRequestSchema = strictRequest(z$1.object({
 	to: z$1.string().min(1).describe("옮길 상태 키(`moveTargets[].key`)"),
-	reason: z$1.string().trim().max(200).optional().describe("옮긴 사유(실행 기록에 남는다)")
+	reason: z$1.string().trim().max(200).optional().describe("옮긴 사유(실행 기록에 남는다)"),
+	restock: z$1.boolean().optional().describe("취소 상태(`moveTargets[].coreStatus` `CANCELED`)로 옮길 때 재고를 되돌리는가(#301). 취소 상태로 옮기면 판매자 취소와 같이 환불한다. 발송 전은 생략하면 true, 발송 뒤는 생략하면 400 `RESTOCK_REQUIRED`다. 다른 상태로 옮길 때는 무시한다")
 }));
 const flowRunStepSchema = z$1.object({
 	step: z$1.number().int(),
@@ -11181,8 +11184,10 @@ const shippingOrderItemSchema = orderItemSchema.extend({
 	delivery: deliveryInfoSchema.nullable().describe("발송 정보. 발송 전이면 null"),
 	flowStep: z$1.object({
 		key: z$1.string().describe("주문 흐름 안 단계 키(상점이 정한다). 화면 분기에 쓰지 않는다"),
-		label: z$1.string().describe("셀러용 단계 이름")
-	}).nullable().optional().default(null).describe("주문 흐름의 지금 단계(`GET /v1/order-items/{orderItemId}/flow`의 `flowState` 키·이름). 같은 상태라도 단계가 발송을 받지 않으면 발송은 409 `INVALID_STATUS`다. 흐름이 없으면 null. 서버는 항상 싣는다")
+		label: z$1.string().describe("셀러용 단계 이름"),
+		acceptsConfirm: z$1.boolean().optional().default(true).describe("이 단계가 발주 확인(`POST /v1/order-items/{orderItemId}/confirm`)을 받는가. 거짓이면 발주 확인은 409 `INVALID_STATUS`다. 연결선 조건식은 실행 때 다시 판정한다"),
+		acceptsDispatch: z$1.boolean().optional().default(true).describe("이 단계가 발송(`POST /v1/order-items/{orderItemId}/dispatch`)을 받는가. 거짓이면 발송은 409 `INVALID_STATUS`다. 연결선 조건식은 실행 때 다시 판정한다")
+	}).nullable().optional().default(null).describe("주문 흐름의 지금 단계(`GET /v1/order-items/{orderItemId}/flow`의 `flowState` 키·이름). 같은 상태라도 단계가 발송을 받지 않으면 발송은 409 `INVALID_STATUS`다(`acceptsConfirm`·`acceptsDispatch`). 흐름이 없으면 null. 서버는 항상 싣는다")
 });
 const shippingOrderItemPageSchema = pageSchema(shippingOrderItemSchema);
 /**
@@ -11249,7 +11254,11 @@ const cancelBySellerRequestSchema = strictRequest(z$1.object({
 	]),
 	detail: z$1.string().max(500).optional(),
 	quantity: z$1.number().int().min(1).optional().describe("취소할 수량. 생략하면 남은 수량 전체다. 남은 수량보다 크면 400 `INVALID_QUANTITY`. 일부만 취소하면 주문상품은 상태를 유지한 채 `canceledQuantity`가 늘고, 전 수량이 소진되면 `CANCELED`가 된다"),
-	holdRefund: z$1.boolean().optional().describe("true면 주문만 취소하고 결제 환불은 대기로 남긴다(#115). 정산·재고·적립금 반환은 그대로 하고, PG 환불은 결제 상세의 `POST /v1/payments/refunds/{refundId}/process`로 따로 한다. 생략하면 취소와 함께 환불한다")
+	holdRefund: z$1.boolean().optional().describe("true면 주문만 취소하고 결제 환불은 대기로 남긴다(#115). 정산·재고·적립금 반환은 그대로 하고, PG 환불은 결제 상세의 `POST /v1/payments/refunds/{refundId}/process`로 따로 한다. 생략하면 취소와 함께 환불한다"),
+	responsibility: z$1.enum(["SELLER", "BUYER"]).optional().describe("귀책(#301). 생략하면 `SELLER`다. `SELLER`면 배송비를 판매자가 부담하고(환불 정책 `sellerFaultFreeShipping`) 쿠폰 조건 미달 차감을 하지 않는다. `BUYER`면 클레임 승인의 구매자 귀책과 같은 규칙이다(발송 뒤에는 배송비를 돌려주지 않는다). 반품 배송비는 자동으로 빼지 않는다 — 필요하면 `deductAmount`로 뺀다"),
+	deductAmount: z$1.number().int().min(0).optional().describe("환불액에서 뺄 추가 차감(#301, 원). 생략하면 0이다. 현금에서 먼저 빼고 모자란 몫만 돌려줄 적립금에서 뺀다. 환불 원장·`ORDER.CANCELED` 웹훅에 따로 남는다"),
+	restock: z$1.boolean().optional().describe("재고를 되돌리는가(#301). 발송 전(결제완료·발주확인, 배송 없는 상품은 제공 완료까지)은 생략하면 true다. 그 뒤(발송·배송중·배송완료·구매확정)는 생략하면 400 `RESTOCK_REQUIRED`다 — 물건이 돌아왔는지는 판매자가 정한다"),
+	reclaimPurchasePoints: z$1.boolean().optional().describe("구매확정 때 지급한 구매 적립금 중 이번 수량의 몫을 회수하는가(#301). 지급된 구매 적립금이 없으면 무시한다. 생략하면 회수하지 않는다. 회원 잔액이 모자라면 있는 만큼만 회수한다(리뷰 적립 회수와 같은 규칙)")
 }));
 /**
 * 제공 처리 요청 (이슈 #48) — `POST /v1/order-items/{orderItemId}/fulfill`. 배송 없는 주문상품(`MANUAL`)을
@@ -11264,16 +11273,18 @@ const fulfillBulkRequestSchema = strictRequest(z$1.object({
 /** `POST /v1/order-items/{orderItemId}/cancel` 응답 — 셀러 직권취소 환불 결과 */
 const cancelBySellerResultSchema = z$1.object({
 	orderItemId: z$1.string(),
-	refundAmount: z$1.number().int().describe("실제 환불한 금액 — 수량 비율 상품 실결제 금액(쿠폰 배분을 뺀 금액) + 배송비 환불 − 조건부 무료배송 미달 차감 + 되돌린 쿠폰 차감(`couponChargeRefundAmount`)"),
+	refundAmount: z$1.number().int().describe("실제 환불한 금액 — 수량 비율 상품 실결제 금액(쿠폰 배분을 뺀 금액) + 배송비 환불 − 조건부 무료배송 미달 차감 − 쿠폰 조건 미달 차감 + 되돌린 쿠폰 차감(`couponChargeRefundAmount`) − 추가 차감(`deductAmount`)"),
 	quantity: z$1.number().int().describe("취소한 수량"),
 	canceledQuantity: z$1.number().int().describe("취소 후 누적 취소 수량"),
 	deliveryFeeRefundAmount: z$1.number().int().describe("환불에 포함된 배송비. 배송 묶음(같은 상품)이 모두 취소됐고 환불 정책이 켜져 있을 때만 0보다 크다"),
 	deliveryFeeChargeAmount: z$1.number().int().describe("조건부 무료배송 기준 미달로 환불액에서 뺀 배송비. 정책이 꺼져 있으면 항상 0이다"),
-	couponChargeAmount: z$1.number().int().optional().default(0).describe("쿠폰 조건 미달 차감. 판매자 취소는 차감하지 않으므로 늘 0이다. 서버는 항상 싣는다"),
+	couponChargeAmount: z$1.number().int().optional().default(0).describe("쿠폰 조건 미달 차감. 판매자 귀책 취소는 차감하지 않으므로 0이고, 구매자 귀책(`responsibility: BUYER`)이면 생길 수 있다. 서버는 항상 싣는다"),
 	couponChargeRefundAmount: z$1.number().int().optional().default(0).describe("환불액에 더한, 앞선 환불에서 뺀 쿠폰 차감을 되돌린 몫. 서버는 항상 싣는다"),
 	pointRefundAmount: z$1.number().int().optional().default(0).describe("돌려준 적립금 (원, #93) — 결제에 쓴 적립금 중 이번 취소·반품 수량의 몫이다. 현금 환불(`refundAmount`)과 별개다. 차감은 현금에서 먼저 빼고 모자란 몫만 여기서 뺀다. 적립금을 쓰지 않은 주문과 이 필드가 없는 이전 응답·이벤트는 0으로 읽는다"),
 	refundedAt: z$1.string().describe("환불을 요청한 시각. `refundHeld`면 취소 시각이고 환불은 아직 하지 않았다"),
-	refundHeld: z$1.boolean().optional().default(false).describe("결제 환불을 대기로 남겼다(`holdRefund`). 결제 상세에서 환불 처리한다")
+	refundHeld: z$1.boolean().optional().default(false).describe("결제 환불을 대기로 남겼다(`holdRefund`). 결제 상세에서 환불 처리한다"),
+	deductAmount: z$1.number().int().optional().default(0).describe("환불액에서 뺀 추가 차감(#301). 서버는 항상 싣는다"),
+	purchasePointReclaimedAmount: z$1.number().int().optional().default(0).describe("회수한 구매 적립금(#301, `reclaimPurchasePoints`). 잔액이 모자라면 요청한 몫보다 작다. 서버는 항상 싣는다")
 });
 /**
 * `GET /v1/order-items/{orderItemId}/cancel-preview` 응답(#115) — 판매자 취소를 하면 돌려줄 금액. 실제 취소와 같은 계산을
@@ -11285,7 +11296,10 @@ const sellerCancelPreviewSchema = z$1.object({
 	refundAmount: z$1.number().int().describe("현금 환불 예정 금액(배송비 환불·차감 포함)"),
 	pointRefundAmount: z$1.number().int().describe("돌려줄 적립금 (원)"),
 	deliveryFeeRefundAmount: z$1.number().int().describe("환불에 포함될 배송비"),
-	deliveryFeeChargeAmount: z$1.number().int().describe("조건부 무료배송 기준 미달로 뺄 배송비")
+	deliveryFeeChargeAmount: z$1.number().int().describe("조건부 무료배송 기준 미달로 뺄 배송비"),
+	deductAmount: z$1.number().int().optional().default(0).describe("뺄 추가 차감(쿼리 `deductAmount`). 서버는 항상 싣는다"),
+	restockRequired: z$1.boolean().optional().default(false).describe("취소 요청에 `restock`이 있어야 하는가(#301) — 발송 뒤 주문상품이면 true다. 서버는 항상 싣는다"),
+	purchasePointAmount: z$1.number().int().optional().default(0).describe("이번 수량에서 회수할 수 있는 구매 적립금(#301). 0이면 회수할 것이 없다(`reclaimPurchasePoints`를 묻지 않는다). 서버는 항상 싣는다")
 });
 /** `PUT /v1/order-items/{orderItemId}/memo` 응답 — 빈 문자열로 저장하면 메모가 지워져 `null`이다 */
 const orderItemMemoResultSchema = z$1.object({
@@ -12194,7 +12208,10 @@ function createStoreClient(options) {
 			hold: (orderItemId, body) => storeHttp.requestVoid("POST", path`/order-items/${orderItemId}/hold`, { body: holdOrderItemRequestSchema.parse(body) }),
 			releaseHold: (orderItemId) => storeHttp.requestVoid("DELETE", path`/order-items/${orderItemId}/hold`),
 			/** 판매자 취소 미리보기(#115) — 취소하면 돌려줄 현금·적립금. 생략한 수량은 남은 수량 전체다 */
-			cancelPreview: (orderItemId, quantity) => storeHttp.request("GET", path`/order-items/${orderItemId}/cancel-preview`, sellerCancelPreviewSchema, { query: quantity ? { quantity } : {} }),
+			cancelPreview: (orderItemId, query) => {
+				const params = typeof query === "number" ? { quantity: query } : query ?? {};
+				return storeHttp.request("GET", path`/order-items/${orderItemId}/cancel-preview`, sellerCancelPreviewSchema, { query: Object.fromEntries(Object.entries(params).filter(([, value]) => value !== void 0 && value !== 0)) });
+			},
 			cancelBySeller: (orderItemId, body, idempotencyKey) => storeHttp.request("POST", path`/order-items/${orderItemId}/cancel`, cancelBySellerResultSchema, {
 				body: cancelBySellerRequestSchema.parse(body),
 				headers: idempotency(idempotencyKey)
@@ -12514,7 +12531,7 @@ get: (params) => storeHttp.request("GET", "/sales-report", salesReportSchema, {
 			list: (params = {}) => storeHttp.request("GET", "/payments", paymentRecordPageSchema, { query: params }),
 			/** `GET /v1/payments/{paymentId}` — 시도·환불 이력 포함. 404 `PAYMENT_NOT_FOUND` */
 			get: (paymentId) => storeHttp.request("GET", path`/payments/${paymentId}`, paymentRecordDetailSchema),
-			/** `POST /v1/payments/refunds/{refundId}/process` — 대기 환불(`HELD`)을 PG로 환불한다(#115). 409 `REFUND_NOT_HELD` */
+			/** `POST /v1/payments/refunds/{refundId}/process` — 대기(`HELD`)·실패(`FAILED`) 환불을 PG로 환불한다(#115, #301). 409 `REFUND_NOT_HELD` */
 			processRefund: (refundId) => storeHttp.request("POST", path`/payments/refunds/${refundId}/process`, paymentRefundRecordSchema)
 		},
 		/**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayren/store-sdk",
-  "version": "0.55.1",
+  "version": "0.56.0",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
   "exports": {

package/src/client.ts

@@ -274,6 +274,7 @@ import {
   orderSchema,
   orderSummarySchema,
   purchaseDecisionExtendResultSchema,
+  type SellerCancelPreviewQuery,
   type ShippingOrderItemListParams,
   sellerCancelPreviewSchema,
   shippingOrderItemSchema,
@@ -1086,13 +1087,21 @@ export function createStoreClient(options: StoreClientOptions) {
       releaseHold: (orderItemId: string) =>
         storeHttp.requestVoid("DELETE", path`/order-items/${orderItemId}/hold`),
       /** 판매자 취소 미리보기(#115) — 취소하면 돌려줄 현금·적립금. 생략한 수량은 남은 수량 전체다 */
-      cancelPreview: (orderItemId: string, quantity?: number) =>
-        storeHttp.request(
+      cancelPreview: (orderItemId: string, query?: number | SellerCancelPreviewQuery) => {
+        // 두 번째 인자는 수량(이전 호출) 또는 귀책·추가 차감까지 담은 쿼리(#301)다
+        const params: SellerCancelPreviewQuery =
+          typeof query === "number" ? { quantity: query } : (query ?? {});
+        return storeHttp.request(
           "GET",
           path`/order-items/${orderItemId}/cancel-preview`,
           sellerCancelPreviewSchema,
-          { query: (quantity ? { quantity } : {}) as Query },
-        ),
+          {
+            query: Object.fromEntries(
+              Object.entries(params).filter(([, value]) => value !== undefined && value !== 0),
+            ) as Query,
+          },
+        );
+      },
       cancelBySeller: (orderItemId: string, body: CancelBySellerRequest, idempotencyKey?: string) =>
         storeHttp.request(
           "POST",
@@ -1754,7 +1763,7 @@ export function createStoreClient(options: StoreClientOptions) {
       /** `GET /v1/payments/{paymentId}` — 시도·환불 이력 포함. 404 `PAYMENT_NOT_FOUND` */
       get: (paymentId: string) =>
         storeHttp.request("GET", path`/payments/${paymentId}`, paymentRecordDetailSchema),
-      /** `POST /v1/payments/refunds/{refundId}/process` — 대기 환불(`HELD`)을 PG로 환불한다(#115). 409 `REFUND_NOT_HELD` */
+      /** `POST /v1/payments/refunds/{refundId}/process` — 대기(`HELD`)·실패(`FAILED`) 환불을 PG로 환불한다(#115, #301). 409 `REFUND_NOT_HELD` */
       processRefund: (refundId: string) =>
         storeHttp.request(
           "POST",

package/src/schemas/commerce-flow.ts

@@ -136,7 +136,9 @@ export const orderItemFlowSchema = z.object({
       }),
     )
     .optional()
-    .describe("상태 직접 이동으로 옮길 수 있는 상태(셀러 보기). 흐름이 끝났으면 빈 배열"),
+    .describe(
+      "상태 직접 이동으로 옮길 수 있는 상태(셀러 보기). 흐름이 끝났으면 빈 배열. `coreStatus`가 `CANCELED`인 상태로 옮기면 판매자 취소와 같이 환불한다(#301)",
+    ),
   branches: z
     .array(flowStateSchema)
     .optional()
@@ -151,6 +153,13 @@ export const moveFlowStateRequestSchema = strictRequest(
   z.object({
     to: z.string().min(1).describe("옮길 상태 키(`moveTargets[].key`)"),
     reason: z.string().trim().max(200).optional().describe("옮긴 사유(실행 기록에 남는다)"),
+    restock: z
+      .boolean()
+      .optional()
+      .describe(
+        "취소 상태(`moveTargets[].coreStatus` `CANCELED`)로 옮길 때 재고를 되돌리는가(#301). 취소 상태로 옮기면 판매자 취소와 같이 환불한다. " +
+          "발송 전은 생략하면 true, 발송 뒤는 생략하면 400 `RESTOCK_REQUIRED`다. 다른 상태로 옮길 때는 무시한다",
+      ),
   }),
 );
 export type MoveFlowStateRequest = z.infer<typeof moveFlowStateRequestSchema>;

package/src/schemas/order.ts

@@ -493,12 +493,26 @@ export const shippingOrderItemSchema = orderItemSchema.extend({
     .object({
       key: z.string().describe("주문 흐름 안 단계 키(상점이 정한다). 화면 분기에 쓰지 않는다"),
       label: z.string().describe("셀러용 단계 이름"),
+      acceptsConfirm: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe(
+          "이 단계가 발주 확인(`POST /v1/order-items/{orderItemId}/confirm`)을 받는가. 거짓이면 발주 확인은 409 `INVALID_STATUS`다. 연결선 조건식은 실행 때 다시 판정한다",
+        ),
+      acceptsDispatch: z
+        .boolean()
+        .optional()
+        .default(true)
+        .describe(
+          "이 단계가 발송(`POST /v1/order-items/{orderItemId}/dispatch`)을 받는가. 거짓이면 발송은 409 `INVALID_STATUS`다. 연결선 조건식은 실행 때 다시 판정한다",
+        ),
     })
     .nullable()
     .optional()
     .default(null)
     .describe(
-      "주문 흐름의 지금 단계(`GET /v1/order-items/{orderItemId}/flow`의 `flowState` 키·이름). 같은 상태라도 단계가 발송을 받지 않으면 발송은 409 `INVALID_STATUS`다. 흐름이 없으면 null. 서버는 항상 싣는다",
+      "주문 흐름의 지금 단계(`GET /v1/order-items/{orderItemId}/flow`의 `flowState` 키·이름). 같은 상태라도 단계가 발송을 받지 않으면 발송은 409 `INVALID_STATUS`다(`acceptsConfirm`·`acceptsDispatch`). 흐름이 없으면 null. 서버는 항상 싣는다",
     ),
 });
 
@@ -661,6 +675,35 @@ export const cancelBySellerRequestSchema = strictRequest(
         "true면 주문만 취소하고 결제 환불은 대기로 남긴다(#115). 정산·재고·적립금 반환은 그대로 하고, PG 환불은 결제 상세의 " +
           "`POST /v1/payments/refunds/{refundId}/process`로 따로 한다. 생략하면 취소와 함께 환불한다",
       ),
+    responsibility: z
+      .enum(["SELLER", "BUYER"])
+      .optional()
+      .describe(
+        "귀책(#301). 생략하면 `SELLER`다. `SELLER`면 배송비를 판매자가 부담하고(환불 정책 `sellerFaultFreeShipping`) 쿠폰 조건 미달 차감을 하지 않는다. " +
+          "`BUYER`면 클레임 승인의 구매자 귀책과 같은 규칙이다(발송 뒤에는 배송비를 돌려주지 않는다). 반품 배송비는 자동으로 빼지 않는다 — 필요하면 `deductAmount`로 뺀다",
+      ),
+    deductAmount: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe(
+        "환불액에서 뺄 추가 차감(#301, 원). 생략하면 0이다. 현금에서 먼저 빼고 모자란 몫만 돌려줄 적립금에서 뺀다. 환불 원장·`ORDER.CANCELED` 웹훅에 따로 남는다",
+      ),
+    restock: z
+      .boolean()
+      .optional()
+      .describe(
+        "재고를 되돌리는가(#301). 발송 전(결제완료·발주확인, 배송 없는 상품은 제공 완료까지)은 생략하면 true다. " +
+          "그 뒤(발송·배송중·배송완료·구매확정)는 생략하면 400 `RESTOCK_REQUIRED`다 — 물건이 돌아왔는지는 판매자가 정한다",
+      ),
+    reclaimPurchasePoints: z
+      .boolean()
+      .optional()
+      .describe(
+        "구매확정 때 지급한 구매 적립금 중 이번 수량의 몫을 회수하는가(#301). 지급된 구매 적립금이 없으면 무시한다. 생략하면 회수하지 않는다. " +
+          "회원 잔액이 모자라면 있는 만큼만 회수한다(리뷰 적립 회수와 같은 규칙)",
+      ),
   }),
 );
 
@@ -701,7 +744,7 @@ export const cancelBySellerResultSchema = z.object({
     .int()
     .describe(
       "실제 환불한 금액 — 수량 비율 상품 실결제 금액(쿠폰 배분을 뺀 금액) + 배송비 환불 − 조건부 무료배송 미달 차감 " +
-        "+ 되돌린 쿠폰 차감(`couponChargeRefundAmount`)",
+        "− 쿠폰 조건 미달 차감 + 되돌린 쿠폰 차감(`couponChargeRefundAmount`) − 추가 차감(`deductAmount`)",
     ),
   quantity: z.number().int().describe("취소한 수량"),
   canceledQuantity: z.number().int().describe("취소 후 누적 취소 수량"),
@@ -720,7 +763,9 @@ export const cancelBySellerResultSchema = z.object({
     .int()
     .optional()
     .default(0)
-    .describe("쿠폰 조건 미달 차감. 판매자 취소는 차감하지 않으므로 늘 0이다. 서버는 항상 싣는다"),
+    .describe(
+      "쿠폰 조건 미달 차감. 판매자 귀책 취소는 차감하지 않으므로 0이고, 구매자 귀책(`responsibility: BUYER`)이면 생길 수 있다. 서버는 항상 싣는다",
+    ),
   couponChargeRefundAmount: z
     .number()
     .int()
@@ -744,10 +789,31 @@ export const cancelBySellerResultSchema = z.object({
     .optional()
     .default(false)
     .describe("결제 환불을 대기로 남겼다(`holdRefund`). 결제 상세에서 환불 처리한다"),
+  deductAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe("환불액에서 뺀 추가 차감(#301). 서버는 항상 싣는다"),
+  purchasePointReclaimedAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe(
+      "회수한 구매 적립금(#301, `reclaimPurchasePoints`). 잔액이 모자라면 요청한 몫보다 작다. 서버는 항상 싣는다",
+    ),
 });
 
 export type CancelBySellerResult = z.infer<typeof cancelBySellerResultSchema>;
 
+/** `GET /v1/order-items/{orderItemId}/cancel-preview` 쿼리 — 금액에 영향을 주는 취소 입력(#301). 생략하면 취소의 기본값이다 */
+export interface SellerCancelPreviewQuery {
+  quantity?: number;
+  responsibility?: "SELLER" | "BUYER";
+  deductAmount?: number;
+}
+
 /**
  * `GET /v1/order-items/{orderItemId}/cancel-preview` 응답(#115) — 판매자 취소를 하면 돌려줄 금액. 실제 취소와 같은 계산을
  * 쓰기 없이 돌린 결과다. 취소할 수 없는 주문상품은 취소와 같은 409다
@@ -759,6 +825,27 @@ export const sellerCancelPreviewSchema = z.object({
   pointRefundAmount: z.number().int().describe("돌려줄 적립금 (원)"),
   deliveryFeeRefundAmount: z.number().int().describe("환불에 포함될 배송비"),
   deliveryFeeChargeAmount: z.number().int().describe("조건부 무료배송 기준 미달로 뺄 배송비"),
+  deductAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe("뺄 추가 차감(쿼리 `deductAmount`). 서버는 항상 싣는다"),
+  restockRequired: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe(
+      "취소 요청에 `restock`이 있어야 하는가(#301) — 발송 뒤 주문상품이면 true다. 서버는 항상 싣는다",
+    ),
+  purchasePointAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe(
+      "이번 수량에서 회수할 수 있는 구매 적립금(#301). 0이면 회수할 것이 없다(`reclaimPurchasePoints`를 묻지 않는다). 서버는 항상 싣는다",
+    ),
 });
 
 export type SellerCancelPreview = z.infer<typeof sellerCancelPreviewSchema>;

package/src/schemas/points.ts

@@ -189,6 +189,7 @@ export const POINT_ENTRY_TYPES = [
   "EARN_REVIEW",
   "REVOKE_REVIEW",
   "EARN_PURCHASE",
+  "REVOKE_PURCHASE",
   "USE_RESERVE",
   "USE_RELEASE",
   "REFUND_RESTORE",
@@ -257,7 +258,7 @@ export type UpdatePointPolicyRequest = z.infer<typeof updatePointPolicyRequestSc
 export const responsePointEntryTypeSchema = z
   .union([z.enum(POINT_ENTRY_TYPES), z.string()])
   .describe(
-    "유형. `EARN_REVIEW` 리뷰 적립 · `REVOKE_REVIEW` 리뷰 삭제 회수 · `EARN_PURCHASE` 구매 적립 · `EXPIRE` 소멸 · `ADJUST` 셀러 지급·차감 · " +
+    "유형. `EARN_REVIEW` 리뷰 적립 · `REVOKE_REVIEW` 리뷰 삭제 회수 · `EARN_PURCHASE` 구매 적립 · `REVOKE_PURCHASE` 판매자 취소의 구매 적립 회수 · `EXPIRE` 소멸 · `ADJUST` 셀러 지급·차감 · " +
       "`OPENING` 기존 잔액 이전 · `USE_RESERVE` 결제 사용(결제 시작 때 빠짐) · `USE_RELEASE` 결제가 실패·만료되어 되돌림 · " +
       "`REFUND_RESTORE` 취소·반품 환불로 반환 · `EARN_COUPON` 적립금 지급 쿠폰. 값이 추가될 수 있어 문자열로 받는다",
   );

package/src/schemas/webhook-event.ts

@@ -176,7 +176,7 @@ export const orderCanceledWebhookEventDataSchema = z.object({
     .int()
     .describe(
       "환불액 (원). 수량 비율 상품 실결제 금액(쿠폰 배분을 뺀 금액) + 배송비 환불 − 조건부 무료배송 미달 차감 " +
-        "+ 되돌린 쿠폰 차감(`couponChargeRefundAmount`)이다. " +
+        "− 쿠폰 조건 미달 차감 + 되돌린 쿠폰 차감(`couponChargeRefundAmount`) − 추가 차감(`deductAmount`)이다. " +
         "결제사 환불 결과는 결제 내역(`GET /v1/payments/{paymentId}`)으로 확인한다",
     ),
   deliveryFeeRefundAmount: z.number().int().describe("환불액에 포함된 배송비 (원)"),
@@ -190,7 +190,7 @@ export const orderCanceledWebhookEventDataSchema = z.object({
     .optional()
     .default(0)
     .describe(
-      "환불액에서 뺀 쿠폰 조건 미달 차감 (원). 판매자 취소는 차감하지 않으므로 늘 0이다. 이 필드가 없는 이전 이벤트는 0으로 읽는다",
+      "환불액에서 뺀 쿠폰 조건 미달 차감 (원). 판매자 귀책 취소는 차감하지 않으므로 0이고, 구매자 귀책(`responsibility: BUYER`)이면 생길 수 있다. 이 필드가 없는 이전 이벤트는 0으로 읽는다",
     ),
   couponChargeRefundAmount: z
     .number()
@@ -210,6 +210,14 @@ export const orderCanceledWebhookEventDataSchema = z.object({
       "돌려준 적립금 (원, #93) — 결제에 쓴 적립금 중 이번 취소·반품 수량의 몫이다. 현금 환불(`refundAmount`)과 별개다. " +
         "차감은 현금에서 먼저 빼고 모자란 몫만 여기서 뺀다. 적립금을 쓰지 않은 주문과 이 필드가 없는 이전 응답·이벤트는 0으로 읽는다",
     ),
+  deductAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe(
+      "환불액에서 뺀 추가 차감 (원, #301) — 판매자가 취소 요청에 넣은 `deductAmount`다. 배송비 차감과 따로 싣는다. 이 필드가 없는 이전 이벤트는 0으로 읽는다",
+    ),
   currency: z
     .string()
     .optional()