@sayren/store-sdk 0.9.0 → 0.11.0

package/package.json

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

package/src/client.ts

@@ -70,6 +70,8 @@ import {
 } from "./schemas/claim";
 import { bulkResultSchema, type PageParams, pageSchema } from "./schemas/common";
 import {
+  type ConsentKind,
+  customerConsentSchema,
   customerDetailSchema,
   type customerListQuerySchema,
   customerOrderSchema,
@@ -126,6 +128,7 @@ import {
   purchaseDecisionExtendResultSchema,
 } from "./schemas/order";
 import {
+  cashReceiptSchema,
   type PaymentListParams,
   type PgEnvironment,
   type PgProvider,
@@ -528,6 +531,12 @@ export function createStoreClient(options: StoreClientOptions) {
           query: params as unknown as Query,
         }),
       get: (orderId: string) => storeHttp.request("GET", path`/orders/${orderId}`, orderSchema),
+      /**
+       * `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) =>
+        storeHttp.request("POST", path`/orders/${orderId}/cash-receipt/reissue`, cashReceiptSchema),
     },
 
     orderItems: {
@@ -708,6 +717,14 @@ export function createStoreClient(options: StoreClientOptions) {
             query: params as Query,
           },
         ),
+      /** 동의 이력 — 최근 순. 가입·재동의·마케팅 변경이 한 줄씩 남는다 */
+      consents: (customerId: string, params?: PageParams & { kind?: ConsentKind }) =>
+        storeHttp.request(
+          "GET",
+          path`/customers/${customerId}/consents`,
+          pageSchema(customerConsentSchema),
+          { query: params as Query },
+        ),
       withdraw: (customerId: string, body: WithdrawCustomerRequest) =>
         storeHttp.requestVoid("POST", path`/customers/${customerId}/withdraw`, {
           body: withdrawCustomerRequestSchema.parse(body),

package/src/index.ts

@@ -24,7 +24,9 @@ export * from "./schemas/misc";
 export * from "./schemas/order";
 export * from "./schemas/payment";
 export * from "./schemas/product";
+export * from "./schemas/refund-policy";
 export * from "./schemas/scope";
+export * from "./schemas/shipping-policy";
 export * from "./schemas/store";
 export * from "./schemas/upload";
 export * from "./schemas/webhook-event";

package/src/schemas/claim.ts

@@ -30,6 +30,24 @@ export const claimReasonSchema = z.enum([
 
 export type ClaimReason = z.infer<typeof claimReasonSchema>;
 
+/**
+ * 반품지 (이슈 #30) — 반품·교환 수거가 안내하는 주소다. 스토어 주소록의 기본 반품지이거나,
+ * 상품이 반품지를 따로 지정했으면 그 주소다.
+ *
+ * 취소 클레임은 보낼 물건이 없어 null이고, 반품지를 등록하지 않은 스토어도 null이다.
+ * 구매자가 직접 보내는 수거(`BUYER_SEND`)에 이 주소가 필요하다.
+ */
+export const claimReturnAddressSchema = z.object({
+  name: z.string().describe("주소 이름(셀러가 붙인 별칭). 예: 본사 물류센터"),
+  contactName: z.string().describe("수취인 이름"),
+  phone: z.string().describe("연락처"),
+  zipCode: z.string(),
+  address1: z.string(),
+  address2: z.string().nullable(),
+});
+
+export type ClaimReturnAddress = z.infer<typeof claimReturnAddressSchema>;
+
 export const claimSchema = z.object({
   claimId: z.string(),
   type: claimTypeSchema,
@@ -41,8 +59,24 @@ export const claimSchema = z.object({
   reason: claimReasonSchema,
   reasonDetail: z.string().nullable(),
   responsibility: z.enum(["BUYER", "SELLER"]),
-  claimDeliveryFee: z.number().int(),
-  expectedRefundAmount: z.number().int().nullable(),
+  claimDeliveryFee: z.number().int().describe("구매자가 부담하는 반품·교환 배송비. 원 단위"),
+  expectedRefundAmount: z
+    .number()
+    .int()
+    .nullable()
+    .describe(
+      "접수 시점에 계산한 예상 환불액 — 수량 비율 상품 금액 − 반품 배송비 − 조건부 무료배송 미달 차감. " +
+        "**배송비 환불은 포함되지 않고 `expectedDeliveryFeeRefundAmount`로 따로 온다**" +
+        "(승인 시점의 배송 묶음 상태로 확정되기 때문이다). 교환은 환불이 없어 null이다",
+    ),
+  expectedDeliveryFeeRefundAmount: z
+    .number()
+    .int()
+    .nullable()
+    .describe(
+      "접수 시점에 계산한 예상 배송비 환불액. 배송 묶음(같은 상품의 주문상품)이 모두 취소되거나 " +
+        "판매자 귀책일 때만 0보다 크다. 이 필드가 생기기 전에 접수된 클레임은 null이다",
+    ),
   exchangeOption: z.object({ optionId: z.string(), optionName: z.string() }).nullable(),
   collect: z
     .object({
@@ -57,6 +91,12 @@ export const claimSchema = z.object({
   holdExpiresAt: z.string().nullable(),
   /** 보류를 이미 썼는지 — 보류는 클레임당 1회라 해제·만료 뒤에도 true */
   holdUsed: z.boolean(),
+  returnAddress: claimReturnAddressSchema
+    .nullable()
+    .describe(
+      "수거 안내에 쓸 반품지(이슈 #30). 상품이 지정한 반품지, 없으면 스토어 기본 반품지다. " +
+        "취소 클레임과 반품지를 등록하지 않은 스토어는 null",
+    ),
 });
 
 export type Claim = z.infer<typeof claimSchema>;
@@ -119,8 +159,26 @@ export type RejectClaimRequest = z.infer<typeof rejectClaimRequestSchema>;
 
 export const approveClaimResultSchema = z.object({
   claimId: z.string(),
-  refundAmount: z.number().int(),
-  deductAmount: z.number().int(),
+  refundAmount: z
+    .number()
+    .int()
+    .describe(
+      "실제 환불한 금액 — 수량 비율 상품 금액 + 배송비 환불 − 반품 배송비 − 조건부 무료배송 미달 차감 − " +
+        "추가 차감(`deductAmount`)",
+    ),
+  deductAmount: z.number().int().describe("승인 때 셀러가 추가로 차감한 금액"),
+  quantity: z.number().int().describe("환불한 수량"),
+  deliveryFeeRefundAmount: z
+    .number()
+    .int()
+    .describe("환불에 포함된 배송비. 배송 묶음 전량 취소나 판매자 귀책일 때만 0보다 크다"),
+  deliveryFeeChargeAmount: z
+    .number()
+    .int()
+    .describe(
+      "환불액에서 뺀 **배송비** — 반품·교환 배송비 + 조건부 무료배송 미달 차감. " +
+        "추가 차감(`deductAmount`)은 포함하지 않는다",
+    ),
   refundedAt: z.string(),
 });
 

package/src/schemas/customer.ts

@@ -58,6 +58,75 @@ export const customerAddressSchema = z.object({
   address2: z.string().nullable(),
 });
 
+// ── 동의 이력 (이슈 #26) ────────────────────────────────────
+
+/** 동의 종류 — 이용약관·개인정보 수집이용은 가입 필수, 마케팅 수신은 선택 */
+export const consentKindSchema = z.enum(["TERMS", "PRIVACY", "MARKETING"]);
+export type ConsentKind = z.infer<typeof consentKindSchema>;
+
+export const consentActionSchema = z.enum(["AGREED", "WITHDRAWN"]);
+export type ConsentAction = z.infer<typeof consentActionSchema>;
+
+/**
+ * 동의가 일어난 경로. 값이 추가될 수 있어 모르는 값은 그대로 보여 준다.
+ * `SIGNUP` 비밀번호 가입 · `SOCIAL_SIGNUP` 소셜 가입 · `DELEGATED` 셀러 자체 회원 연동 ·
+ * `RECONSENT` 약관 개정 재동의 · `MEMBER_UPDATE` 구매자가 직접 변경 · `SELLER` 셀러가 처리
+ */
+export const consentSourceSchema = z.enum([
+  "SIGNUP",
+  "SOCIAL_SIGNUP",
+  "DELEGATED",
+  "RECONSENT",
+  "MEMBER_UPDATE",
+  "SELLER",
+]);
+export type ConsentSource = z.infer<typeof consentSourceSchema>;
+
+/** 동의 이력 한 줄 — 추가만 되고 지워지지 않는다(구매자 탈퇴 시에만 함께 지워진다) */
+export const customerConsentSchema = z.object({
+  consentId: z.string(),
+  kind: consentKindSchema,
+  /** 동의한 약관 버전. 마케팅은 버전이 없어 null */
+  version: z.string().nullable(),
+  /** 동의 시점의 약관 문서 주소. 스토어가 주소를 정하지 않았거나 마케팅이면 null */
+  documentUrl: z.string().nullable(),
+  action: consentActionSchema,
+  source: consentSourceSchema,
+  occurredAt: z.string(),
+});
+export type CustomerConsent = z.infer<typeof customerConsentSchema>;
+
+/** 종류별 현재 동의 상태 */
+export const customerConsentStateSchema = z.object({
+  kind: consentKindSchema,
+  agreed: z.boolean(),
+  /** 동의한 약관 버전. 마케팅이거나 이력이 없으면 null */
+  agreedVersion: z.string().nullable(),
+  /** 스토어의 현재 약관 버전. 마케팅은 null */
+  currentVersion: z.string().nullable(),
+  /** 스토어가 정한 현재 약관 문서 주소. 정하지 않았거나 마케팅이면 null */
+  currentDocumentUrl: z.string().nullable(),
+  updatedAt: z.string().nullable(),
+  /** 약관이 개정돼 다시 받아야 하는가. 마케팅은 항상 false */
+  reconsentRequired: z.boolean(),
+});
+export type CustomerConsentState = z.infer<typeof customerConsentStateSchema>;
+
+export const customerConsentsSchema = z.object({
+  terms: customerConsentStateSchema,
+  privacy: customerConsentStateSchema,
+  marketing: customerConsentStateSchema,
+  /** 필수 동의 중 하나라도 현재 버전이 아니면 true */
+  reconsentRequired: z.boolean(),
+});
+export type CustomerConsents = z.infer<typeof customerConsentsSchema>;
+
+/** `GET /v1/customers/{id}/consents` 쿼리 — 최근 순이다 */
+export const customerConsentListQuerySchema = z.object({
+  kind: consentKindSchema.optional().describe("동의 종류 필터. 생략하면 전체"),
+  ...pageQueryShape(),
+});
+
 /** 구매자 상세 — 휴대폰 전체를 보여 준다 */
 export const customerDetailSchema = z.object({
   customerId: z.string(),
@@ -76,6 +145,9 @@ export const customerDetailSchema = z.object({
       }),
     )
     .describe("로그인 방법 — 이메일·비밀번호(`password`)와 연결된 소셜 계정"),
+  consents: customerConsentsSchema.describe(
+    "약관·개인정보·마케팅 동의의 현재 상태. 이력은 `GET /v1/customers/{customerId}/consents`",
+  ),
   addresses: z.array(customerAddressSchema),
   stats: customerStatsSchema.extend({
     canceledOrReturnedCount: z.number().int().describe("취소된 주문 상품 + 완료된 반품 수"),

package/src/schemas/order.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { changeTypeSchema, orderItemStatusSchema, type PageParams, pageSchema } from "./common";
-import { easyPayProviderResponseSchema } from "./payment";
+import { cashReceiptSchema, easyPayProviderResponseSchema } from "./payment";
 
 export const orderSummarySchema = z.object({
   orderId: z.string(),
@@ -40,10 +40,18 @@ export const orderItemSchema = z.object({
   optionId: z.string().nullable(),
   optionName: z.string().nullable(),
   sellerCode: z.string().nullable(),
-  quantity: z.number().int(),
+  quantity: z.number().int().describe("주문 수량"),
+  canceledQuantity: z
+    .number()
+    .int()
+    .describe("취소·반품으로 환불된 누적 수량. 수량 단위 부분 취소가 없었으면 0이다"),
+  activeQuantity: z
+    .number()
+    .int()
+    .describe("살아 있는 수량 (`quantity` − `canceledQuantity`). 0이면 주문상품이 전량 취소됐다"),
   unitPrice: z.number().int(),
   discountAmount: z.number().int(),
-  totalPrice: z.number().int(),
+  totalPrice: z.number().int().describe("주문상품 금액 (할인 반영 단가 × 주문 수량)"),
   hold: z.object({ reason: z.string(), expectedDispatchDate: z.string() }).nullable(),
   autoDecisionDate: z.string().nullable(),
   sellerMemo: z.string().nullable(),
@@ -99,6 +107,13 @@ export const orderSchema = z.object({
     discountAmount: z.number().int(),
     totalAmount: z.number().int(),
     paidAt: z.string().nullable(),
+    cashReceipt: cashReceiptSchema
+      .nullable()
+      .optional()
+      .default(null)
+      .describe(
+        "현금영수증. 구매자가 계좌이체·가상계좌 결제에서 신청했을 때만 있고 그 밖에는 null. 서버는 항상 싣는다",
+      ),
   }),
   testPayment: z
     .boolean()
@@ -193,7 +208,14 @@ export const dispatchRequestSchema = z
     deliveryMethod: deliveryMethodSchema,
     carrierCode: z.string().optional(),
     trackingNumber: z.string().optional(),
-    dispatchedAt: z.string().optional(),
+    /**
+     * 발송 시각. ISO 8601이고 시간대(`Z` 또는 `+09:00`)를 포함해야 한다. 생략하면 현재 시각이다.
+     *
+     * 전에는 `z.string()`이라 아무 문자열이나 그대로 저장됐다. 이 값은 배송 정보 jsonb에 들어가
+     * 자동 배송완료·추적 동기화 잡의 대상 선별 조건이 된다 — 잘못된 한 행이 스토어 구분 없이 도는
+     * 잡 전체를 멈출 수 있어 입력에서 좁혔다. 검증을 통과한 값도 저장 전에 UTC ISO로 정규화한다.
+     */
+    dispatchedAt: z.iso.datetime({ offset: true }).optional(),
   })
   .refine(
     (value) =>
@@ -219,11 +241,65 @@ export const deliveryInfoSchema = z.object({
 
 export type DeliveryInfo = z.infer<typeof deliveryInfoSchema>;
 
+/**
+ * 택배 추적 단계. 응답에서는 문자열로 받는다(값이 추가될 수 있다) — 현재 값은 `ACCEPTED`(접수)·`IN_TRANSIT`(이동 중)·
+ * `OUT_FOR_DELIVERY`(배송 출발)·`DELIVERED`(배송완료)다.
+ */
+export const trackingStageResponseSchema = z.string();
+
 /** `GET /v1/order-items/{orderItemId}/delivery` 응답 — 배송 정보 + 배송 추적 이벤트 */
 export const deliveryStatusSchema = deliveryInfoSchema.extend({
   trackingEvents: z
-    .array(z.object({ status: z.string(), location: z.string(), occurredAt: z.string() }))
-    .optional(),
+    .array(
+      z.object({
+        status: z.string().describe("택배사가 알려 준 처리 내용(예: 집화처리, 배송출발)"),
+        location: z.string().describe("처리 장소. 모르면 빈 문자열"),
+        occurredAt: z.string(),
+        stage: trackingStageResponseSchema
+          .nullable()
+          .optional()
+          .default(null)
+          .describe(
+            "이 이벤트의 추적 단계. 배달 실패처럼 단계로 나눌 수 없는 이벤트는 null. 서버는 항상 싣는다. " +
+              "현재 값은 `ACCEPTED`·`IN_TRANSIT`·`OUT_FOR_DELIVERY`·`DELIVERED`이고 값이 추가될 수 있어 문자열로 받는다",
+          ),
+      }),
+    )
+    .optional()
+    .describe("배송 추적 이력. 시각 오름차순(오래된 것부터)"),
+  tracking: z
+    .object({
+      result: z
+        .string()
+        .nullable()
+        .describe(
+          "마지막 추적 조회 결과. 조회에 성공한 적이 없으면 null. " +
+            "현재 값은 `FOUND`(조회됨)·`NOT_FOUND`(택배사 전산에 송장 없음)·`UNSUPPORTED_CARRIER`(추적을 지원하지 않는 택배사)이고 " +
+            "값이 추가될 수 있어 문자열로 받는다",
+        ),
+      stage: trackingStageResponseSchema
+        .nullable()
+        .describe(
+          "현재 추적 단계. 조회되지 않았으면 null. 현재 값은 `ACCEPTED`·`IN_TRANSIT`·`OUT_FOR_DELIVERY`·`DELIVERED`이고 " +
+            "값이 추가될 수 있어 문자열로 받는다",
+        ),
+      checkedAt: z
+        .string()
+        .nullable()
+        .describe("택배사에서 추적 정보를 마지막으로 받아 온 시각(ISO 8601)"),
+      carrierDeliveredAt: z
+        .string()
+        .nullable()
+        .describe(
+          "택배사가 알려 준 배송완료 시각(ISO 8601). 추적으로 배송완료가 반영되면 주문상품의 `deliveredAt`은 반영 시각이라 이 값과 다를 수 있다",
+        ),
+    })
+    .nullable()
+    .optional()
+    .default(null)
+    .describe(
+      "택배 추적 요약. 택배 발송이 아니거나 추적을 쓰지 않으면 null. 추적이 배송완료면 주문상품이 자동으로 배송완료된다. 서버는 항상 싣는다",
+    ),
 });
 
 export type DeliveryStatus = z.infer<typeof deliveryStatusSchema>;
@@ -256,6 +332,15 @@ export type HoldOrderItemRequest = z.infer<typeof holdOrderItemRequestSchema>;
 export const cancelBySellerRequestSchema = z.object({
   reason: z.enum(["OUT_OF_STOCK", "PRICE_ERROR", "DELIVERY_IMPOSSIBLE", "ETC"]),
   detail: z.string().max(500).optional(),
+  quantity: z
+    .number()
+    .int()
+    .min(1)
+    .optional()
+    .describe(
+      "취소할 수량. 생략하면 남은 수량 전체다. 남은 수량보다 크면 400 `INVALID_QUANTITY`. " +
+        "일부만 취소하면 주문상품은 상태를 유지한 채 `canceledQuantity`가 늘고, 전 수량이 소진되면 `CANCELED`가 된다",
+    ),
 });
 
 export type CancelBySellerRequest = z.infer<typeof cancelBySellerRequestSchema>;
@@ -263,7 +348,22 @@ export type CancelBySellerRequest = z.infer<typeof cancelBySellerRequestSchema>;
 /** `POST /v1/order-items/{orderItemId}/cancel` 응답 — 셀러 직권취소 환불 결과 */
 export const cancelBySellerResultSchema = z.object({
   orderItemId: z.string(),
-  refundAmount: z.number().int(),
+  refundAmount: z
+    .number()
+    .int()
+    .describe("실제 환불한 금액 — 수량 비율 상품 금액 + 배송비 환불 − 조건부 무료배송 미달 차감"),
+  quantity: z.number().int().describe("취소한 수량"),
+  canceledQuantity: z.number().int().describe("취소 후 누적 취소 수량"),
+  deliveryFeeRefundAmount: z
+    .number()
+    .int()
+    .describe(
+      "환불에 포함된 배송비. 배송 묶음(같은 상품)이 모두 취소됐고 환불 정책이 켜져 있을 때만 0보다 크다",
+    ),
+  deliveryFeeChargeAmount: z
+    .number()
+    .int()
+    .describe("조건부 무료배송 기준 미달로 환불액에서 뺀 배송비. 정책이 꺼져 있으면 항상 0이다"),
   refundedAt: z.string(),
 });
 

package/src/schemas/payment.ts

@@ -514,6 +514,57 @@ export const paymentAttemptStatusSchema = z
       "새 값이 추가될 수 있으니 모르는 값은 '진행 중이 아닌 시도'로 다룬다",
   );
 
+/**
+ * 현금영수증 상태 — 값이 추가될 수 있어 응답은 문자열로 받는다. 화면 분기는 이 목록으로 하고 모르는 값은 처리 중으로 다룬다.
+ * - `REQUESTED`: 구매자가 신청했고 결제 승인 전이다
+ * - `PENDING`: 발급·취소를 기다린다(승인 직후, 또는 일시 오류로 자동 재시도 대기)
+ * - `ISSUED`: 발급됐다. 부분 환불이 있었으면 그만큼 취소(또는 재발급)된 금액이다
+ * - `CANCELED`: 전액 환불로 취소됐다
+ * - `FAILED`: 발급·취소가 실패했고 자동 재시도가 끝났다. `failCode`·`failMessage`를 보고 재발급한다
+ * - `SKIPPED`: 발급 대상이 아니다(승인된 결제수단이 계좌이체·가상계좌가 아님)
+ */
+export const CASH_RECEIPT_STATUS_VALUES = [
+  "REQUESTED",
+  "PENDING",
+  "ISSUED",
+  "CANCELED",
+  "FAILED",
+  "SKIPPED",
+] as const;
+export type KnownCashReceiptStatus = (typeof CASH_RECEIPT_STATUS_VALUES)[number];
+
+export const cashReceiptSchema = z.object({
+  cashReceiptId: z.string(),
+  status: z
+    .string()
+    .describe(
+      "상태. `REQUESTED` 결제 전 · `PENDING` 발급 대기 · `ISSUED` 발급 · `CANCELED` 취소 · `FAILED` 실패 · `SKIPPED` 발급 대상 아님. 값이 추가될 수 있다",
+    ),
+  type: z.string().describe("용도. `INCOME_DEDUCTION` 소득공제 · `EXPENSE_PROOF` 지출증빙"),
+  identityType: z
+    .string()
+    .describe("식별 번호 종류. `PHONE` 휴대폰 · `CARD` 현금영수증카드 · `BUSINESS` 사업자등록번호"),
+  identityNumberMasked: z
+    .string()
+    .describe("가린 식별 번호 (예: 010****5678). 원문은 조회할 수 없다"),
+  amount: z
+    .number()
+    .int()
+    .describe("발급해야 할 금액 = 결제 금액 − 환불 완료 금액. 승인 전에는 결제 금액"),
+  issuedAmount: z.number().int().describe("PG에 현재 발급돼 있는 금액. 취소됐거나 발급 전이면 0"),
+  provider: pgProviderSchema.nullable().describe("발급 PG — 결제를 승인한 PG. 승인 전에는 null"),
+  issueNumber: z.string().nullable().describe("현금영수증 승인 번호"),
+  receiptUrl: z.string().nullable().describe("현금영수증 확인 주소"),
+  issuedAt: z.string().nullable().describe("최근 발급 시각 (ISO 8601)"),
+  canceledAt: z.string().nullable().describe("최근 취소 시각 (ISO 8601)"),
+  failCode: z.string().nullable().describe("마지막 실패 코드. 성공하면 비운다"),
+  failMessage: z.string().nullable().describe("마지막 실패 사유"),
+  reissuable: z.boolean().describe("콘솔 재발급으로 다시 시도할 수 있는가 (`FAILED`·`PENDING`)"),
+  requestedAt: z.string().describe("신청 시각 (ISO 8601)"),
+  updatedAt: z.string().describe("마지막 변경 시각 (ISO 8601)"),
+});
+export type CashReceipt = z.infer<typeof cashReceiptSchema>;
+
 export const paymentRecordSchema = z.object({
   paymentId: z.string().describe("결제 건 id. 상세 조회 키"),
   orderId: z.string().nullable().describe("승인돼 만들어진 주문. 승인 전에 끝난 결제는 null"),
@@ -542,6 +593,14 @@ export const paymentRecordSchema = z.object({
   failMessage: z.string().nullable().describe("실패 사유"),
   paidAt: z.string().nullable().describe("승인 시각 (ISO 8601)"),
   createdAt: z.string().describe("결제 시작 시각 (ISO 8601)"),
+  cashReceiptStatus: z
+    .string()
+    .nullable()
+    .optional()
+    .default(null)
+    .describe(
+      "현금영수증 상태(`cashReceiptSchema.status`와 같은 값). 신청이 없으면 null. 서버는 항상 싣는다",
+    ),
 });
 export type PaymentRecord = z.infer<typeof paymentRecordSchema>;
 
@@ -601,6 +660,11 @@ export const paymentRecordDetailSchema = paymentRecordSchema.extend({
     .describe("가맹점 식별자 지문 (토스 clientKey, 포트원 Store ID). 비밀 값은 없다"),
   attempts: z.array(paymentAttemptRecordSchema).describe("시도 이력. 순번 오름차순"),
   refunds: z.array(paymentRefundRecordSchema).describe("환불 이력. 실패한 요청도 남는다"),
+  cashReceipt: cashReceiptSchema
+    .nullable()
+    .optional()
+    .default(null)
+    .describe("현금영수증. 구매자가 신청하지 않았으면 null. 서버는 항상 싣는다"),
 });
 export type PaymentRecordDetail = z.infer<typeof paymentRecordDetailSchema>;
 

package/src/schemas/product.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { type PageParams, pageQueryShape } from "./common";
+import { refundPolicyPatchSchema } from "./refund-policy";
 import { UPLOAD_PURPOSE_LIMITS, uploadExtensionOf } from "./upload";
 
 export const productStatusSchema = z.enum(["SALE", "SUSPENDED", "OUT_OF_STOCK", "CLOSED"]);
@@ -90,6 +91,10 @@ export const productSchema = productSummarySchema.extend({
   conditionalFreeAmount: z.number().int().nullable().optional(),
   returnFee: z.number().int().optional(),
   exchangeFee: z.number().int().optional(),
+  refundPolicy: refundPolicyPatchSchema
+    .nullable()
+    .optional()
+    .describe("상품별 환불 정책 덮어쓰기. null이면 스토어 기본 환불 정책을 쓴다"),
   shippingAddressId: z.string().nullable().optional(),
   returnAddressId: z.string().nullable().optional(),
   createdAt: z.string().optional(),
@@ -252,6 +257,30 @@ export const variantStockSchema = z.object({
 
 export type VariantStock = z.infer<typeof variantStockSchema>;
 
+/**
+ * 출고지·반품지 지정 문구 — POST·PUT·PATCH가 같은 규칙을 쓰므로 설명도 한 곳이다 (이슈 #30).
+ *
+ * 세 값이 뜻이 다르다. **생략**은 「정하지 않음」이라 서버가 그 시점 스토어 기본 주소를 박아 저장하고,
+ * **null**은 「스토어 기본을 따른다」는 명시적 비우기다. 주소록 항목은 상품이 참조 중이면 지울 수 없어
+ * (`409 ADDRESS_IN_USE`) 참조를 푸는 수단이 필요한데, 생략을 기본값으로 되채우면 기본 주소는 영원히
+ * 풀리지 않는다 — null이 그 경로다. 배송 묶음 판정은 null을 그 시점 스토어 기본 출고지로 정규화하므로
+ * 두 표현이 배송비를 갈라놓지 않는다.
+ */
+const ADDRESS_DESCRIPTIONS = {
+  shipping:
+    "출고지 주소 id(`GET /v1/seller-addresses?type=SHIPPING`). 생략하면 스토어 기본 출고지를 저장하고, " +
+    "`null`이면 비워 둔다(스토어 기본 출고지를 따른다). 이 스토어의 `SHIPPING` 주소가 아니면 거부한다",
+  return:
+    "반품지 주소 id(`GET /v1/seller-addresses?type=RETURN`). 생략하면 스토어 기본 반품지를 저장하고, " +
+    "`null`이면 비워 둔다(스토어 기본 반품지를 따른다). 이 스토어의 `RETURN` 주소가 아니면 거부한다",
+  patchShipping:
+    "출고지 주소 id. **생략은 바꾸지 않음**이고 `null`은 비우기다(스토어 기본 출고지를 따른다). " +
+    "이 스토어의 `SHIPPING` 주소가 아니면 거부한다",
+  patchReturn:
+    "반품지 주소 id. **생략은 바꾸지 않음**이고 `null`은 비우기다(스토어 기본 반품지를 따른다). " +
+    "이 스토어의 `RETURN` 주소가 아니면 거부한다",
+} as const;
+
 export const productCreateRequestSchema = z
   .object({
     name: z.string().min(1).max(100),
@@ -279,16 +308,38 @@ export const productCreateRequestSchema = z
     deliveryType: deliveryTypeSchema
       .default("PAID")
       .describe("배송비 유형. FREE 무료, PAID 유료, CONDITIONAL_FREE 조건부 무료"),
-    deliveryFee: z.number().int().default(0).describe("배송비. 원 단위"),
+    deliveryFee: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe(
+        "배송비. 원 단위. **생략하면 스토어 기본 배송비**(`GET /v1/store`의 `shippingPolicy.baseDeliveryFee`)를 쓴다. " +
+          "`deliveryType`이 FREE면 0으로 저장한다",
+      ),
     conditionalFreeAmount: z
       .number()
       .int()
       .optional()
       .describe("CONDITIONAL_FREE일 때 무료 배송이 되는 주문 금액. 원 단위"),
-    returnFee: z.number().int().default(0).describe("반품 배송비. 원 단위"),
-    exchangeFee: z.number().int().default(0).describe("교환 배송비. 원 단위"),
-    shippingAddressId: z.string().optional(),
-    returnAddressId: z.string().optional(),
+    returnFee: z
+      .number()
+      .int()
+      .default(0)
+      .describe("반품 배송비. 원 단위. `refundPolicy.returnDeliveryFee`와 같은 값이다"),
+    exchangeFee: z
+      .number()
+      .int()
+      .default(0)
+      .describe("교환 배송비. 원 단위. `refundPolicy.exchangeDeliveryFee`와 같은 값이다"),
+    refundPolicy: refundPolicyPatchSchema
+      .nullish()
+      .describe(
+        "상품별 환불 정책 — 준 항목만 스토어 기본을 덮어쓴다. `null`이나 생략은 스토어 기본을 그대로 쓴다는 뜻이다. " +
+          "`returnDeliveryFee`·`exchangeDeliveryFee`를 주면 `returnFee`·`exchangeFee`도 같은 값으로 맞춘다",
+      ),
+    shippingAddressId: z.string().nullable().optional().describe(ADDRESS_DESCRIPTIONS.shipping),
+    returnAddressId: z.string().nullable().optional().describe(ADDRESS_DESCRIPTIONS.return),
   })
   .extend(optionModelRequestSchema.shape);
 
@@ -300,6 +351,13 @@ export const productPatchRequestSchema = z
     salePrice: z.number().int().multipleOf(10).optional(),
     status: productStatusSchema.optional(),
     deliveryFee: z.number().int().optional(),
+    // PATCH의 생략은 「바꾸지 않음」이다 — 기본 주소로 되채우지 않는다. 비우려면 `null`을 준다
+    shippingAddressId: z
+      .string()
+      .nullable()
+      .optional()
+      .describe(ADDRESS_DESCRIPTIONS.patchShipping),
+    returnAddressId: z.string().nullable().optional().describe(ADDRESS_DESCRIPTIONS.patchReturn),
   })
   .refine((value) => Object.values(value).some((v) => v !== undefined), {
     message: "최소 1개 필드가 필요합니다",