@sayren/store-sdk 0.16.0 → 0.18.0

package/src/schemas/refund-policy.ts

@@ -16,17 +16,18 @@ const descriptions = {
     "발송 전 취소로 배송 묶음(같은 상품의 주문상품)이 모두 취소되면 그 묶음의 배송비를 환불한다. " +
     "false면 배송비를 환불하지 않는다. 기본 true",
   returnDeliveryFee:
-    "단순 변심(구매자 귀책) 반품의 반품 배송비. 원 단위. 환불액에서 뺀다. 기본 0(무료). " +
-    "상품별 정책에서 이 값을 주면 상품의 `returnFee`도 같은 값으로 맞춘다",
+    "단순 변심(구매자 귀책) 반품의 반품 배송비. 원 단위. 환불액에서 뺀다. 기본 0(무료). 배송 상품에만 있다",
   exchangeDeliveryFee:
-    "단순 변심(구매자 귀책) 교환의 교환 배송비. 원 단위. 구매자에게 청구할 금액을 안내값으로 싣는다. 기본 0(무료). " +
-    "상품별 정책에서 이 값을 주면 상품의 `exchangeFee`도 같은 값으로 맞춘다",
+    "단순 변심(구매자 귀책) 교환의 교환 배송비. 원 단위. 구매자에게 청구할 금액을 안내값으로 싣는다. 기본 0(무료). 배송 상품에만 있다",
   sellerFaultFreeShipping:
     "판매자 귀책(셀러 직권취소, 불량·오배송 반품)이면 배송비를 셀러가 부담한다 — 배송비를 환불하고 반품비를 받지 않는다. " +
     "false면 구매자 귀책과 같은 규칙을 쓴다. 기본 true",
   conditionalFreeShortfallCharge:
     "조건부 무료배송(`CONDITIONAL_FREE`) 상품에서 일부 취소로 남은 금액이 무료 기준액에 미달하면 그 배송비를 환불액에서 뺀다. " +
     "false면 추가 청구 없이 셀러가 부담한다. 기본 false",
+  couponShortfallCharge:
+    "쿠폰 조건 미달 차감. 일부 취소·반품으로 남은 주문상품이 쿠폰 조건(최소 주문 금액 등)을 잃으면 남은 주문상품이 받던 쿠폰 할인을 환불액에서 뺀다. " +
+    "판매자 귀책(셀러 직권취소, 불량·오배송 반품)은 빼지 않는다. false면 차감 없이 실결제 금액만 나눠 환불한다. 기본 true",
 } as const;
 
 /** 유효 환불 정책 — 스토어 기본 + 상품별 덮어쓰기를 합친 결과 */
@@ -36,6 +37,13 @@ export const refundPolicySchema = z.object({
   exchangeDeliveryFee: z.number().int().min(0).describe(descriptions.exchangeDeliveryFee),
   sellerFaultFreeShipping: z.boolean().describe(descriptions.sellerFaultFreeShipping),
   conditionalFreeShortfallCharge: z.boolean().describe(descriptions.conditionalFreeShortfallCharge),
+  couponShortfallCharge: z
+    .boolean()
+    .optional()
+    .default(true)
+    .describe(
+      `${descriptions.couponShortfallCharge}. 이 필드가 없는 이전 서버 응답은 true로 읽는다`,
+    ),
 });
 
 export type RefundPolicy = z.infer<typeof refundPolicySchema>;
@@ -52,6 +60,7 @@ export const REFUND_POLICY_DEFAULTS: RefundPolicy = {
   exchangeDeliveryFee: 0,
   sellerFaultFreeShipping: true,
   conditionalFreeShortfallCharge: false,
+  couponShortfallCharge: true,
 };
 
 /**
@@ -77,27 +86,30 @@ export const refundPolicyPatchSchema = z.strictObject({
     .boolean()
     .optional()
     .describe(descriptions.conditionalFreeShortfallCharge),
+  couponShortfallCharge: z.boolean().optional().describe(descriptions.couponShortfallCharge),
 });
 
 export type RefundPolicyPatch = z.infer<typeof refundPolicyPatchSchema>;
 
-/** 정책 해석에 쓰는 상품 값 — 상품별 덮어쓰기와 레거시 배송비 필드 */
+/**
+ * 상품별 덮어쓰기 — 쿠폰 조건 미달 차감(`couponShortfallCharge`)은 주문 단위 규칙이라 상품이 정하지 않는다.
+ * 스토어 정책만 읽는다(이슈 #47).
+ */
+export const productRefundPolicyPatchSchema = refundPolicyPatchSchema.omit({
+  couponShortfallCharge: true,
+});
+
+/** 정책 해석에 쓰는 상품 값 — 상품별 덮어쓰기 */
 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)이 스토어 기본을 물려받게 하는 규칙이다.
