@sayren/store-sdk 0.16.0 → 0.17.0

package/src/schemas/refund-policy.ts

@@ -27,6 +27,9 @@ const descriptions = {
   conditionalFreeShortfallCharge:
     "조건부 무료배송(`CONDITIONAL_FREE`) 상품에서 일부 취소로 남은 금액이 무료 기준액에 미달하면 그 배송비를 환불액에서 뺀다. " +
     "false면 추가 청구 없이 셀러가 부담한다. 기본 false",
+  couponShortfallCharge:
+    "쿠폰 조건 미달 차감. 일부 취소·반품으로 남은 주문상품이 쿠폰 조건(최소 주문 금액 등)을 잃으면 남은 주문상품이 받던 쿠폰 할인을 환불액에서 뺀다. " +
+    "판매자 귀책(셀러 직권취소, 불량·오배송 반품)은 빼지 않는다. false면 차감 없이 실결제 금액만 나눠 환불한다. 기본 true",
 } as const;
 
 /** 유효 환불 정책 — 스토어 기본 + 상품별 덮어쓰기를 합친 결과 */
@@ -36,6 +39,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 +62,7 @@ export const REFUND_POLICY_DEFAULTS: RefundPolicy = {
   exchangeDeliveryFee: 0,
   sellerFaultFreeShipping: true,
   conditionalFreeShortfallCharge: false,
+  couponShortfallCharge: true,
 };
 
 /**
@@ -77,10 +88,19 @@ 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 {
   /** 상품별 덮어쓰기. 없으면 스토어 기본을 그대로 쓴다 */
