@sayren/store-sdk 0.55.0 → 0.56.0

package/dist/index.d.mts

@@ -3368,6 +3368,7 @@ export declare const orderCanceledWebhookEventDataSchema: z$1.ZodObject<{
   couponChargeAmount: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodNumber>>;
   couponChargeRefundAmount: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodNumber>>;
   pointRefundAmount: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodNumber>>;
+  deductAmount: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodNumber>>;
   currency: z$1.ZodOptional<z$1.ZodString>;
   testPayment: z$1.ZodBoolean;
 }, z$1.core.$strip>;
@@ -3613,6 +3614,7 @@ export declare const orderCanceledWebhookEventSchema: z$1.ZodObject<{
     couponChargeAmount: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodNumber>>;
     couponChargeRefundAmount: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodNumber>>;
     pointRefundAmount: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodNumber>>;
+    deductAmount: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodNumber>>;
     currency: z$1.ZodOptional<z$1.ZodString>;
     testPayment: z$1.ZodBoolean;
   }, z$1.core.$strip>;
@@ -4013,6 +4015,7 @@ export declare const webhookEventSchema: z$1.ZodDiscriminatedUnion<[z$1.ZodObjec
     couponChargeAmount: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodNumber>>;
     couponChargeRefundAmount: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodNumber>>;
     pointRefundAmount: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodNumber>>;
+    deductAmount: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodNumber>>;
     currency: z$1.ZodOptional<z$1.ZodString>;
     testPayment: z$1.ZodBoolean;
   }, z$1.core.$strip>;
@@ -6176,8 +6179,8 @@ export declare const claimSchema: z$1.ZodObject<{
   }>;
   reasonDetail: z$1.ZodNullable<z$1.ZodString>;
   responsibility: z$1.ZodEnum<{
-    BUYER: "BUYER";
     SELLER: "SELLER";
+    BUYER: "BUYER";
   }>;
   claimDeliveryFee: z$1.ZodNumber;
   expectedRefundAmount: z$1.ZodNullable<z$1.ZodNumber>;
@@ -6266,8 +6269,8 @@ export declare const claimDetailSchema: z$1.ZodObject<{
   }>;
   reasonDetail: z$1.ZodNullable<z$1.ZodString>;
   responsibility: z$1.ZodEnum<{
-    BUYER: "BUYER";
     SELLER: "SELLER";
+    BUYER: "BUYER";
   }>;
   claimDeliveryFee: z$1.ZodNumber;
   expectedRefundAmount: z$1.ZodNullable<z$1.ZodNumber>;
@@ -6311,9 +6314,9 @@ export declare const claimDetailSchema: z$1.ZodObject<{
       WITHDRAWN: "WITHDRAWN";
     }>;
     actor: z$1.ZodEnum<{
-      SYSTEM: "SYSTEM";
-      BUYER: "BUYER";
       SELLER: "SELLER";
+      BUYER: "BUYER";
+      SYSTEM: "SYSTEM";
     }>;
     occurredAt: z$1.ZodString;
   }, z$1.core.$strip>>>;