+ * 반품·교환 배송비의 원천은 정책 하나다(이슈 #57 결정 3). 상품의 레거시 반품비·교환비 필드와의 연결은 없앴고,
+ * 레거시 값은 마이그레이션이 상품별 정책으로 옮겼다.
  */
 export function resolveRefundPolicy(
   storePolicy?: RefundPolicyPatch | null,
@@ -108,28 +120,27 @@ export function resolveRefundPolicy(
 }
 
 /**
- * 상품의 **덮어쓰기 자체** — 레거시 반품비·교환비를 같은 형태로 승격한 값이다. 덮어쓰기가 없으면 null.
+ * 상품의 **덮어쓰기 자체** — 덮어쓰기가 없으면 null.
  *
  * `resolveRefundPolicy`가 합친 결과로는 "상품이 정한 값"과 "스토어 기본을 물려받은 값"을 가를 수 없다.
  * 관리 API 응답의 `refundPolicy`와 콘솔 폼의 덮어쓰기 스위치가 이 함수를 원천으로 쓴다 — 가르지 못하면
- * 스토어 기본을 쓰는 상품을 저장할 때 그 순간의 기본값이 상품에 박히거나, 레거시 값이 조용히 사라진다.
+ * 스토어 기본을 쓰는 상품을 저장할 때 그 순간의 기본값이 상품에 박힌다.
  */
 export function productRefundPolicyOverride(
   product?: RefundPolicyProductInput | null,
 ): RefundPolicyPatch | null {
-  const override = dropUndefined(product?.refundPolicy);
-  const legacy: RefundPolicyPatch = {};
-  if (override.returnDeliveryFee === undefined && (product?.returnFee ?? 0) > 0) {
-    legacy.returnDeliveryFee = product?.returnFee ?? 0;
-  }
-  if (override.exchangeDeliveryFee === undefined && (product?.exchangeFee ?? 0) > 0) {
-    legacy.exchangeDeliveryFee = product?.exchangeFee ?? 0;
-  }
-  const merged = { ...legacy, ...override };
-  if (product?.refundPolicy == null && Object.keys(merged).length === 0) return null;
-  return merged;
+  if (product?.refundPolicy == null) return null;
+  // 쿠폰 조건 미달 차감은 주문 단위라 스토어만 정한다 — 상품 행에 키가 있어도 덮어쓰기로 읽지 않는다(이슈 #47)
+  const { couponShortfallCharge: _storeOnly, ...override } = dropUndefined(product.refundPolicy);
+  return override;
 }
 
+/** 반품·교환 배송비 키 — 배송이 없는 상품의 정책에는 두지 않는다 */
+export const REFUND_POLICY_DELIVERY_FEE_KEYS = [
+  "returnDeliveryFee",
+  "exchangeDeliveryFee",
+] as const;
+
 /** `undefined` 값을 빼고 얕게 복사한다 — 전개 순서로 덮어쓸 때 `undefined`가 기본값을 지우지 않게 */
 function dropUndefined(patch?: RefundPolicyPatch | null): RefundPolicyPatch {
   if (!patch) return {};
@@ -143,7 +154,8 @@ function dropUndefined(patch?: RefundPolicyPatch | null): RefundPolicyPatch {
  *
  * 원 단위 반올림 규칙: `floor(주문상품 금액 × 누적 수량 ÷ 전체 수량)`을 두 번 구해 그 차를 쓴다.
  * 부분 취소를 몇 번 나눠도 합이 주문상품 금액과 정확히 같아서 1원이 남거나 넘치지 않는다.
- * 할인은 이미 단가에 들어 있어(주문 단위 쿠폰이 없다) 별도 안분이 없다.
+ * 즉시할인은 이미 단가에 들어 있다. 쿠폰 할인은 단가에 들어가지 않으므로 환불은 실결제 금액을 나누는
+ * `proratedPaidRefundBase`(promotion.ts)를 쓴다(이슈 #47).
  *
  * @param totalPrice 주문상품 금액 (할인 반영 단가 × 전체 수량)
  * @param quantity 주문상품 전체 수량

package/src/schemas/scope.ts

@@ -29,6 +29,7 @@ export const STORE_SCOPE_RESOURCES = {
   member: ["r", "rw"],
   customer: ["r", "rw"],
   audit: ["r"],
+  promotion: ["r", "rw"],
 } as const satisfies Record<string, readonly ScopeAccess[]>;
 
 export type StoreScopeResource = keyof typeof STORE_SCOPE_RESOURCES;
@@ -65,6 +66,7 @@ export const STORE_ROLE_SCOPES = {
     "member:rw",
     "customer:rw",
     "audit:r",
+    "promotion:rw",
   ],
   ADMIN: [
     "product:rw",
@@ -79,6 +81,7 @@ export const STORE_ROLE_SCOPES = {
     "member:rw",
     "customer:rw",
     "audit:r",
+    "promotion:rw",
   ],
   STAFF: [
     "product:rw",
@@ -88,5 +91,6 @@ export const STORE_ROLE_SCOPES = {
     "inquiry:rw",
     "review:rw",
     "customer:r",
+    "promotion:r",
   ],
 } as const satisfies Record<StoreRole, readonly string[]>;

package/src/schemas/shipping-policy.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { DeliveryType } from "./product";
+import { type DeliveryType, type FulfillmentType, requiresShipping } from "./fulfillment";
 
 /**
  * 배송비 규칙 (이슈 #29) — 배송비를 **몇 번, 얼마나** 부과하는지를 정한다.
@@ -19,6 +19,9 @@ import type { DeliveryType } from "./product";
  *
  * 계산은 `quoteDelivery` 하나다. 장바구니·주문서·결제 시작·환불 정산이 모두 이 함수를 쓴다 —
  * 네 곳이 각자 계산하면 화면 금액과 결제 금액이 갈라진다.
+ *
+ * **비실물 줄은 배송 계산에서 빠진다**(이슈 #48, `requiresShipping`). 묶음을 만들지 않고, 스토어 전체 무료 기준의
+ * 판정 금액(`shippableAmount`)에도 넣지 않는다 — 디지털 상품 금액이 실물 배송비를 면제시키지 않게 한다.
  */
 
 const descriptions = {
@@ -219,6 +222,11 @@ export interface DeliveryBundleProduct {
   conditionalFreeAmount: number | null;
   /** 출고지 주소 id(`seller_addresses`). null이면 스토어 기본 출고지를 쓰는 상품끼리 한 묶음이다 */
   shippingAddressId?: string | null;
+  /**
+   * 상품 유형 (이슈 #48). 생략·null이면 배송 상품이다. 배송이 필요 없는 유형은 묶음을 만들지 않는다.
+   * 줄(`DeliveryFeeLine.fulfillmentType`)에 값이 있으면 그 값이 이긴다.
+   */
+  fulfillmentType?: FulfillmentType | null;
 }
 
 /**
@@ -246,6 +254,11 @@ export interface DeliveryFeeLine {
   productId: string;
   /** 상품 금액 (할인 반영 단가 × 수량) */
   amount: number;
+  /**
+   * 이 줄의 상품 유형 — 주문서 스냅샷 값이다(이슈 #48). 주면 상품의 현재 유형보다 우선한다. 주문서를 만든 뒤 셀러가
+   * 유형을 바꿔도 결제 시작의 견적과 주문상품 스냅샷이 같은 유형을 보게 한다. 생략하면 상품 값을 쓴다.
+   */
+  fulfillmentType?: FulfillmentType | null;
 }
 
 /**
@@ -290,6 +303,13 @@ export interface DeliveryQuote {
   remoteArea: RemoteArea;
   /** 스토어 전체 무료 기준(`freeThreshold`) 충족으로 기본 배송비를 면제했는가 */
   freeByThreshold: boolean;
+  /**
+   * 배송이 필요한 줄의 상품 금액 합 — 스토어 전체 무료 기준의 판정 금액이다(이슈 #48). 비실물 줄은 빠진다.
+   * 주문 상품 금액 합(`productAmount`)과 다를 수 있다.
+   */
+  shippableAmount: number;
+  /** 배송이 필요한 줄이 하나라도 있는가 — 배송 묶음이 하나라도 있는가다. false면 배송지를 받지 않는다 */
+  requiresShipping: boolean;
 }
 
 export interface DeliveryQuoteInput {
@@ -319,11 +339,13 @@ export function quoteDelivery(input: DeliveryQuoteInput): DeliveryQuote {
     string,
     { product: DeliveryBundleProduct; ids: Set<string>; sum: number }
   >();
-  let productAmount = 0;
+  let shippableAmount = 0;
   for (const line of input.lines) {
     const product = input.productOf(line.productId);
     if (!product) continue;
-    productAmount += line.amount;
+    // 비실물은 묶음도 무료 기준 판정 금액도 만들지 않는다 — 디지털 금액이 실물 배송비를 면제시키지 않게 한다
+    if (!requiresShipping(line.fulfillmentType ?? product.fulfillmentType)) continue;
+    shippableAmount += line.amount;
     const key = deliveryBundleKeyOf(product);
     const group = groups.get(key) ?? { product, ids: new Set<string>(), sum: 0 };
     group.ids.add(line.productId);
@@ -332,7 +354,7 @@ export function quoteDelivery(input: DeliveryQuoteInput): DeliveryQuote {
   }
 
   const freeByThreshold =
-    policy.freeThreshold !== null && productAmount >= policy.freeThreshold && groups.size > 0;
+    policy.freeThreshold !== null && shippableAmount >= policy.freeThreshold && groups.size > 0;
 
   const bundles: DeliveryBundleQuote[] = [];
   for (const [bundleKey, group] of groups) {
@@ -371,5 +393,7 @@ export function quoteDelivery(input: DeliveryQuoteInput): DeliveryQuote {
     deliveryFee: baseFee + remoteSurcharge,
     remoteArea: area,
     freeByThreshold,
+    shippableAmount,
+    requiresShipping: bundles.length > 0,
   };
 }

package/src/schemas/store.ts

@@ -166,6 +166,22 @@ export const updateStoreRequestSchema = z
         "비회원 주문 허용. false(회원만)면 로그인하지 않은 구매자의 주문서 생성·결제 요청이 403 `GUEST_CHECKOUT_DISABLED`다. " +
           "장바구니 담기와 이미 받은 비회원 주문의 조회·취소는 막지 않는다",
       ),
+    fulfillmentMailEnabled: z
+      .boolean()
+      .optional()
+      .describe(
+        "비실물 상품 제공 안내 메일(이슈 #48). 켜면(기본) 제공이 끝났을 때 구매자에게 안내 메일을 보낸다. 코드·파일 주소는 싣지 않는다",
+      ),
+    withdrawalNotice: z
+      .string()
+      .trim()
+      .min(1)
+      .max(1000)
+      .nullable()
+      .optional()
+      .describe(
+        "청약철회 제한 고지 문구(이슈 #48). 제한 상품이 있는 주문서에 보인다. null이면 플랫폼 기본 문구를 쓴다",
+      ),
     autoDeliverDays: z
       .number()
       .int()
@@ -231,6 +247,17 @@ export const storeSchema = z.object({
       "스토어프론트 도메인 — 소셜 로그인 리디렉트와 방문 분석 수집이 함께 쓴다(`analyticsAllowedOrigins`와 같은 값)",
     ),
   guestCheckoutEnabled: z.boolean().describe("비회원 주문 허용. false면 회원만 주문할 수 있다"),
+  fulfillmentMailEnabled: z
+    .boolean()
+    .optional()
+    .default(true)
+    .describe("비실물 상품 제공 안내 메일(이슈 #48). 서버는 항상 싣는다"),
+  withdrawalNotice: z
+    .string()
+    .nullable()
+    .optional()
+    .default(null)
+    .describe("청약철회 제한 고지 문구(이슈 #48). null이면 플랫폼 기본 문구다. 서버는 항상 싣는다"),
   autoDeliverDays: z.number().int().describe(autoDeliverDaysDescription),
   autoConfirmDays: z.number().int().describe(autoConfirmDaysDescription),
   refundPolicy: refundPolicySchema.describe(
@@ -333,7 +360,11 @@ export const storeMemberRoleUpdatedSchema = z.object({
 
 export type StoreMemberRoleUpdated = z.infer<typeof storeMemberRoleUpdatedSchema>;
 
-export const addressTypeSchema = z.enum(["SHIPPING", "RETURN"]);
+/**
+ * 주소 유형 — 출고지·반품지·방문 수령지(이슈 #48). 방문 수령지(`PICKUP`)는 목록에서 `type=PICKUP`으로 조회할 때만 나온다
+ * (이 값을 모르는 옛 SDK의 목록 파싱이 깨지지 않게).
+ */
+export const addressTypeSchema = z.enum(["SHIPPING", "RETURN", "PICKUP"]);
 
 export type AddressType = z.infer<typeof addressTypeSchema>;
 

package/src/schemas/upload.ts

@@ -5,8 +5,10 @@ import { z } from "zod";
  *
  * - `product-image`: 상품 목록·상세의 상품 이미지. 목록 썸네일로 쓰이므로 정지 이미지만 받는다.
  * - `description`: 상세설명 본문에 삽입하는 미디어. 동영상과 svg도 받는다.
+ * - `digital-asset`: 파일 다운로드 상품의 판매 파일(이슈 #48). **비공개 객체**로 올라가고 공개 주소가 없다 — 구매자는 제공된
+ *   주문상품에서 수명 300초의 서명 주소로만 받는다.
  */
-export const uploadPurposeSchema = z.enum(["product-image", "description"]);
+export const uploadPurposeSchema = z.enum(["product-image", "description", "digital-asset"]);
 
 export type UploadPurpose = z.infer<typeof uploadPurposeSchema>;
 
@@ -34,6 +36,37 @@ export const UPLOAD_PURPOSE_LIMITS: Record<UploadPurpose, UploadPurposeLimit> =
     extensions: ["jpg", "jpeg", "png", "gif", "webp", "avif", "svg", "mp4", "webm", "mov"],
     maxBytes: 50 * MB,
   },
+  // 판매 파일 — 실행 파일(exe·dmg 등)은 받지 않는다. 크기 상한은 CDN 업로드 한도 안으로 잡는다
+  "digital-asset": {
+    extensions: [
+      "pdf",
+      "epub",
+      "zip",
+      "mp3",
+      "wav",
+      "flac",
+      "m4a",
+      "mp4",
+      "mov",
+      "jpg",
+      "jpeg",
+      "png",
+      "webp",
+      "psd",
+      "ai",
+      "txt",
+      "csv",
+      "xlsx",
+      "docx",
+      "pptx",
+    ],
+    maxBytes: 200 * MB,
+  },
+};
+
+/** 비공개 업로드(판매 파일)의 PUT 필수 헤더 — CDN이 이 값으로 공개 조회를 막는다 */
+export const PRIVATE_UPLOAD_HEADERS: Readonly<Record<string, string>> = {
+  "x-amz-meta-visibility": "private",
 };
 
 /** 파일명의 소문자 확장자. 확장자가 없으면 `""` */
@@ -100,10 +133,23 @@ export const uploadRequestSchema = z.object({
 export type UploadRequest = z.infer<typeof uploadRequestSchema>;
 
 export const uploadTicketSchema = z.object({
-  /** 업로드 완료 후 공개될 주소 */
+  /** 업로드 완료 후 공개될 주소. 비공개 업로드(`digital-asset`)는 이 주소로 받을 수 없다 */
   url: z.url(),
   /** 파일 바이트를 PUT할 presigned URL. 1시간 유효 */
   uploadUrl: z.url(),
+  key: z
+    .string()
+    .optional()
+    .describe(
+      "객체 키. 비공개 업로드(`digital-asset`)는 이 값으로 상품에 파일을 연결한다(`POST /v1/products/{productId}/digital-assets`). 공개 업로드에는 없다",
+    ),
+  headers: z
+    .record(z.string(), z.string())
+    .optional()
+    .default({})
+    .describe(
+      "PUT에 반드시 실을 헤더. 비공개 업로드는 `x-amz-meta-visibility: private`이고 빠뜨리면 공개 객체가 된다. 공개 업로드는 빈 객체다",
+    ),
 });
 
 export type UploadTicket = z.infer<typeof uploadTicketSchema>;

package/src/schemas/webhook-event.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { claimStatusSchema, claimTypeSchema } from "./claim";
 import { orderItemStatusSchema } from "./common";
+import { orderItemFulfillmentSnapshotResponseSchema } from "./fulfillment";
 
 /**
  * 웹훅 발송 형식 (공개 계약). 본문은 얇은 이벤트다. 개인정보를 싣지 않으며
@@ -23,6 +24,14 @@ const envelopeFields = {
   id: z.string().describe("이벤트 ID (`evt_…`, 테스트 전송은 `evt_test_…`). 중복 제거 키"),
   createdAt: z.string().describe("이벤트 발생 일시 (ISO 8601)"),
   storeId: z.string().describe("이벤트가 발생한 스토어 ID"),
+  sequence: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe(
+      "리소스별 순번. 같은 주문·클레임·문의·리뷰·상품의 이벤트마다 1씩 커진다. 도착 순서는 보장하지 않으므로 같은 리소스의 이벤트는 이 값으로 정렬한다. 이 필드가 생기기 전의 이벤트와 테스트 전송에는 없다",
+    ),
 };
 
 export const orderWebhookEventDataSchema = z.object({
@@ -35,9 +44,59 @@ export const orderWebhookEventDataSchema = z.object({
     .describe(
       "테스트 결제(샌드박스 결제) 주문인가. true면 실제로 돈이 오가지 않았다. 이 필드가 없는 이전 이벤트는 false로 읽는다",
     ),
+  couponDiscountAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe(
+      "주문이 받은 상품·주문 쿠폰 할인 합계 (원). 즉시할인(`discountAmount`)과 별개다. " +
+        "쿠폰이 없거나 이 필드가 없는 이전 이벤트는 0으로 읽는다",
+    ),
+  orderItemId: z
+    .string()
+    .optional()
+    .describe(
+      "이벤트를 만든 주문상품 ID. 비실물 상품 제공으로 보내는 `ORDER.DELIVERED`에만 실린다. " +
+        "택배 배송완료와 그 밖의 주문 이벤트에는 없다",
+    ),
+  fulfillmentSnapshot: orderItemFulfillmentSnapshotResponseSchema
+    .optional()
+    .describe(
+      "이벤트를 만든 주문상품의 주문 시점 이행 스냅샷(주문상품 응답의 `fulfillmentSnapshot`과 같다, 이슈 #57). " +
+        "비실물 상품의 제공 완료는 `ORDER.DELIVERED`로도 오고 `type`이 `SHIPPING`이 아니다. `orderItemId`가 있는 이벤트에만 실린다",
+    ),
 });
 export type OrderWebhookEventData = z.infer<typeof orderWebhookEventDataSchema>;
 
+/**
+ * `ORDER.FULFILLED` — 비실물 주문상품(파일·코드·이용권·방문 수령)을 제공했다(이슈 #48). 자동 제공은 결제 확정과 함께,
+ * 수동 제공은 셀러의 제공 처리(`POST /v1/order-items/{orderItemId}/fulfill`)로 온다. 기존 구독자를 위해 같은 순간
+ * `ORDER.DELIVERED`도 함께 보낸다. **코드·파일 주소는 싣지 않는다** — 관리 API로 조회한다.
+ */
+export const orderFulfilledWebhookEventDataSchema = z.object({
+  orderId: z.string().describe("주문 ID"),
+  orderItemId: z.string().describe("제공한 주문상품 ID"),
+  status: orderItemStatusSchema.describe("이벤트 발생 시점의 주문 대표 상태"),
+  fulfillmentSnapshot: orderItemFulfillmentSnapshotResponseSchema.describe(
+    "제공한 주문상품의 주문 시점 이행 스냅샷(주문상품 응답의 `fulfillmentSnapshot`과 같다, 이슈 #57)",
+  ),
+  fulfillment: z
+    .object({
+      mode: z
+        .string()
+        .describe(
+          "실제 제공 방식. `AUTO`(결제 확정과 함께)·`MANUAL`(셀러 제공 처리). 주문상품 제공 기록의 `mode`와 같다",
+        ),
+    })
+    .describe("제공 기록"),
+  fulfilledAt: z.string().describe("제공 시각 (ISO 8601). 주문상품의 `deliveredAt`과 같다"),
+  testPayment: z
+    .boolean()
+    .describe("테스트 결제(샌드박스 결제) 주문인가. true면 실제로 돈이 오가지 않았다"),
+});
+export type OrderFulfilledWebhookEventData = z.infer<typeof orderFulfilledWebhookEventDataSchema>;
+
 /**
  * `ORDER.CANCELED` — 셀러 직권취소(`POST /v1/order-items/{orderItemId}/cancel`)로 주문상품이 취소됐다.
  * 수량 단위 부분 취소도 이 이벤트다(`quantity` < 주문 수량이면 주문상품 상태가 그대로다).
@@ -64,7 +123,8 @@ export const orderCanceledWebhookEventDataSchema = z.object({
     .number()
     .int()
     .describe(
-      "환불액 (원). 수량 비율 상품 금액 + 배송비 환불 − 조건부 무료배송 미달 차감이다. " +
+      "환불액 (원). 수량 비율 상품 실결제 금액(쿠폰 배분을 뺀 금액) + 배송비 환불 − 조건부 무료배송 미달 차감 " +
+        "+ 되돌린 쿠폰 차감(`couponChargeRefundAmount`)이다. " +
         "결제사 환불 결과는 결제 내역(`GET /v1/payments/{paymentId}`)으로 확인한다",
     ),
   deliveryFeeRefundAmount: z.number().int().describe("환불액에 포함된 배송비 (원)"),
@@ -72,6 +132,23 @@ export const orderCanceledWebhookEventDataSchema = z.object({
     .number()
     .int()
     .describe("환불액에서 뺀 배송비 (원) — 조건부 무료배송 기준 미달 차감"),
+  couponChargeAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe(
+      "환불액에서 뺀 쿠폰 조건 미달 차감 (원). 판매자 취소는 차감하지 않으므로 늘 0이다. 이 필드가 없는 이전 이벤트는 0으로 읽는다",
+    ),
+  couponChargeRefundAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe(
+      "환불액에 더한 금액 (원) — 앞선 환불에서 뺀 쿠폰 조건 미달 차감을 되돌린 몫이다. " +
+        "전량 취소면 누적 차감이 모두 되돌아간다. 이 필드가 없는 이전 이벤트는 0으로 읽는다",
+    ),
   testPayment: z
     .boolean()
     .describe("테스트 결제(샌드박스 결제) 주문인가. true면 실제로 돈이 오가지 않았다"),
@@ -124,6 +201,25 @@ export const claimWebhookEventDataSchema = z.object({
       "환불액에서 뺀 추가 차감 (원) — 셀러가 클레임 승인에 넣은 금액이다(상품 훼손 등). " +
         "배송비 차감과 별개이므로 `deliveryFeeChargeAmount`와 더해서 뺀다. 접수 이벤트와 이 필드가 없는 이전 이벤트는 0이다",
     ),
+  couponChargeAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe(
+      "환불액에서 뺀 쿠폰 조건 미달 차감 (원) — 일부 취소·반품으로 남은 주문상품이 쿠폰 조건(최소 주문 금액 등)을 " +
+        "잃어 남은 주문상품이 받던 할인을 뺀 금액이다. 배송비 차감·추가 차감과 별개다. 접수 이벤트는 예상값이다. " +
+        "이 필드가 없는 이전 이벤트는 0으로 읽는다",
+    ),
+  couponChargeRefundAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe(
+      "환불액에 더한 금액 (원) — 앞선 환불에서 뺀 쿠폰 조건 미달 차감을 되돌린 몫이다. 접수 이벤트는 예상값이다. " +
+        "이 필드가 없는 이전 이벤트는 0으로 읽는다",
+    ),
   testPayment: z
     .boolean()
     .optional()
@@ -171,6 +267,12 @@ export const orderWebhookEventSchema = z.object({
   data: orderWebhookEventDataSchema,
 });
 
+export const orderFulfilledWebhookEventSchema = z.object({
+  ...envelopeFields,
+  type: z.literal("ORDER.FULFILLED"),
+  data: orderFulfilledWebhookEventDataSchema,
+});
+
 export const orderCanceledWebhookEventSchema = z.object({
   ...envelopeFields,
   type: z.literal("ORDER.CANCELED"),
@@ -210,6 +312,7 @@ export const productOutOfStockWebhookEventSchema = z.object({
 export const webhookEventSchema = z
   .discriminatedUnion("type", [
     orderWebhookEventSchema,
+    orderFulfilledWebhookEventSchema,
     orderCanceledWebhookEventSchema,
     claimWebhookEventSchema,
     inquiryWebhookEventSchema,