@@ -117,7 +137,8 @@ export function resolveRefundPolicy(
 export function productRefundPolicyOverride(
   product?: RefundPolicyProductInput | null,
 ): RefundPolicyPatch | null {
-  const override = dropUndefined(product?.refundPolicy);
+  // 쿠폰 조건 미달 차감은 주문 단위라 스토어만 정한다 — 상품 행에 키가 있어도 덮어쓰기로 읽지 않는다(이슈 #47)
+  const { couponShortfallCharge: _storeOnly, ...override } = dropUndefined(product?.refundPolicy);
   const legacy: RefundPolicyPatch = {};
   if (override.returnDeliveryFee === undefined && (product?.returnFee ?? 0) > 0) {
     legacy.returnDeliveryFee = product?.returnFee ?? 0;
@@ -143,7 +164,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,4 +1,5 @@
 import { z } from "zod";
+import { type FulfillmentType, requiresShipping } from "./fulfillment";
 import type { DeliveryType } from "./product";
 
 /**
@@ -19,6 +20,9 @@ import type { DeliveryType } from "./product";
  *
  * 계산은 `quoteDelivery` 하나다. 장바구니·주문서·결제 시작·환불 정산이 모두 이 함수를 쓴다 —
  * 네 곳이 각자 계산하면 화면 금액과 결제 금액이 갈라진다.
+ *
+ * **비실물 줄은 배송 계산에서 빠진다**(이슈 #48, `requiresShipping`). 묶음을 만들지 않고, 스토어 전체 무료 기준의
+ * 판정 금액(`shippableAmount`)에도 넣지 않는다 — 디지털 상품 금액이 실물 배송비를 면제시키지 않게 한다.
  */
 
 const descriptions = {
@@ -219,6 +223,11 @@ export interface DeliveryBundleProduct {
   conditionalFreeAmount: number | null;
   /** 출고지 주소 id(`seller_addresses`). null이면 스토어 기본 출고지를 쓰는 상품끼리 한 묶음이다 */
   shippingAddressId?: string | null;
+  /**
+   * 상품 유형 (이슈 #48). 생략·null이면 배송 상품이다. 배송이 필요 없는 유형은 묶음을 만들지 않는다.
+   * 줄(`DeliveryFeeLine.fulfillmentType`)에 값이 있으면 그 값이 이긴다.
+   */
+  fulfillmentType?: FulfillmentType | null;
 }
 
 /**
@@ -246,6 +255,11 @@ export interface DeliveryFeeLine {
   productId: string;
   /** 상품 금액 (할인 반영 단가 × 수량) */
   amount: number;
+  /**
+   * 이 줄의 상품 유형 — 주문서 스냅샷 값이다(이슈 #48). 주면 상품의 현재 유형보다 우선한다. 주문서를 만든 뒤 셀러가
+   * 유형을 바꿔도 결제 시작의 견적과 주문상품 스냅샷이 같은 유형을 보게 한다. 생략하면 상품 값을 쓴다.
+   */
+  fulfillmentType?: FulfillmentType | null;
 }
 
 /**
@@ -290,6 +304,13 @@ export interface DeliveryQuote {
   remoteArea: RemoteArea;
   /** 스토어 전체 무료 기준(`freeThreshold`) 충족으로 기본 배송비를 면제했는가 */
   freeByThreshold: boolean;
+  /**
+   * 배송이 필요한 줄의 상품 금액 합 — 스토어 전체 무료 기준의 판정 금액이다(이슈 #48). 비실물 줄은 빠진다.
+   * 주문 상품 금액 합(`productAmount`)과 다를 수 있다.
+   */
+  shippableAmount: number;
+  /** 배송이 필요한 줄이 하나라도 있는가 — 배송 묶음이 하나라도 있는가다. false면 배송지를 받지 않는다 */
+  requiresShipping: boolean;
 }
 
 export interface DeliveryQuoteInput {
@@ -319,11 +340,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 +355,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 +394,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

@@ -23,6 +23,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 +43,58 @@ 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`에만 실린다. " +
+        "택배 배송완료와 그 밖의 주문 이벤트에는 없다",
+    ),
+  fulfillmentType: z
+    .string()
+    .optional()
+    .describe(
+      "이벤트를 만든 주문상품의 상품 유형. 비실물 상품의 제공 완료는 `ORDER.DELIVERED`로도 오고 이 값이 `SHIPPING`이 아니다. " +
+        "현재 값은 `SHIPPING`·`DOWNLOAD`·`CODE`·`SERVICE`·`PICKUP`이고 값이 추가될 수 있어 문자열로 받는다. " +
+        "비실물 제공이 아닌 이벤트에는 없고, 없으면 `SHIPPING`으로 읽는다",
+    ),
 });
 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("이벤트 발생 시점의 주문 대표 상태"),
+  fulfillmentType: z
+    .string()
+    .describe(
+      "상품 유형. 현재 값은 `DOWNLOAD`·`CODE`·`SERVICE`·`PICKUP`이고 값이 추가될 수 있어 문자열로 받는다",
+    ),
+  fulfillmentMode: z
+    .string()
+    .nullable()
+    .describe("제공 방식. `AUTO`(결제 확정과 함께)·`MANUAL`(셀러 제공 처리)"),
+  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 +121,8 @@ export const orderCanceledWebhookEventDataSchema = z.object({
     .number()
     .int()
     .describe(
-      "환불액 (원). 수량 비율 상품 금액 + 배송비 환불 − 조건부 무료배송 미달 차감이다. " +
+      "환불액 (원). 수량 비율 상품 실결제 금액(쿠폰 배분을 뺀 금액) + 배송비 환불 − 조건부 무료배송 미달 차감 " +
+        "+ 되돌린 쿠폰 차감(`couponChargeRefundAmount`)이다. " +
         "결제사 환불 결과는 결제 내역(`GET /v1/payments/{paymentId}`)으로 확인한다",
     ),
   deliveryFeeRefundAmount: z.number().int().describe("환불액에 포함된 배송비 (원)"),
@@ -72,6 +130,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 +199,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 +265,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 +310,7 @@ export const productOutOfStockWebhookEventSchema = z.object({
 export const webhookEventSchema = z
   .discriminatedUnion("type", [
     orderWebhookEventSchema,
+    orderFulfilledWebhookEventSchema,
     orderCanceledWebhookEventSchema,
     claimWebhookEventSchema,
     inquiryWebhookEventSchema,