@@ -7135,6 +7138,7 @@ export type OrderItemFlow = z$1.infer<typeof orderItemFlowSchema>;
 export declare const moveFlowStateRequestSchema: z$1.ZodObject<{
   to: z$1.ZodString;
   reason: z$1.ZodOptional<z$1.ZodString>;
+  restock: z$1.ZodOptional<z$1.ZodBoolean>;
 }, z$1.core.$strip>;
 export type MoveFlowStateRequest = z$1.infer<typeof moveFlowStateRequestSchema>;
 export declare const flowRunStepSchema: z$1.ZodObject<{
@@ -9010,8 +9014,8 @@ export type ConsentAction = z$1.infer<typeof consentActionSchema>;
  * `RECONSENT` 약관 개정 재동의 · `MEMBER_UPDATE` 구매자가 직접 변경 · `SELLER` 셀러가 처리
  */
 export declare const consentSourceSchema: z$1.ZodEnum<{
-  SIGNUP: "SIGNUP";
   SELLER: "SELLER";
+  SIGNUP: "SIGNUP";
   SOCIAL_SIGNUP: "SOCIAL_SIGNUP";
   DELEGATED: "DELEGATED";
   RECONSENT: "RECONSENT";
@@ -9033,8 +9037,8 @@ export declare const customerConsentSchema: z$1.ZodObject<{
     AGREED: "AGREED";
   }>;
   source: z$1.ZodEnum<{
-    SIGNUP: "SIGNUP";
     SELLER: "SELLER";
+    SIGNUP: "SIGNUP";
     SOCIAL_SIGNUP: "SOCIAL_SIGNUP";
     DELEGATED: "DELEGATED";
     RECONSENT: "RECONSENT";
@@ -11139,6 +11143,12 @@ export declare const shippingOrderItemSchema: z$1.ZodObject<{
     dispatchedAt: z$1.ZodString;
     deliveredAt: z$1.ZodNullable<z$1.ZodString>;
   }, z$1.core.$strip>>;
+  flowStep: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodNullable<z$1.ZodObject<{
+    key: z$1.ZodString;
+    label: z$1.ZodString;
+    acceptsConfirm: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodBoolean>>;
+    acceptsDispatch: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodBoolean>>;
+  }, z$1.core.$strip>>>>;
 }, z$1.core.$strip>;
 export type ShippingOrderItem = z$1.infer<typeof shippingOrderItemSchema>;
 export declare const shippingOrderItemPageSchema: z$1.ZodObject<{
@@ -11293,6 +11303,12 @@ export declare const shippingOrderItemPageSchema: z$1.ZodObject<{
       dispatchedAt: z$1.ZodString;
       deliveredAt: z$1.ZodNullable<z$1.ZodString>;
     }, z$1.core.$strip>>;
+    flowStep: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodNullable<z$1.ZodObject<{
+      key: z$1.ZodString;
+      label: z$1.ZodString;
+      acceptsConfirm: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodBoolean>>;
+      acceptsDispatch: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodBoolean>>;
+    }, z$1.core.$strip>>>>;
   }, z$1.core.$strip>>;
 }, z$1.core.$strip>;
 export type ShippingOrderItemPage = z$1.infer<typeof shippingOrderItemPageSchema>;
@@ -11400,6 +11416,13 @@ export declare const cancelBySellerRequestSchema: z$1.ZodObject<{
   detail: z$1.ZodOptional<z$1.ZodString>;
   quantity: z$1.ZodOptional<z$1.ZodNumber>;
   holdRefund: z$1.ZodOptional<z$1.ZodBoolean>;
+  responsibility: z$1.ZodOptional<z$1.ZodEnum<{
+    SELLER: "SELLER";
+    BUYER: "BUYER";
+  }>>;
+  deductAmount: z$1.ZodOptional<z$1.ZodNumber>;
+  restock: z$1.ZodOptional<z$1.ZodBoolean>;
+  reclaimPurchasePoints: z$1.ZodOptional<z$1.ZodBoolean>;
 }, z$1.core.$strip>;
 export type CancelBySellerRequest = z$1.infer<typeof cancelBySellerRequestSchema>;
 /**
@@ -11429,8 +11452,16 @@ export declare const cancelBySellerResultSchema: z$1.ZodObject<{
   pointRefundAmount: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodNumber>>;
   refundedAt: z$1.ZodString;
   refundHeld: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodBoolean>>;
+  deductAmount: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodNumber>>;
+  purchasePointReclaimedAmount: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodNumber>>;
 }, z$1.core.$strip>;
 export type CancelBySellerResult = z$1.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다
@@ -11442,6 +11473,9 @@ export declare const sellerCancelPreviewSchema: z$1.ZodObject<{
   pointRefundAmount: z$1.ZodNumber;
   deliveryFeeRefundAmount: z$1.ZodNumber;
   deliveryFeeChargeAmount: z$1.ZodNumber;
+  deductAmount: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodNumber>>;
+  restockRequired: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodBoolean>>;
+  purchasePointAmount: z$1.ZodDefault<z$1.ZodOptional<z$1.ZodNumber>>;
 }, z$1.core.$strip>;
 export type SellerCancelPreview = z$1.infer<typeof sellerCancelPreviewSchema>;
 /** `PUT /v1/order-items/{orderItemId}/memo` 응답 — 빈 문자열로 저장하면 메모가 지워져 `null`이다 */
@@ -13025,7 +13059,7 @@ export declare function pointExpiresAtOf(earnedAt: Date, days: number | null): D
 export declare const POINT_LOT_SOURCES: readonly ["REVIEW", "PURCHASE", "ADJUST", "REFUND_RESTORE", "OPENING", "COUPON"];
 export type PointLotSource = (typeof POINT_LOT_SOURCES)[number];
 /** 원장 항목 유형 */
-export declare const POINT_ENTRY_TYPES: readonly ["EARN_REVIEW", "REVOKE_REVIEW", "EARN_PURCHASE", "USE_RESERVE", "USE_RELEASE", "REFUND_RESTORE", "EXPIRE", "ADJUST", "OPENING", "EARN_COUPON"];
+export declare const POINT_ENTRY_TYPES: readonly ["EARN_REVIEW", "REVOKE_REVIEW", "EARN_PURCHASE", "REVOKE_PURCHASE", "USE_RESERVE", "USE_RELEASE", "REFUND_RESTORE", "EXPIRE", "ADJUST", "OPENING", "EARN_COUPON"];
 export type PointEntryType = (typeof POINT_ENTRY_TYPES)[number];
 /** 상점 플랫폼 알림 — `REVIEW_REWARD_PAUSED` 리뷰 자동 적립이 멈춤 · `POINTS_AVAILABLE` 적립금 설정을 쓸 수 있음 */
 export declare const pointPolicyNoticeSchema: z$1.ZodNullable<z$1.ZodEnum<{
@@ -13094,6 +13128,7 @@ export declare const responsePointEntryTypeSchema: z$1.ZodUnion<readonly [z$1.Zo
   EARN_REVIEW: "EARN_REVIEW";
   REVOKE_REVIEW: "REVOKE_REVIEW";
   EARN_PURCHASE: "EARN_PURCHASE";
+  REVOKE_PURCHASE: "REVOKE_PURCHASE";
   USE_RESERVE: "USE_RESERVE";
   USE_RELEASE: "USE_RELEASE";
   REFUND_RESTORE: "REFUND_RESTORE";
@@ -13110,6 +13145,7 @@ export declare const pointEntrySchema: z$1.ZodObject<{
     EARN_REVIEW: "EARN_REVIEW";
     REVOKE_REVIEW: "REVOKE_REVIEW";
     EARN_PURCHASE: "EARN_PURCHASE";
+    REVOKE_PURCHASE: "REVOKE_PURCHASE";
     USE_RESERVE: "USE_RESERVE";
     USE_RELEASE: "USE_RELEASE";
     REFUND_RESTORE: "REFUND_RESTORE";
@@ -13196,6 +13232,7 @@ export declare const pointAdjustmentResultSchema: z$1.ZodObject<{
       EARN_REVIEW: "EARN_REVIEW";
       REVOKE_REVIEW: "REVOKE_REVIEW";
       EARN_PURCHASE: "EARN_PURCHASE";
+      REVOKE_PURCHASE: "REVOKE_PURCHASE";
       USE_RESERVE: "USE_RESERVE";
       USE_RELEASE: "USE_RELEASE";
       REFUND_RESTORE: "REFUND_RESTORE";
@@ -20796,6 +20833,12 @@ export declare function createStoreClient(options: StoreClientOptions): {
           dispatchedAt: string;
           deliveredAt: string | null;
         } | null;
+        flowStep: {
+          key: string;
+          label: string;
+          acceptsConfirm: boolean;
+          acceptsDispatch: boolean;
+        } | null;
         stay?: {
           checkIn: string;
           checkOut: string;
@@ -20820,13 +20863,16 @@ export declare function createStoreClient(options: StoreClientOptions): {
     hold: (orderItemId: string, body: HoldOrderItemRequest) => Promise<void>;
     releaseHold: (orderItemId: string) => Promise<void>;
     /** 판매자 취소 미리보기(#115) — 취소하면 돌려줄 현금·적립금. 생략한 수량은 남은 수량 전체다 */
-    cancelPreview: (orderItemId: string, quantity?: number) => Promise<{
+    cancelPreview: (orderItemId: string, query?: number | SellerCancelPreviewQuery) => Promise<{
       orderItemId: string;
       quantity: number;
       refundAmount: number;
       pointRefundAmount: number;
       deliveryFeeRefundAmount: number;
       deliveryFeeChargeAmount: number;
+      deductAmount: number;
+      restockRequired: boolean;
+      purchasePointAmount: number;
     }>;
     cancelBySeller: (orderItemId: string, body: CancelBySellerRequest, idempotencyKey?: string) => Promise<{
       orderItemId: string;
@@ -20840,6 +20886,8 @@ export declare function createStoreClient(options: StoreClientOptions): {
       pointRefundAmount: number;
       refundedAt: string;
       refundHeld: boolean;
+      deductAmount: number;
+      purchasePointReclaimedAmount: number;
     }>;
     updateMemo: (orderItemId: string, memo: string) => Promise<void>;
     requestPurchaseDecision: (orderItemId: string) => Promise<void>;
@@ -21961,7 +22009,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
         quantity: number;
         reason: "CHANGE_OF_MIND" | "WRONG_ORDER" | "DEFECTIVE" | "WRONG_DELIVERY" | "DIFFERENT_FROM_PAGE" | "DELAY";
         reasonDetail: string | null;
-        responsibility: "BUYER" | "SELLER";
+        responsibility: "SELLER" | "BUYER";
         claimDeliveryFee: number;
         expectedRefundAmount: number | null;
         expectedDeliveryFeeRefundAmount: number | null;
@@ -22001,7 +22049,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
       quantity: number;
       reason: "CHANGE_OF_MIND" | "WRONG_ORDER" | "DEFECTIVE" | "WRONG_DELIVERY" | "DIFFERENT_FROM_PAGE" | "DELAY";
       reasonDetail: string | null;
-      responsibility: "BUYER" | "SELLER";
+      responsibility: "SELLER" | "BUYER";
       claimDeliveryFee: number;
       expectedRefundAmount: number | null;
       expectedDeliveryFeeRefundAmount: number | null;
@@ -22030,7 +22078,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
       } | null;
       histories?: {
         status: "REJECTED" | "COMPLETED" | "REQUESTED" | "HELD" | "COLLECTING" | "COLLECTED" | "REDELIVERING" | "APPROVED" | "WITHDRAWN";
-        actor: "SYSTEM" | "BUYER" | "SELLER";
+        actor: "SELLER" | "BUYER" | "SYSTEM";
         occurredAt: string;
       }[] | undefined;
     }>;
@@ -22078,7 +22126,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
       quantity: number;
       reason: "CHANGE_OF_MIND" | "WRONG_ORDER" | "DEFECTIVE" | "WRONG_DELIVERY" | "DIFFERENT_FROM_PAGE" | "DELAY";
       reasonDetail: string | null;
-      responsibility: "BUYER" | "SELLER";
+      responsibility: "SELLER" | "BUYER";
       claimDeliveryFee: number;
       expectedRefundAmount: number | null;
       expectedDeliveryFeeRefundAmount: number | null;
@@ -22566,7 +22614,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
         version: string | null;
         documentUrl: string | null;
         action: "WITHDRAWN" | "AGREED";
-        source: "SIGNUP" | "SELLER" | "SOCIAL_SIGNUP" | "DELEGATED" | "RECONSENT" | "MEMBER_UPDATE";
+        source: "SELLER" | "SIGNUP" | "SOCIAL_SIGNUP" | "DELEGATED" | "RECONSENT" | "MEMBER_UPDATE";
         occurredAt: string;
       }[];
     }>;
@@ -23912,7 +23960,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
         updatedAt: string;
       } | null;
     }>;
-    /** `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) => Promise<{
       refundId: string;
       amount: number;

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(),
@@ -11178,7 +11181,13 @@ const shippingOrderItemSchema = orderItemSchema.extend({
 	ordererName: z$1.string(),
 	ordererPhone: z$1.string(),
 	shippingAddress: shippingAddressSchema,
-	delivery: deliveryInfoSchema.nullable().describe("발송 정보. 발송 전이면 null")
+	delivery: deliveryInfoSchema.nullable().describe("발송 정보. 발송 전이면 null"),
+	flowStep: z$1.object({
+		key: z$1.string().describe("주문 흐름 안 단계 키(상점이 정한다). 화면 분기에 쓰지 않는다"),
+		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);
 /**
@@ -11245,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`)을
@@ -11260,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) — 판매자 취소를 하면 돌려줄 금액. 실제 취소와 같은 계산을
@@ -11281,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({
@@ -12190,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)
@@ -12510,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.0",
+  "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

@@ -489,6 +489,31 @@ export const shippingOrderItemSchema = orderItemSchema.extend({
   ordererPhone: z.string(),
   shippingAddress: shippingAddressSchema,
   delivery: deliveryInfoSchema.nullable().describe("발송 정보. 발송 전이면 null"),
+  flowStep: z
+    .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`다(`acceptsConfirm`·`acceptsDispatch`). 흐름이 없으면 null. 서버는 항상 싣는다",
+    ),
 });
 
 export type ShippingOrderItem = z.infer<typeof shippingOrderItemSchema>;
@@ -650,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). 지급된 구매 적립금이 없으면 무시한다. 생략하면 회수하지 않는다. " +
+          "회원 잔액이 모자라면 있는 만큼만 회수한다(리뷰 적립 회수와 같은 규칙)",
+      ),
   }),
 );
 
@@ -690,7 +744,7 @@ export const cancelBySellerResultSchema = z.object({
     .int()
     .describe(
       "실제 환불한 금액 — 수량 비율 상품 실결제 금액(쿠폰 배분을 뺀 금액) + 배송비 환불 − 조건부 무료배송 미달 차감 " +
-        "+ 되돌린 쿠폰 차감(`couponChargeRefundAmount`)",
+        "− 쿠폰 조건 미달 차감 + 되돌린 쿠폰 차감(`couponChargeRefundAmount`) − 추가 차감(`deductAmount`)",
     ),
   quantity: z.number().int().describe("취소한 수량"),
   canceledQuantity: z.number().int().describe("취소 후 누적 취소 수량"),
@@ -709,7 +763,9 @@ export const cancelBySellerResultSchema = z.object({
     .int()
     .optional()
     .default(0)
-    .describe("쿠폰 조건 미달 차감. 판매자 취소는 차감하지 않으므로 늘 0이다. 서버는 항상 싣는다"),
+    .describe(
+      "쿠폰 조건 미달 차감. 판매자 귀책 취소는 차감하지 않으므로 0이고, 구매자 귀책(`responsibility: BUYER`)이면 생길 수 있다. 서버는 항상 싣는다",
+    ),
   couponChargeRefundAmount: z
     .number()
     .int()
@@ -733,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다
@@ -748,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()