@sayren/store-sdk 0.9.0 → 0.11.0

package/dist/index.d.mts

@@ -1082,6 +1082,22 @@ export declare const claimReasonSchema: z.ZodEnum<{
   DELAY: "DELAY";
 }>;
 export type ClaimReason = z.infer<typeof claimReasonSchema>;
+/**
+ * 반품지 (이슈 #30) — 반품·교환 수거가 안내하는 주소다. 스토어 주소록의 기본 반품지이거나,
+ * 상품이 반품지를 따로 지정했으면 그 주소다.
+ *
+ * 취소 클레임은 보낼 물건이 없어 null이고, 반품지를 등록하지 않은 스토어도 null이다.
+ * 구매자가 직접 보내는 수거(`BUYER_SEND`)에 이 주소가 필요하다.
+ */
+export declare const claimReturnAddressSchema: z.ZodObject<{
+  name: z.ZodString;
+  contactName: z.ZodString;
+  phone: z.ZodString;
+  zipCode: z.ZodString;
+  address1: z.ZodString;
+  address2: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type ClaimReturnAddress = z.infer<typeof claimReturnAddressSchema>;
 export declare const claimSchema: z.ZodObject<{
   claimId: z.ZodString;
   type: z.ZodEnum<{
@@ -1119,6 +1135,7 @@ export declare const claimSchema: z.ZodObject<{
   }>;
   claimDeliveryFee: z.ZodNumber;
   expectedRefundAmount: z.ZodNullable<z.ZodNumber>;
+  expectedDeliveryFeeRefundAmount: z.ZodNullable<z.ZodNumber>;
   exchangeOption: z.ZodNullable<z.ZodObject<{
     optionId: z.ZodString;
     optionName: z.ZodString;
@@ -1135,6 +1152,14 @@ export declare const claimSchema: z.ZodObject<{
   completedAt: z.ZodNullable<z.ZodString>;
   holdExpiresAt: z.ZodNullable<z.ZodString>;
   holdUsed: z.ZodBoolean;
+  returnAddress: z.ZodNullable<z.ZodObject<{
+    name: z.ZodString;
+    contactName: z.ZodString;
+    phone: z.ZodString;
+    zipCode: z.ZodString;
+    address1: z.ZodString;
+    address2: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>>;
 }, z.core.$strip>;
 export type Claim = z.infer<typeof claimSchema>;
 export interface ClaimListParams extends PageParams {
@@ -1197,6 +1222,7 @@ export declare const claimDetailSchema: z.ZodObject<{
   }>;
   claimDeliveryFee: z.ZodNumber;
   expectedRefundAmount: z.ZodNullable<z.ZodNumber>;
+  expectedDeliveryFeeRefundAmount: z.ZodNullable<z.ZodNumber>;
   exchangeOption: z.ZodNullable<z.ZodObject<{
     optionId: z.ZodString;
     optionName: z.ZodString;
@@ -1213,6 +1239,14 @@ export declare const claimDetailSchema: z.ZodObject<{
   completedAt: z.ZodNullable<z.ZodString>;
   holdExpiresAt: z.ZodNullable<z.ZodString>;
   holdUsed: z.ZodBoolean;
+  returnAddress: z.ZodNullable<z.ZodObject<{
+    name: z.ZodString;
+    contactName: z.ZodString;
+    phone: z.ZodString;
+    zipCode: z.ZodString;
+    address1: z.ZodString;
+    address2: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>>;
   histories: z.ZodOptional<z.ZodArray<z.ZodObject<{
     status: z.ZodEnum<{
       REQUESTED: "REQUESTED";
@@ -1256,6 +1290,9 @@ export declare const approveClaimResultSchema: z.ZodObject<{
   claimId: z.ZodString;
   refundAmount: z.ZodNumber;
   deductAmount: z.ZodNumber;
+  quantity: z.ZodNumber;
+  deliveryFeeRefundAmount: z.ZodNumber;
+  deliveryFeeChargeAmount: z.ZodNumber;
   refundedAt: z.ZodString;
 }, z.core.$strip>;
 export type ApproveClaimResult = z.infer<typeof approveClaimResultSchema>;
@@ -1319,6 +1356,125 @@ export declare const customerAddressSchema: z.ZodObject<{
   address1: z.ZodString;
   address2: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
+/** 동의 종류 — 이용약관·개인정보 수집이용은 가입 필수, 마케팅 수신은 선택 */
+export declare const consentKindSchema: z.ZodEnum<{
+  TERMS: "TERMS";
+  PRIVACY: "PRIVACY";
+  MARKETING: "MARKETING";
+}>;
+export type ConsentKind = z.infer<typeof consentKindSchema>;
+export declare const consentActionSchema: z.ZodEnum<{
+  WITHDRAWN: "WITHDRAWN";
+  AGREED: "AGREED";
+}>;
+export type ConsentAction = z.infer<typeof consentActionSchema>;
+/**
+ * 동의가 일어난 경로. 값이 추가될 수 있어 모르는 값은 그대로 보여 준다.
+ * `SIGNUP` 비밀번호 가입 · `SOCIAL_SIGNUP` 소셜 가입 · `DELEGATED` 셀러 자체 회원 연동 ·
+ * `RECONSENT` 약관 개정 재동의 · `MEMBER_UPDATE` 구매자가 직접 변경 · `SELLER` 셀러가 처리
+ */
+export declare const consentSourceSchema: z.ZodEnum<{
+  SELLER: "SELLER";
+  SIGNUP: "SIGNUP";
+  SOCIAL_SIGNUP: "SOCIAL_SIGNUP";
+  DELEGATED: "DELEGATED";
+  RECONSENT: "RECONSENT";
+  MEMBER_UPDATE: "MEMBER_UPDATE";
+}>;
+export type ConsentSource = z.infer<typeof consentSourceSchema>;
+/** 동의 이력 한 줄 — 추가만 되고 지워지지 않는다(구매자 탈퇴 시에만 함께 지워진다) */
+export declare const customerConsentSchema: z.ZodObject<{
+  consentId: z.ZodString;
+  kind: z.ZodEnum<{
+    TERMS: "TERMS";
+    PRIVACY: "PRIVACY";
+    MARKETING: "MARKETING";
+  }>;
+  version: z.ZodNullable<z.ZodString>;
+  documentUrl: z.ZodNullable<z.ZodString>;
+  action: z.ZodEnum<{
+    WITHDRAWN: "WITHDRAWN";
+    AGREED: "AGREED";
+  }>;
+  source: z.ZodEnum<{
+    SELLER: "SELLER";
+    SIGNUP: "SIGNUP";
+    SOCIAL_SIGNUP: "SOCIAL_SIGNUP";
+    DELEGATED: "DELEGATED";
+    RECONSENT: "RECONSENT";
+    MEMBER_UPDATE: "MEMBER_UPDATE";
+  }>;
+  occurredAt: z.ZodString;
+}, z.core.$strip>;
+export type CustomerConsent = z.infer<typeof customerConsentSchema>;
+/** 종류별 현재 동의 상태 */
+export declare const customerConsentStateSchema: z.ZodObject<{
+  kind: z.ZodEnum<{
+    TERMS: "TERMS";
+    PRIVACY: "PRIVACY";
+    MARKETING: "MARKETING";
+  }>;
+  agreed: z.ZodBoolean;
+  agreedVersion: z.ZodNullable<z.ZodString>;
+  currentVersion: z.ZodNullable<z.ZodString>;
+  currentDocumentUrl: z.ZodNullable<z.ZodString>;
+  updatedAt: z.ZodNullable<z.ZodString>;
+  reconsentRequired: z.ZodBoolean;
+}, z.core.$strip>;
+export type CustomerConsentState = z.infer<typeof customerConsentStateSchema>;
+export declare const customerConsentsSchema: z.ZodObject<{
+  terms: z.ZodObject<{
+    kind: z.ZodEnum<{
+      TERMS: "TERMS";
+      PRIVACY: "PRIVACY";
+      MARKETING: "MARKETING";
+    }>;
+    agreed: z.ZodBoolean;
+    agreedVersion: z.ZodNullable<z.ZodString>;
+    currentVersion: z.ZodNullable<z.ZodString>;
+    currentDocumentUrl: z.ZodNullable<z.ZodString>;
+    updatedAt: z.ZodNullable<z.ZodString>;
+    reconsentRequired: z.ZodBoolean;
+  }, z.core.$strip>;
+  privacy: z.ZodObject<{
+    kind: z.ZodEnum<{
+      TERMS: "TERMS";
+      PRIVACY: "PRIVACY";
+      MARKETING: "MARKETING";
+    }>;
+    agreed: z.ZodBoolean;
+    agreedVersion: z.ZodNullable<z.ZodString>;
+    currentVersion: z.ZodNullable<z.ZodString>;
+    currentDocumentUrl: z.ZodNullable<z.ZodString>;
+    updatedAt: z.ZodNullable<z.ZodString>;
+    reconsentRequired: z.ZodBoolean;
+  }, z.core.$strip>;
+  marketing: z.ZodObject<{
+    kind: z.ZodEnum<{
+      TERMS: "TERMS";
+      PRIVACY: "PRIVACY";
+      MARKETING: "MARKETING";
+    }>;
+    agreed: z.ZodBoolean;
+    agreedVersion: z.ZodNullable<z.ZodString>;
+    currentVersion: z.ZodNullable<z.ZodString>;
+    currentDocumentUrl: z.ZodNullable<z.ZodString>;
+    updatedAt: z.ZodNullable<z.ZodString>;
+    reconsentRequired: z.ZodBoolean;
+  }, z.core.$strip>;
+  reconsentRequired: z.ZodBoolean;
+}, z.core.$strip>;
+export type CustomerConsents = z.infer<typeof customerConsentsSchema>;
+/** `GET /v1/customers/{id}/consents` 쿼리 — 최근 순이다 */
+export declare const customerConsentListQuerySchema: z.ZodObject<{
+  page: z.ZodOptional<z.ZodString>;
+  size: z.ZodOptional<z.ZodString>;
+  kind: z.ZodOptional<z.ZodEnum<{
+    TERMS: "TERMS";
+    PRIVACY: "PRIVACY";
+    MARKETING: "MARKETING";
+  }>>;
+}, z.core.$strip>;
 /** 구매자 상세 — 휴대폰 전체를 보여 준다 */
 export declare const customerDetailSchema: z.ZodObject<{
   customerId: z.ZodString;
@@ -1337,6 +1493,48 @@ export declare const customerDetailSchema: z.ZodObject<{
     }>;
     linkedAt: z.ZodString;
   }, z.core.$strip>>;
+  consents: z.ZodObject<{
+    terms: z.ZodObject<{
+      kind: z.ZodEnum<{
+        TERMS: "TERMS";
+        PRIVACY: "PRIVACY";
+        MARKETING: "MARKETING";
+      }>;
+      agreed: z.ZodBoolean;
+      agreedVersion: z.ZodNullable<z.ZodString>;
+      currentVersion: z.ZodNullable<z.ZodString>;
+      currentDocumentUrl: z.ZodNullable<z.ZodString>;
+      updatedAt: z.ZodNullable<z.ZodString>;
+      reconsentRequired: z.ZodBoolean;
+    }, z.core.$strip>;
+    privacy: z.ZodObject<{
+      kind: z.ZodEnum<{
+        TERMS: "TERMS";
+        PRIVACY: "PRIVACY";
+        MARKETING: "MARKETING";
+      }>;
+      agreed: z.ZodBoolean;
+      agreedVersion: z.ZodNullable<z.ZodString>;
+      currentVersion: z.ZodNullable<z.ZodString>;
+      currentDocumentUrl: z.ZodNullable<z.ZodString>;
+      updatedAt: z.ZodNullable<z.ZodString>;
+      reconsentRequired: z.ZodBoolean;
+    }, z.core.$strip>;
+    marketing: z.ZodObject<{
+      kind: z.ZodEnum<{
+        TERMS: "TERMS";
+        PRIVACY: "PRIVACY";
+        MARKETING: "MARKETING";
+      }>;
+      agreed: z.ZodBoolean;
+      agreedVersion: z.ZodNullable<z.ZodString>;
+      currentVersion: z.ZodNullable<z.ZodString>;
+      currentDocumentUrl: z.ZodNullable<z.ZodString>;
+      updatedAt: z.ZodNullable<z.ZodString>;
+      reconsentRequired: z.ZodBoolean;
+    }, z.core.$strip>;
+    reconsentRequired: z.ZodBoolean;
+  }, z.core.$strip>;
   addresses: z.ZodArray<z.ZodObject<{
     addressId: z.ZodString;
     alias: z.ZodString;
@@ -1991,6 +2189,8 @@ export declare const orderItemSchema: z.ZodObject<{
   optionName: z.ZodNullable<z.ZodString>;
   sellerCode: z.ZodNullable<z.ZodString>;
   quantity: z.ZodNumber;
+  canceledQuantity: z.ZodNumber;
+  activeQuantity: z.ZodNumber;
   unitPrice: z.ZodNumber;
   discountAmount: z.ZodNumber;
   totalPrice: z.ZodNumber;
@@ -2050,6 +2250,28 @@ export declare const orderSchema: z.ZodObject<{
     discountAmount: z.ZodNumber;
     totalAmount: z.ZodNumber;
     paidAt: z.ZodNullable<z.ZodString>;
+    cashReceipt: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+      cashReceiptId: z.ZodString;
+      status: z.ZodString;
+      type: z.ZodString;
+      identityType: z.ZodString;
+      identityNumberMasked: z.ZodString;
+      amount: z.ZodNumber;
+      issuedAmount: z.ZodNumber;
+      provider: z.ZodNullable<z.ZodEnum<{
+        tosspayments: "tosspayments";
+        portone: "portone";
+      }>>;
+      issueNumber: z.ZodNullable<z.ZodString>;
+      receiptUrl: z.ZodNullable<z.ZodString>;
+      issuedAt: z.ZodNullable<z.ZodString>;
+      canceledAt: z.ZodNullable<z.ZodString>;
+      failCode: z.ZodNullable<z.ZodString>;
+      failMessage: z.ZodNullable<z.ZodString>;
+      reissuable: z.ZodBoolean;
+      requestedAt: z.ZodString;
+      updatedAt: z.ZodString;
+    }, z.core.$strip>>>>;
   }, z.core.$strip>;
   testPayment: z.ZodBoolean;
   items: z.ZodArray<z.ZodObject<{
@@ -2076,6 +2298,8 @@ export declare const orderSchema: z.ZodObject<{
     optionName: z.ZodNullable<z.ZodString>;
     sellerCode: z.ZodNullable<z.ZodString>;
     quantity: z.ZodNumber;
+    canceledQuantity: z.ZodNumber;
+    activeQuantity: z.ZodNumber;
     unitPrice: z.ZodNumber;
     discountAmount: z.ZodNumber;
     totalPrice: z.ZodNumber;
@@ -2159,6 +2383,8 @@ export declare const orderItemPageSchema: z.ZodObject<{
     optionName: z.ZodNullable<z.ZodString>;
     sellerCode: z.ZodNullable<z.ZodString>;
     quantity: z.ZodNumber;
+    canceledQuantity: z.ZodNumber;
+    activeQuantity: z.ZodNumber;
     unitPrice: z.ZodNumber;
     discountAmount: z.ZodNumber;
     totalPrice: z.ZodNumber;
@@ -2269,7 +2495,7 @@ export declare const dispatchRequestSchema: z.ZodObject<{
   }>;
   carrierCode: z.ZodOptional<z.ZodString>;
   trackingNumber: z.ZodOptional<z.ZodString>;
-  dispatchedAt: z.ZodOptional<z.ZodString>;
+  dispatchedAt: z.ZodOptional<z.ZodISODateTime>;
 }, z.core.$strip>;
 export type DispatchRequest = z.infer<typeof dispatchRequestSchema>;
 export declare const deliveryInfoSchema: z.ZodObject<{
@@ -2293,6 +2519,11 @@ export declare const deliveryInfoSchema: z.ZodObject<{
   deliveredAt: z.ZodNullable<z.ZodString>;
 }, z.core.$strip>;
 export type DeliveryInfo = z.infer<typeof deliveryInfoSchema>;
+/**
+ * 택배 추적 단계. 응답에서는 문자열로 받는다(값이 추가될 수 있다) — 현재 값은 `ACCEPTED`(접수)·`IN_TRANSIT`(이동 중)·
+ * `OUT_FOR_DELIVERY`(배송 출발)·`DELIVERED`(배송완료)다.
+ */
+export declare const trackingStageResponseSchema: z.ZodString;
 /** `GET /v1/order-items/{orderItemId}/delivery` 응답 — 배송 정보 + 배송 추적 이벤트 */
 export declare const deliveryStatusSchema: z.ZodObject<{
   orderItemId: z.ZodString;
@@ -2317,7 +2548,14 @@ export declare const deliveryStatusSchema: z.ZodObject<{
     status: z.ZodString;
     location: z.ZodString;
     occurredAt: z.ZodString;
+    stage: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
   }, z.core.$strip>>>;
+  tracking: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+    result: z.ZodNullable<z.ZodString>;
+    stage: z.ZodNullable<z.ZodString>;
+    checkedAt: z.ZodNullable<z.ZodString>;
+    carrierDeliveredAt: z.ZodNullable<z.ZodString>;
+  }, z.core.$strip>>>>;
 }, z.core.$strip>;
 export type DeliveryStatus = z.infer<typeof deliveryStatusSchema>;
 /** `PUT /v1/order-items/{orderItemId}/dispatch/tracking` 응답 — 바뀐 송장 */
@@ -2352,12 +2590,17 @@ export declare const cancelBySellerRequestSchema: z.ZodObject<{
     DELIVERY_IMPOSSIBLE: "DELIVERY_IMPOSSIBLE";
   }>;
   detail: z.ZodOptional<z.ZodString>;
+  quantity: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type CancelBySellerRequest = z.infer<typeof cancelBySellerRequestSchema>;
 /** `POST /v1/order-items/{orderItemId}/cancel` 응답 — 셀러 직권취소 환불 결과 */
 export declare const cancelBySellerResultSchema: z.ZodObject<{
   orderItemId: z.ZodString;
   refundAmount: z.ZodNumber;
+  quantity: z.ZodNumber;
+  canceledQuantity: z.ZodNumber;
+  deliveryFeeRefundAmount: z.ZodNumber;
+  deliveryFeeChargeAmount: z.ZodNumber;
   refundedAt: z.ZodString;
 }, z.core.$strip>;
 export type CancelBySellerResult = z.infer<typeof cancelBySellerResultSchema>;
@@ -3091,6 +3334,40 @@ export declare const paymentRecordStatusSchema: z.ZodEnum<{
 }>;
 export type PaymentRecordStatus = z.infer<typeof paymentRecordStatusSchema>;
 export declare const paymentAttemptStatusSchema: z.ZodString;
+/**
+ * 현금영수증 상태 — 값이 추가될 수 있어 응답은 문자열로 받는다. 화면 분기는 이 목록으로 하고 모르는 값은 처리 중으로 다룬다.
+ * - `REQUESTED`: 구매자가 신청했고 결제 승인 전이다
+ * - `PENDING`: 발급·취소를 기다린다(승인 직후, 또는 일시 오류로 자동 재시도 대기)
+ * - `ISSUED`: 발급됐다. 부분 환불이 있었으면 그만큼 취소(또는 재발급)된 금액이다
+ * - `CANCELED`: 전액 환불로 취소됐다
+ * - `FAILED`: 발급·취소가 실패했고 자동 재시도가 끝났다. `failCode`·`failMessage`를 보고 재발급한다
+ * - `SKIPPED`: 발급 대상이 아니다(승인된 결제수단이 계좌이체·가상계좌가 아님)
+ */
+export declare const CASH_RECEIPT_STATUS_VALUES: readonly ["REQUESTED", "PENDING", "ISSUED", "CANCELED", "FAILED", "SKIPPED"];
+export type KnownCashReceiptStatus = (typeof CASH_RECEIPT_STATUS_VALUES)[number];
+export declare const cashReceiptSchema: z.ZodObject<{
+  cashReceiptId: z.ZodString;
+  status: z.ZodString;
+  type: z.ZodString;
+  identityType: z.ZodString;
+  identityNumberMasked: z.ZodString;
+  amount: z.ZodNumber;
+  issuedAmount: z.ZodNumber;
+  provider: z.ZodNullable<z.ZodEnum<{
+    tosspayments: "tosspayments";
+    portone: "portone";
+  }>>;
+  issueNumber: z.ZodNullable<z.ZodString>;
+  receiptUrl: z.ZodNullable<z.ZodString>;
+  issuedAt: z.ZodNullable<z.ZodString>;
+  canceledAt: z.ZodNullable<z.ZodString>;
+  failCode: z.ZodNullable<z.ZodString>;
+  failMessage: z.ZodNullable<z.ZodString>;
+  reissuable: z.ZodBoolean;
+  requestedAt: z.ZodString;
+  updatedAt: z.ZodString;
+}, z.core.$strip>;
+export type CashReceipt = z.infer<typeof cashReceiptSchema>;
 export declare const paymentRecordSchema: z.ZodObject<{
   paymentId: z.ZodString;
   orderId: z.ZodNullable<z.ZodString>;
@@ -3129,6 +3406,7 @@ export declare const paymentRecordSchema: z.ZodObject<{
   failMessage: z.ZodNullable<z.ZodString>;
   paidAt: z.ZodNullable<z.ZodString>;
   createdAt: z.ZodString;
+  cashReceiptStatus: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
 }, z.core.$strip>;
 export type PaymentRecord = z.infer<typeof paymentRecordSchema>;
 export declare const paymentRecordPageSchema: z.ZodObject<{
@@ -3174,6 +3452,7 @@ export declare const paymentRecordPageSchema: z.ZodObject<{
     failMessage: z.ZodNullable<z.ZodString>;
     paidAt: z.ZodNullable<z.ZodString>;
     createdAt: z.ZodString;
+    cashReceiptStatus: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
   }, z.core.$strip>>;
 }, z.core.$strip>;
 export type PaymentRecordPage = z.infer<typeof paymentRecordPageSchema>;
@@ -3262,6 +3541,7 @@ export declare const paymentRecordDetailSchema: z.ZodObject<{
   failMessage: z.ZodNullable<z.ZodString>;
   paidAt: z.ZodNullable<z.ZodString>;
   createdAt: z.ZodString;
+  cashReceiptStatus: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodString>>>;
   refundableAmount: z.ZodNumber;
   merchantId: z.ZodNullable<z.ZodString>;
   attempts: z.ZodArray<z.ZodObject<{
@@ -3309,6 +3589,28 @@ export declare const paymentRecordDetailSchema: z.ZodObject<{
     requestedAt: z.ZodString;
     completedAt: z.ZodNullable<z.ZodString>;
   }, z.core.$strip>>;
+  cashReceipt: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodObject<{
+    cashReceiptId: z.ZodString;
+    status: z.ZodString;
+    type: z.ZodString;
+    identityType: z.ZodString;
+    identityNumberMasked: z.ZodString;
+    amount: z.ZodNumber;
+    issuedAmount: z.ZodNumber;
+    provider: z.ZodNullable<z.ZodEnum<{
+      tosspayments: "tosspayments";
+      portone: "portone";
+    }>>;
+    issueNumber: z.ZodNullable<z.ZodString>;
+    receiptUrl: z.ZodNullable<z.ZodString>;
+    issuedAt: z.ZodNullable<z.ZodString>;
+    canceledAt: z.ZodNullable<z.ZodString>;
+    failCode: z.ZodNullable<z.ZodString>;
+    failMessage: z.ZodNullable<z.ZodString>;
+    reissuable: z.ZodBoolean;
+    requestedAt: z.ZodString;
+    updatedAt: z.ZodString;
+  }, z.core.$strip>>>>;
 }, z.core.$strip>;
 export type PaymentRecordDetail = z.infer<typeof paymentRecordDetailSchema>;
 /** `GET /v1/payments` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열) */
@@ -3458,6 +3760,13 @@ export declare const productSchema: z.ZodObject<{
   conditionalFreeAmount: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
   returnFee: z.ZodOptional<z.ZodNumber>;
   exchangeFee: z.ZodOptional<z.ZodNumber>;
+  refundPolicy: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+    preShipmentDeliveryFeeRefund: z.ZodOptional<z.ZodBoolean>;
+    returnDeliveryFee: z.ZodOptional<z.ZodNumber>;
+    exchangeDeliveryFee: z.ZodOptional<z.ZodNumber>;
+    sellerFaultFreeShipping: z.ZodOptional<z.ZodBoolean>;
+    conditionalFreeShortfallCharge: z.ZodOptional<z.ZodBoolean>;
+  }, z.core.$strict>>>;
   shippingAddressId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
   returnAddressId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
   createdAt: z.ZodOptional<z.ZodString>;
@@ -3611,12 +3920,19 @@ export declare const productCreateRequestSchema: z.ZodObject<{
     PAID: "PAID";
     CONDITIONAL_FREE: "CONDITIONAL_FREE";
   }>>;
-  deliveryFee: z.ZodDefault<z.ZodNumber>;
+  deliveryFee: z.ZodOptional<z.ZodNumber>;
   conditionalFreeAmount: z.ZodOptional<z.ZodNumber>;
   returnFee: z.ZodDefault<z.ZodNumber>;
   exchangeFee: z.ZodDefault<z.ZodNumber>;
-  shippingAddressId: z.ZodOptional<z.ZodString>;
-  returnAddressId: z.ZodOptional<z.ZodString>;
+  refundPolicy: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+    preShipmentDeliveryFeeRefund: z.ZodOptional<z.ZodBoolean>;
+    returnDeliveryFee: z.ZodOptional<z.ZodNumber>;
+    exchangeDeliveryFee: z.ZodOptional<z.ZodNumber>;
+    sellerFaultFreeShipping: z.ZodOptional<z.ZodBoolean>;
+    conditionalFreeShortfallCharge: z.ZodOptional<z.ZodBoolean>;
+  }, z.core.$strict>>>;
+  shippingAddressId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  returnAddressId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
   optionGroups: z.ZodDefault<z.ZodArray<z.ZodObject<{
     groupId: z.ZodOptional<z.ZodString>;
     name: z.ZodString;
@@ -3649,6 +3965,8 @@ export declare const productPatchRequestSchema: z.ZodObject<{
     CLOSED: "CLOSED";
   }>>;
   deliveryFee: z.ZodOptional<z.ZodNumber>;
+  shippingAddressId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  returnAddressId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 export type ProductPatchRequest = z.infer<typeof productPatchRequestSchema>;
 export declare const productSortSchema: z.ZodEnum<{
@@ -3731,6 +4049,16 @@ export declare const analyticsOriginSchema: z.ZodString;
 export declare const MAX_ANALYTICS_ALLOWED_ORIGINS = 20;
 /** 자동 배송완료·자동 구매확정 대기일 상한 */
 export declare const MAX_AUTO_TRANSITION_DAYS = 30;
+/**
+ * 약관 버전 — 스토어가 정하는 문자열이다(`1`·`2`·`2026-09-26`·`v1.2` 등). 형식은 강제하지 않고 값이 다르면 다른 버전이다.
+ * 올리면 그 약관에 동의한 구매자의 `reconsentRequired`가 켜지고, 재동의가 이력에 남는다. 되돌리면 재동의 요구도 풀린다.
+ */
+export declare const policyVersionSchema: z.ZodString;
+/**
+ * 약관 문서 주소 — 구매자에게 보여 주는 약관 본문의 주소다. 동의 시점 값이 이력 행에 복사되므로
+ * 나중에 주소를 바꿔도 "무엇에 동의했는지"가 남는다. `null`로 지울 수 있다.
+ */
+export declare const policyDocumentUrlSchema: z.ZodNullable<z.ZodURL>;
 /** `PATCH /v1/store` 본문 — 바꿀 필드만 보낸다 */
 export declare const updateStoreRequestSchema: z.ZodObject<{
   name: z.ZodOptional<z.ZodString>;
@@ -3742,6 +4070,23 @@ export declare const updateStoreRequestSchema: z.ZodObject<{
   guestCheckoutEnabled: z.ZodOptional<z.ZodBoolean>;
   autoDeliverDays: z.ZodOptional<z.ZodNumber>;
   autoConfirmDays: z.ZodOptional<z.ZodNumber>;
+  refundPolicy: z.ZodOptional<z.ZodObject<{
+    preShipmentDeliveryFeeRefund: z.ZodOptional<z.ZodBoolean>;
+    returnDeliveryFee: z.ZodOptional<z.ZodNumber>;
+    exchangeDeliveryFee: z.ZodOptional<z.ZodNumber>;
+    sellerFaultFreeShipping: z.ZodOptional<z.ZodBoolean>;
+    conditionalFreeShortfallCharge: z.ZodOptional<z.ZodBoolean>;
+  }, z.core.$strict>>;
+  shippingPolicy: z.ZodOptional<z.ZodObject<{
+    baseDeliveryFee: z.ZodOptional<z.ZodNumber>;
+    freeThreshold: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    jejuSurcharge: z.ZodOptional<z.ZodNumber>;
+    isolatedSurcharge: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$strict>>;
+  termsVersion: z.ZodOptional<z.ZodString>;
+  privacyVersion: z.ZodOptional<z.ZodString>;
+  termsUrl: z.ZodOptional<z.ZodNullable<z.ZodURL>>;
+  privacyUrl: z.ZodOptional<z.ZodNullable<z.ZodURL>>;
 }, z.core.$strip>;
 export type UpdateStoreRequest = z.infer<typeof updateStoreRequestSchema>;
 export declare const storeSchema: z.ZodObject<{
@@ -3762,6 +4107,25 @@ export declare const storeSchema: z.ZodObject<{
   guestCheckoutEnabled: z.ZodBoolean;
   autoDeliverDays: z.ZodNumber;
   autoConfirmDays: z.ZodNumber;
+  refundPolicy: z.ZodObject<{
+    preShipmentDeliveryFeeRefund: z.ZodBoolean;
+    returnDeliveryFee: z.ZodNumber;
+    exchangeDeliveryFee: z.ZodNumber;
+    sellerFaultFreeShipping: z.ZodBoolean;
+    conditionalFreeShortfallCharge: z.ZodBoolean;
+  }, z.core.$strip>;
+  shippingPolicy: z.ZodObject<{
+    baseDeliveryFee: z.ZodNumber;
+    freeThreshold: z.ZodNullable<z.ZodNumber>;
+    jejuSurcharge: z.ZodNumber;
+    isolatedSurcharge: z.ZodNumber;
+  }, z.core.$strip>;
+  termsVersion: z.ZodString;
+  privacyVersion: z.ZodString;
+  termsVersionUpdatedAt: z.ZodNullable<z.ZodString>;
+  privacyVersionUpdatedAt: z.ZodNullable<z.ZodString>;
+  termsUrl: z.ZodNullable<z.ZodString>;
+  privacyUrl: z.ZodNullable<z.ZodString>;
   memberCount: z.ZodNumber;
   createdAt: z.ZodString;
 }, z.core.$strip>;
@@ -4270,6 +4634,13 @@ export declare function createStoreClient(options: StoreClientOptions): {
       conditionalFreeAmount?: number | null | undefined;
       returnFee?: number | undefined;
       exchangeFee?: number | undefined;
+      refundPolicy?: {
+        preShipmentDeliveryFeeRefund?: boolean | undefined;
+        returnDeliveryFee?: number | undefined;
+        exchangeDeliveryFee?: number | undefined;
+        sellerFaultFreeShipping?: boolean | undefined;
+        conditionalFreeShortfallCharge?: boolean | undefined;
+      } | null | undefined;
       shippingAddressId?: string | null | undefined;
       returnAddressId?: string | null | undefined;
       createdAt?: string | undefined;
@@ -4321,6 +4692,13 @@ export declare function createStoreClient(options: StoreClientOptions): {
       conditionalFreeAmount?: number | null | undefined;
       returnFee?: number | undefined;
       exchangeFee?: number | undefined;
+      refundPolicy?: {
+        preShipmentDeliveryFeeRefund?: boolean | undefined;
+        returnDeliveryFee?: number | undefined;
+        exchangeDeliveryFee?: number | undefined;
+        sellerFaultFreeShipping?: boolean | undefined;
+        conditionalFreeShortfallCharge?: boolean | undefined;
+      } | null | undefined;
       shippingAddressId?: string | null | undefined;
       returnAddressId?: string | null | undefined;
       createdAt?: string | undefined;
@@ -4372,6 +4750,13 @@ export declare function createStoreClient(options: StoreClientOptions): {
       conditionalFreeAmount?: number | null | undefined;
       returnFee?: number | undefined;
       exchangeFee?: number | undefined;
+      refundPolicy?: {
+        preShipmentDeliveryFeeRefund?: boolean | undefined;
+        returnDeliveryFee?: number | undefined;
+        exchangeDeliveryFee?: number | undefined;
+        sellerFaultFreeShipping?: boolean | undefined;
+        conditionalFreeShortfallCharge?: boolean | undefined;
+      } | null | undefined;
       shippingAddressId?: string | null | undefined;
       returnAddressId?: string | null | undefined;
       createdAt?: string | undefined;
@@ -4665,6 +5050,25 @@ export declare function createStoreClient(options: StoreClientOptions): {
         discountAmount: number;
         totalAmount: number;
         paidAt: string | null;
+        cashReceipt: {
+          cashReceiptId: string;
+          status: string;
+          type: string;
+          identityType: string;
+          identityNumberMasked: string;
+          amount: number;
+          issuedAmount: number;
+          provider: "tosspayments" | "portone" | null;
+          issueNumber: string | null;
+          receiptUrl: string | null;
+          issuedAt: string | null;
+          canceledAt: string | null;
+          failCode: string | null;
+          failMessage: string | null;
+          reissuable: boolean;
+          requestedAt: string;
+          updatedAt: string;
+        } | null;
       };
       testPayment: boolean;
       items: {
@@ -4678,6 +5082,8 @@ export declare function createStoreClient(options: StoreClientOptions): {
         optionName: string | null;
         sellerCode: string | null;
         quantity: number;
+        canceledQuantity: number;
+        activeQuantity: number;
         unitPrice: number;
         discountAmount: number;
         totalPrice: number;
@@ -4693,6 +5099,29 @@ export declare function createStoreClient(options: StoreClientOptions): {
         testPayment: boolean;
       }[];
     }>;
+    /**
+     * `POST /v1/orders/{orderId}/cash-receipt/reissue` — 실패했거나 재시도 대기 중인 현금영수증을 지금 다시 발급·취소한다.
+     * 콘솔 OWNER·ADMIN 전용(PAT·M2M 403 `INSUFFICIENT_ROLE`). 404 `CASH_RECEIPT_NOT_FOUND`, 409 `CASH_RECEIPT_NOT_REISSUABLE`
+     */
+    reissueCashReceipt: (orderId: string) => Promise<{
+      cashReceiptId: string;
+      status: string;
+      type: string;
+      identityType: string;
+      identityNumberMasked: string;
+      amount: number;
+      issuedAmount: number;
+      provider: "tosspayments" | "portone" | null;
+      issueNumber: string | null;
+      receiptUrl: string | null;
+      issuedAt: string | null;
+      canceledAt: string | null;
+      failCode: string | null;
+      failMessage: string | null;
+      reissuable: boolean;
+      requestedAt: string;
+      updatedAt: string;
+    }>;
   };
   orderItems: {
     /** `GET /v1/order-items`. `testPayment` 필터는 `orders.list`와 같다 */
@@ -4712,6 +5141,8 @@ export declare function createStoreClient(options: StoreClientOptions): {
         optionName: string | null;
         sellerCode: string | null;
         quantity: number;
+        canceledQuantity: number;
+        activeQuantity: number;
         unitPrice: number;
         discountAmount: number;
         totalPrice: number;
@@ -4743,6 +5174,10 @@ export declare function createStoreClient(options: StoreClientOptions): {
     cancelBySeller: (orderItemId: string, body: CancelBySellerRequest, idempotencyKey?: string) => Promise<{
       orderItemId: string;
       refundAmount: number;
+      quantity: number;
+      canceledQuantity: number;
+      deliveryFeeRefundAmount: number;
+      deliveryFeeChargeAmount: number;
       refundedAt: string;
     }>;
     updateMemo: (orderItemId: string, memo: string) => Promise<void>;
@@ -4791,6 +5226,8 @@ export declare function createStoreClient(options: StoreClientOptions): {
       optionName: string | null;
       sellerCode: string | null;
       quantity: number;
+      canceledQuantity: number;
+      activeQuantity: number;
       unitPrice: number;
       discountAmount: number;
       totalPrice: number;
@@ -4826,10 +5263,17 @@ export declare function createStoreClient(options: StoreClientOptions): {
       status: "DISPATCHED" | "DELIVERING" | "DELIVERED";
       dispatchedAt: string;
       deliveredAt: string | null;
+      tracking: {
+        result: string | null;
+        stage: string | null;
+        checkedAt: string | null;
+        carrierDeliveredAt: string | null;
+      } | null;
       trackingEvents?: {
         status: string;
         location: string;
         occurredAt: string;
+        stage: string | null;
       }[] | undefined;
     }>;
   };
@@ -4859,6 +5303,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
         responsibility: "BUYER" | "SELLER";
         claimDeliveryFee: number;
         expectedRefundAmount: number | null;
+        expectedDeliveryFeeRefundAmount: number | null;
         exchangeOption: {
           optionId: string;
           optionName: string;
@@ -4872,6 +5317,14 @@ export declare function createStoreClient(options: StoreClientOptions): {
         completedAt: string | null;
         holdExpiresAt: string | null;
         holdUsed: boolean;
+        returnAddress: {
+          name: string;
+          contactName: string;
+          phone: string;
+          zipCode: string;
+          address1: string;
+          address2: string | null;
+        } | null;
       }[];
     }>;
     get: (claimId: string) => Promise<{
@@ -4887,6 +5340,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
       responsibility: "BUYER" | "SELLER";
       claimDeliveryFee: number;
       expectedRefundAmount: number | null;
+      expectedDeliveryFeeRefundAmount: number | null;
       exchangeOption: {
         optionId: string;
         optionName: string;
@@ -4900,6 +5354,14 @@ export declare function createStoreClient(options: StoreClientOptions): {
       completedAt: string | null;
       holdExpiresAt: string | null;
       holdUsed: boolean;
+      returnAddress: {
+        name: string;
+        contactName: string;
+        phone: string;
+        zipCode: string;
+        address1: string;
+        address2: string | null;
+      } | null;
       histories?: {
         status: "REQUESTED" | "HELD" | "COLLECTING" | "COLLECTED" | "REDELIVERING" | "APPROVED" | "REJECTED" | "COMPLETED" | "WITHDRAWN";
         actor: "BUYER" | "SELLER" | "SYSTEM";
@@ -4910,6 +5372,9 @@ export declare function createStoreClient(options: StoreClientOptions): {
       claimId: string;
       refundAmount: number;
       deductAmount: number;
+      quantity: number;
+      deliveryFeeRefundAmount: number;
+      deliveryFeeChargeAmount: number;
       refundedAt: string;
     }>;
     reject: (claimId: string, body: RejectClaimRequest) => Promise<void>;
@@ -4938,6 +5403,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
       responsibility: "BUYER" | "SELLER";
       claimDeliveryFee: number;
       expectedRefundAmount: number | null;
+      expectedDeliveryFeeRefundAmount: number | null;
       exchangeOption: {
         optionId: string;
         optionName: string;
@@ -4951,6 +5417,14 @@ export declare function createStoreClient(options: StoreClientOptions): {
       completedAt: string | null;
       holdExpiresAt: string | null;
       holdUsed: boolean;
+      returnAddress: {
+        name: string;
+        contactName: string;
+        phone: string;
+        zipCode: string;
+        address1: string;
+        address2: string | null;
+      } | null;
     }>;
   };
   inquiries: {
@@ -5130,6 +5604,36 @@ export declare function createStoreClient(options: StoreClientOptions): {
         method: "kakao" | "naver" | "google" | "password";
         linkedAt: string;
       }[];
+      consents: {
+        terms: {
+          kind: "TERMS" | "PRIVACY" | "MARKETING";
+          agreed: boolean;
+          agreedVersion: string | null;
+          currentVersion: string | null;
+          currentDocumentUrl: string | null;
+          updatedAt: string | null;
+          reconsentRequired: boolean;
+        };
+        privacy: {
+          kind: "TERMS" | "PRIVACY" | "MARKETING";
+          agreed: boolean;
+          agreedVersion: string | null;
+          currentVersion: string | null;
+          currentDocumentUrl: string | null;
+          updatedAt: string | null;
+          reconsentRequired: boolean;
+        };
+        marketing: {
+          kind: "TERMS" | "PRIVACY" | "MARKETING";
+          agreed: boolean;
+          agreedVersion: string | null;
+          currentVersion: string | null;
+          currentDocumentUrl: string | null;
+          updatedAt: string | null;
+          reconsentRequired: boolean;
+        };
+        reconsentRequired: boolean;
+      };
       addresses: {
         addressId: string;
         alias: string;
@@ -5169,6 +5673,24 @@ export declare function createStoreClient(options: StoreClientOptions): {
         }[];
       }[];
     }>;
+    /** 동의 이력 — 최근 순. 가입·재동의·마케팅 변경이 한 줄씩 남는다 */
+    consents: (customerId: string, params?: PageParams & {
+      kind?: ConsentKind;
+    }) => Promise<{
+      page: number;
+      size: number;
+      totalElements: number;
+      totalPages: number;
+      contents: {
+        consentId: string;
+        kind: "TERMS" | "PRIVACY" | "MARKETING";
+        version: string | null;
+        documentUrl: string | null;
+        action: "WITHDRAWN" | "AGREED";
+        source: "SELLER" | "SIGNUP" | "SOCIAL_SIGNUP" | "DELEGATED" | "RECONSENT" | "MEMBER_UPDATE";
+        occurredAt: string;
+      }[];
+    }>;
     withdraw: (customerId: string, body: WithdrawCustomerRequest) => Promise<void>;
   };
   customerInquiries: {
@@ -5536,6 +6058,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
         failMessage: string | null;
         paidAt: string | null;
         createdAt: string;
+        cashReceiptStatus: string | null;
       }[];
     }>;
     /** `GET /v1/payments/{paymentId}` — 시도·환불 이력 포함. 404 `PAYMENT_NOT_FOUND` */
@@ -5559,6 +6082,7 @@ export declare function createStoreClient(options: StoreClientOptions): {
       failMessage: string | null;
       paidAt: string | null;
       createdAt: string;
+      cashReceiptStatus: string | null;
       refundableAmount: number;
       merchantId: string | null;
       attempts: {
@@ -5588,6 +6112,25 @@ export declare function createStoreClient(options: StoreClientOptions): {
         requestedAt: string;
         completedAt: string | null;
       }[];
+      cashReceipt: {
+        cashReceiptId: string;
+        status: string;
+        type: string;
+        identityType: string;
+        identityNumberMasked: string;
+        amount: number;
+        issuedAmount: number;
+        provider: "tosspayments" | "portone" | null;
+        issueNumber: string | null;
+        receiptUrl: string | null;
+        issuedAt: string | null;
+        canceledAt: string | null;
+        failCode: string | null;
+        failMessage: string | null;
+        reissuable: boolean;
+        requestedAt: string;
+        updatedAt: string;
+      } | null;
     }>;
   };
   /**
@@ -6540,6 +7083,25 @@ export declare function createStoreClient(options: StoreClientOptions): {
       guestCheckoutEnabled: boolean;
       autoDeliverDays: number;
       autoConfirmDays: number;
+      refundPolicy: {
+        preShipmentDeliveryFeeRefund: boolean;
+        returnDeliveryFee: number;
+        exchangeDeliveryFee: number;
+        sellerFaultFreeShipping: boolean;
+        conditionalFreeShortfallCharge: boolean;
+      };
+      shippingPolicy: {
+        baseDeliveryFee: number;
+        freeThreshold: number | null;
+        jejuSurcharge: number;
+        isolatedSurcharge: number;
+      };
+      termsVersion: string;
+      privacyVersion: string;
+      termsVersionUpdatedAt: string | null;
+      privacyVersionUpdatedAt: string | null;
+      termsUrl: string | null;
+      privacyUrl: string | null;
       memberCount: number;
       createdAt: string;
     }>;
@@ -6561,6 +7123,25 @@ export declare function createStoreClient(options: StoreClientOptions): {
       guestCheckoutEnabled: boolean;
       autoDeliverDays: number;
       autoConfirmDays: number;
+      refundPolicy: {
+        preShipmentDeliveryFeeRefund: boolean;
+        returnDeliveryFee: number;
+        exchangeDeliveryFee: number;
+        sellerFaultFreeShipping: boolean;
+        conditionalFreeShortfallCharge: boolean;
+      };
+      shippingPolicy: {
+        baseDeliveryFee: number;
+        freeThreshold: number | null;
+        jejuSurcharge: number;
+        isolatedSurcharge: number;
+      };
+      termsVersion: string;
+      privacyVersion: string;
+      termsVersionUpdatedAt: string | null;
+      privacyVersionUpdatedAt: string | null;
+      termsUrl: string | null;
+      privacyUrl: string | null;
       memberCount: number;
       createdAt: string;
     }>;
@@ -6644,6 +7225,77 @@ export declare function exchangeStoreTokenViaOAuth(options: {
   role?: string;
 }>;
 //#endregion
+//#region src/schemas/refund-policy.d.ts
+/** 유효 환불 정책 — 스토어 기본 + 상품별 덮어쓰기를 합친 결과 */
+export declare const refundPolicySchema: z.ZodObject<{
+  preShipmentDeliveryFeeRefund: z.ZodBoolean;
+  returnDeliveryFee: z.ZodNumber;
+  exchangeDeliveryFee: z.ZodNumber;
+  sellerFaultFreeShipping: z.ZodBoolean;
+  conditionalFreeShortfallCharge: z.ZodBoolean;
+}, z.core.$strip>;
+export type RefundPolicy = z.infer<typeof refundPolicySchema>;
+/**
+ * 스토어가 정하지 않았을 때 서버가 쓰는 값.
+ *
+ * `as const`가 아니라 `RefundPolicy`로 타입을 좁힌다 — 리터럴 타입이면 `Partial<typeof …>`로 일부만 바꿀 때
+ * `true` 자리에 `false`를 넣을 수 없다.
+ */
+export declare const REFUND_POLICY_DEFAULTS: RefundPolicy;
+/**
+ * 부분 정책 — 스토어 설정 요청과 상품별 덮어쓰기가 쓴다. 준 항목만 바뀐다.
+ *
+ * `strictObject`라 모르는 키는 400이다. 오타(`returnFee` 등)를 조용히 무시하면 셀러는 저장됐다고
+ * 믿는데 정책은 기본값으로 남는다.
+ */
+export declare const refundPolicyPatchSchema: z.ZodObject<{
+  preShipmentDeliveryFeeRefund: z.ZodOptional<z.ZodBoolean>;
+  returnDeliveryFee: z.ZodOptional<z.ZodNumber>;
+  exchangeDeliveryFee: z.ZodOptional<z.ZodNumber>;
+  sellerFaultFreeShipping: z.ZodOptional<z.ZodBoolean>;
+  conditionalFreeShortfallCharge: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type RefundPolicyPatch = z.infer<typeof refundPolicyPatchSchema>;
+/** 정책 해석에 쓰는 상품 값 — 상품별 덮어쓰기와 레거시 배송비 필드 */
+export interface RefundPolicyProductInput {
+  /** 상품별 덮어쓰기. 없으면 스토어 기본을 그대로 쓴다 */
+  refundPolicy?: RefundPolicyPatch | null;
+  /** @deprecated 레거시 상품 반품비 — `refundPolicy`가 없는 옛 상품의 값이다 */
+  returnFee?: number | null;
+  /** @deprecated 레거시 상품 교환비 — `refundPolicy`가 없는 옛 상품의 값이다 */
+  exchangeFee?: number | null;
+}
+/**
+ * 유효 정책 해석 — 상품별 덮어쓰기 → 스토어 기본 → `REFUND_POLICY_DEFAULTS` 순이다.
+ *
+ * 반품비·교환비는 레거시 필드(`products.returnFee`·`exchangeFee`)와 **연결**한다. 상품이
+ * `refundPolicy.returnDeliveryFee`를 정하면 그 값이 원천이고(서버가 `returnFee`도 같은 값으로 맞춘다),
+ * 정하지 않았으면 레거시 값이 0보다 클 때 그 값을 쓴다. 0이면 스토어 기본을 따른다 —
+ * 정책이 생기기 전에 만든 상품(반품비 0)이 스토어 기본을 물려받게 하는 규칙이다.
+ */
+export declare function resolveRefundPolicy(storePolicy?: RefundPolicyPatch | null, product?: RefundPolicyProductInput | null): RefundPolicy;
+/**
+ * 상품의 **덮어쓰기 자체** — 레거시 반품비·교환비를 같은 형태로 승격한 값이다. 덮어쓰기가 없으면 null.
+ *
+ * `resolveRefundPolicy`가 합친 결과로는 "상품이 정한 값"과 "스토어 기본을 물려받은 값"을 가를 수 없다.
+ * 관리 API 응답의 `refundPolicy`와 콘솔 폼의 덮어쓰기 스위치가 이 함수를 원천으로 쓴다 — 가르지 못하면
+ * 스토어 기본을 쓰는 상품을 저장할 때 그 순간의 기본값이 상품에 박히거나, 레거시 값이 조용히 사라진다.
+ */
+export declare function productRefundPolicyOverride(product?: RefundPolicyProductInput | null): RefundPolicyPatch | null;
+/**
+ * 수량 단위 부분 취소의 환불 기준액 — **누적 내림의 차분**이다.
+ *
+ * 원 단위 반올림 규칙: `floor(주문상품 금액 × 누적 수량 ÷ 전체 수량)`을 두 번 구해 그 차를 쓴다.
+ * 부분 취소를 몇 번 나눠도 합이 주문상품 금액과 정확히 같아서 1원이 남거나 넘치지 않는다.
+ * 할인은 이미 단가에 들어 있어(주문 단위 쿠폰이 없다) 별도 안분이 없다.
+ *
+ * @param totalPrice 주문상품 금액 (할인 반영 단가 × 전체 수량)
+ * @param quantity 주문상품 전체 수량
+ * @param settledQuantity 이미 취소·반품된 누적 수량
+ * @param cancelQuantity 이번에 취소·반품할 수량
+ */
+export declare function proratedRefundBase(totalPrice: number, quantity: number, settledQuantity: number, cancelQuantity: number): number;
+//#endregion
 //#region src/schemas/scope.d.ts
 /**
  * 스토어 스코프 카탈로그 (auth-spec §7) — 형식 `{리소스}:{r|rw}`, rw는 r을 함의한다.
@@ -6700,6 +7352,194 @@ export declare const STORE_ROLE_SCOPES: {
   readonly STAFF: readonly ["product:rw", "category:rw", "order:rw", "claim:rw", "inquiry:rw", "review:rw", "customer:r"];
 };
 //#endregion
+//#region src/schemas/shipping-policy.d.ts
+/** 유효 배송비 정책 — 스토어가 정하지 않은 항목은 `SHIPPING_POLICY_DEFAULTS`로 채운 값이다 */
+export declare const shippingPolicySchema: z.ZodObject<{
+  baseDeliveryFee: z.ZodNumber;
+  freeThreshold: z.ZodNullable<z.ZodNumber>;
+  jejuSurcharge: z.ZodNumber;
+  isolatedSurcharge: z.ZodNumber;
+}, z.core.$strip>;
+export type ShippingPolicy = z.infer<typeof shippingPolicySchema>;
+/**
+ * 스토어가 정하지 않았을 때 서버가 쓰는 값.
+ *
+ * `as const`가 아니라 `ShippingPolicy`로 좁힌다 — 리터럴 타입이면 `Partial<typeof …>`로 일부만 바꿀 때
+ * `null` 자리에 숫자를 넣을 수 없다(`REFUND_POLICY_DEFAULTS`와 같은 이유).
+ */
+export declare const SHIPPING_POLICY_DEFAULTS: ShippingPolicy;
+/**
+ * 부분 정책 — `PATCH /v1/store`의 `shippingPolicy`가 쓴다. 준 항목만 바뀐다.
+ *
+ * `strictObject`라 모르는 키는 400이다. 오타를 조용히 무시하면 셀러는 저장됐다고 믿는데
+ * 정책은 기본값으로 남는다(`refundPolicyPatchSchema`와 같은 이유).
+ */
+export declare const shippingPolicyPatchSchema: z.ZodObject<{
+  baseDeliveryFee: z.ZodOptional<z.ZodNumber>;
+  freeThreshold: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+  jejuSurcharge: z.ZodOptional<z.ZodNumber>;
+  isolatedSurcharge: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type ShippingPolicyPatch = z.infer<typeof shippingPolicyPatchSchema>;
+/** 유효 정책 해석 — 스토어가 정한 항목 + `SHIPPING_POLICY_DEFAULTS` */
+export declare function resolveShippingPolicy(patch?: ShippingPolicyPatch | null): ShippingPolicy;
+/** 지역 구분 — 우편번호로 판정한다 */
+export declare const remoteAreaSchema: z.ZodEnum<{
+  NONE: "NONE";
+  JEJU: "JEJU";
+  ISOLATED: "ISOLATED";
+}>;
+export type RemoteArea = z.infer<typeof remoteAreaSchema>;
+/**
+ * 제주·도서산간 우편번호 범위 — **코드 상수다.** 금액은 스토어가 정하고 범위는 플랫폼이 고정한다.
+ *
+ * 국내 택배사가 공표하는 제주·도서산간 할증 구간을 5자리 우편번호 범위로 옮긴 표다. 셀러마다
+ * 범위가 다르면 같은 주소에 다른 금액이 나가고 CS가 셀러 수만큼 갈라진다. 스토어별 범위 편집은
+ * 후속 과제이고, 지금은 이 표가 유일한 원천이다.
+ *
+ * ## 근거
+ *
+ * 원천은 **CJ대한통운이 공표한 「제주 및 도서산간 지역 추가 운송비」 표**(구간 시작·끝 우편번호와
+ * 지역명이 붙은 그 표)다. 같은 표가 한진택배 공지와 쇼핑몰 솔루션 안내에도 같은 값으로 실린다.
+ * 서로 다른 게시자의 전재본 네 곳이 인천·전남·경남 구간까지 글자 그대로 일치하는 것을 확인했다.
+ *
+ * - CJ대한통운 표 전재 (구간별 금액 포함): https://ichibanhouse.com/article/공지뉴스/1/16/
+ * - 같은 표의 다른 전재본: https://peppytail.com/article/공지사항/1/4046/
+ * - 시행 시점(2020-02-01)과 구간별 행정구역명을 함께 적은 전재본:
+ *   https://tosstoss.co.kr/bbs/content.php?co_id=pilotage
+ * - 솔루션 안내 「제주도 및 도서산간 지역 기준표」:
+ *   https://help.campaignus.me/ko/articles/제주도-및-도서산간-지역-기준표-342d2e5e
+ *
+ * 라벨의 행정구역명은 우편번호 배정을 따로 확인해 고쳤다. 택배사 표의 지역명은 축약·오기가 있다.
+ * 확인한 것만 남기고, 확인하지 못한 구간은 이 표에서 뺀다 — 판정하지 못하면 받지 않는 쪽이
+ * `remoteAreaOf`의 규칙과 같다.
+ *
+ * ## 표에서 뺀 구간
+ *
+ * - **54000**: 택배사 표는 「경남 통영 섬지역3」으로 적었지만 이 번호는 **전북 군산시 옥도면**이다.
+ *   게다가 공정거래위원회가 2025-10-07 발표에서 연륙교로 이어진 신시도·야미도·선유도와 비연륙
+ *   도서(방축도·관리도)가 같은 우편번호를 쓰는 대표 사례로 이 지역을 들었다. 라벨도 부과 근거도
+ *   확정하지 못해 뺀다.
+ * - **강화군 본섬(23000~23003, 23011~23099)**: 택배사 표의 강화 할증 구간은 23004~23010
+ *   (교동면·삼산면·서도면)뿐이다. 강화대교·초지대교로 이어진 본섬은 도선료가 없어 어느 택배사도
+ *   할증하지 않는다. 「누락」이 아니라 대상이 아니다.
+ *
+ * ## 한계
+ *
+ * 우편번호 단위 판정은 한 번호 안에 연륙도서와 비연륙도서가 섞인 구간에서 과대 부과가 된다.
+ * 공정위가 2025-10-07에 온라인몰 13곳의 이 방식을 시정하게 한 지적이 그것이다
+ * (https://eiec.kdi.re.kr/policy/materialView.do?num=272070). 아래 구간 중 33411(보령 오천면,
+ * 원산도가 해저터널로 연결), 46768~46771(강서구 가덕도, 거가대교로 연결)이 그런 혼재 구간이다.
+ * 도로명주소·건물관리번호 단위 판정은 후속 과제다.
+ *
+ * 범위는 **닫힌 구간**(`from` ≤ zip ≤ `to`)이고 겹치지 않는다. 앞에서부터 처음 맞는 항목을 쓴다.
+ * 순서는 콘솔 「추가 배송비 지역」 표의 행 순서이기도 하다(`remoteAreaGroups`). 제주를 먼저 두고
+ * 도서산간은 우편번호 오름차순으로 둔다.
+ */
+export declare const REMOTE_AREA_ZIP_RANGES: ReadonlyArray<{
+  readonly area: Exclude<RemoteArea, "NONE">;
+  readonly from: number;
+  readonly to: number;
+  readonly label: string;
+}>;
+/**
+ * 우편번호 → 지역 구분. 5자리 숫자가 아니면 `NONE`이다.
+ *
+ * 형식 검증은 배송지 스키마(`/^[0-9]{5}$/`)가 하고, 여기서는 **판정하지 못하면 추가 배송비를 받지 않는다**.
+ * 반대로 두면 우편번호를 잘못 넣은 주문에 근거 없는 금액이 붙는다.
+ */
+export declare function remoteAreaOf(zipCode: string | null | undefined): RemoteArea;
+/** 지역 구분의 안내 이름 — 판정된 범위의 `label`이다. 판정되지 않으면 null */
+export declare function remoteAreaLabelOf(zipCode: string | null | undefined): string | null;
+/** 묶음 하나에 붙는 지역 추가 배송비 */
+export declare function remoteSurchargeOf(policy: ShippingPolicy, area: RemoteArea): number;
+/** 묶음 판정에 쓰는 상품 값 — 출고지와 배송 정책이다 */
+export interface DeliveryBundleProduct {
+  deliveryType: DeliveryType;
+  deliveryFee: number;
+  conditionalFreeAmount: number | null;
+  /** 출고지 주소 id(`seller_addresses`). null이면 스토어 기본 출고지를 쓰는 상품끼리 한 묶음이다 */
+  shippingAddressId?: string | null;
+}
+/**
+ * 배송 묶음 키 — **같은 출고지 + 같은 배송 정책이면 같은 키다.**
+ *
+ * 키는 주문 시점에 주문상품 행에 스냅샷된다(`order_items.delivery_bundle_key`). 셀러가 주문 뒤
+ * 출고지나 배송비를 바꿔도 그 주문의 묶음은 움직이지 않는다 — 움직이면 이미 환불한 묶음의 키가
+ * 달라져 `orders.delivery_fee_settlements`의 이중 환불 방지 표시가 무력해진다.
+ *
+ * `-`는 「값 없음」이다. 사람이 읽을 수 있게 남기고, 값 자체에 `:`가 들어갈 수 없는 형식만 쓴다
+ * (주소 id는 `adr_…`, 나머지는 열거형·정수).
+ */
+export declare function deliveryBundleKeyOf(product: DeliveryBundleProduct): string;
+/** 계산에 넣는 한 줄 — 주문상품·장바구니 항목·주문서 항목이 이 형태로 들어온다 */
+export interface DeliveryFeeLine {
+  productId: string;
+  /** 상품 금액 (할인 반영 단가 × 수량) */
+  amount: number;
+}
+/**
+ * 기본 배송비를 면제한 근거 — 면제하지 않았으면 null이다.
+ *
+ * 환불 정산이 근거를 구분해야 한다. 조건부 무료 기준 미달 차감은 **상품별 조건부 무료(`CONDITIONAL`)로
+ * 면제된 묶음만** 대상이다. 스토어 전체 무료 기준(`STORE_THRESHOLD`)이나 무료배송 상품(`FREE`)은 셀러가
+ * 배송비를 받지 않기로 한 것이므로, 일부 취소로 기준이 깨져도 구매자에게 배송비를 물리지 않는다.
+ *
+ * 세 값이 겹치면 `FREE` → `STORE_THRESHOLD` → `CONDITIONAL` 순으로 센 근거를 남긴다.
+ */
+export declare const deliveryFeeWaiverSchema: z.ZodEnum<{
+  FREE: "FREE";
+  STORE_THRESHOLD: "STORE_THRESHOLD";
+  CONDITIONAL: "CONDITIONAL";
+}>;
+export type DeliveryFeeWaiver = z.infer<typeof deliveryFeeWaiverSchema>;
+/** 묶음 하나의 견적 */
+export interface DeliveryBundleQuote {
+  bundleKey: string;
+  /** 이 묶음에 든 상품 id — 스냅샷 검증과 콘솔 안내에 쓴다 */
+  productIds: string[];
+  /** 실제 청구한 기본 배송비 — 무료배송·무료 기준 충족이면 0 */
+  fee: number;
+  /** 기본 배송비를 면제한 근거. 청구했으면 null */
+  waivedBy: DeliveryFeeWaiver | null;
+  /** 배송비 정가 — 조건부 무료 미달 차감액의 상한이다 */
+  listFee: number;
+  /** 묶음 조건부 무료 기준액. 조건부 무료가 아니면 null */
+  freeThreshold: number | null;
+  /** 이 묶음에 붙은 지역 추가 배송비 */
+  remoteSurcharge: number;
+}
+/** 배송비 견적 — 합계와 묶음 내역 */
+export interface DeliveryQuote {
+  bundles: DeliveryBundleQuote[];
+  /** 기본 배송비 합계 (지역 추가 제외) */
+  baseFee: number;
+  /** 지역 추가 배송비 합계 */
+  remoteSurcharge: number;
+  /** 청구할 배송비 총액 = `baseFee` + `remoteSurcharge` */
+  deliveryFee: number;
+  remoteArea: RemoteArea;
+  /** 스토어 전체 무료 기준(`freeThreshold`) 충족으로 기본 배송비를 면제했는가 */
+  freeByThreshold: boolean;
+}
+export interface DeliveryQuoteInput {
+  lines: DeliveryFeeLine[];
+  /** 상품 배송 정책 조회 — 못 읽은 상품은 계산에서 빠진다(배송비를 만들어 붙이지 않는다) */
+  productOf: (productId: string) => DeliveryBundleProduct | undefined;
+  policy: ShippingPolicy;
+  /** 배송지 우편번호. 아직 모르면 생략한다 — 지역 추가 배송비 0으로 계산한다 */
+  zipCode?: string | null;
+}
+/**
+ * 배송비 계산 — **순수 함수다.** 장바구니 요약, 주문서 금액, 결제 시작의 최종 확정,
+ * 주문 배송비 스냅샷이 모두 이 한 곳을 쓴다.
+ *
+ * 순서가 규칙이다. 묶음별 조건부 무료를 먼저 보고, 그다음 스토어 전체 무료 기준으로 기본 배송비를
+ * 한꺼번에 0으로 만들고, 마지막에 지역 추가 배송비를 묶음마다 더한다. 추가 배송비는 무료 기준에
+ * 걸리지 않는다.
+ */
+export declare function quoteDelivery(input: DeliveryQuoteInput): DeliveryQuote;
+//#endregion
 //#region src/schemas/webhook-event.d.ts
 export declare const orderWebhookEventDataSchema: z.ZodObject<{
   orderId: z.ZodString;
@@ -6736,6 +7576,11 @@ export declare const claimWebhookEventDataSchema: z.ZodObject<{
     COMPLETED: "COMPLETED";
     WITHDRAWN: "WITHDRAWN";
   }>;
+  quantity: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+  refundAmount: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodNumber>>>;
+  deliveryFeeRefundAmount: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+  deliveryFeeChargeAmount: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+  deductAmount: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
   testPayment: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 }, z.core.$strip>;
 export type ClaimWebhookEventData = z.infer<typeof claimWebhookEventDataSchema>;
@@ -6809,6 +7654,11 @@ export declare const claimWebhookEventSchema: z.ZodObject<{
       COMPLETED: "COMPLETED";
       WITHDRAWN: "WITHDRAWN";
     }>;
+    quantity: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    refundAmount: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodNumber>>>;
+    deliveryFeeRefundAmount: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    deliveryFeeChargeAmount: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    deductAmount: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
     testPayment: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
   }, z.core.$strip>;
   id: z.ZodString;
@@ -6900,6 +7750,11 @@ export declare const webhookEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
       COMPLETED: "COMPLETED";
       WITHDRAWN: "WITHDRAWN";
     }>;
+    quantity: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    refundAmount: z.ZodDefault<z.ZodOptional<z.ZodNullable<z.ZodNumber>>>;
+    deliveryFeeRefundAmount: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    deliveryFeeChargeAmount: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    deductAmount: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
     testPayment: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
   }, z.core.$strip>;
   id: z.ZodString;