feat(fulfillment, core-flows, types, utils, medusa): support custom delivery address + pass additional data to createFulfillment (#16139)

shahednasser · web-flow · commit 9fa4bd9eb941 · 2026-08-04T18:40:55.000+03:00
diff --git a/.changeset/wet-moose-relax.md b/.changeset/wet-moose-relax.md
@@ -0,0 +1,9 @@
+---
+"@medusajs/fulfillment": patch
+"@medusajs/core-flows": patch
+"@medusajs/types": patch
+"@medusajs/utils": patch
+"@medusajs/medusa": patch
+---
+
+feat(fulfillment, core-flows, types, utils, medusa): support custom delivery address + pass additional data to createFulfillment
diff --git a/integration-tests/http/__tests__/order/admin/order.spec.ts b/integration-tests/http/__tests__/order/admin/order.spec.ts
@@ -1829,6 +1829,41 @@ medusaIntegrationTestRunner({
         expect(iitem.reserved_quantity).toBe(0)
       })
 
+      it("should override the fulfillment's delivery address with the request's delivery_address", async () => {
+        const orderItemId = order.items.find(
+          (i) => i.variant_id === productOverride3.variants[0].id
+        ).id
+
+        const {
+          data: { order: fulfillableOrder },
+        } = await api.post(
+          `/admin/orders/${order.id}/fulfillments?fields=fulfillments.id,fulfillments.delivery_address.*`,
+          {
+            shipping_option_id: seeder.shippingOption.id,
+            location_id: seeder.stockLocation.id,
+            items: [{ id: orderItemId, quantity: 1 }],
+            delivery_address: {
+              first_name: "Nova",
+              last_name: "Poshta",
+            },
+          },
+          adminHeaders
+        )
+
+        expect(fulfillableOrder.fulfillments).toHaveLength(1)
+        expect(fulfillableOrder.fulfillments[0].delivery_address).toEqual(
+          expect.objectContaining({
+            // overridden by the request
+            first_name: "Nova",
+            last_name: "Poshta",
+            // untouched fields are still taken from the order's shipping address
+            address_1: order.shipping_address.address_1,
+            city: order.shipping_address.city,
+            country_code: order.shipping_address.country_code,
+          })
+        )
+      })
+
       it("should throw if trying to fulfillment more items than it is reserved", async () => {
         const orderItemId = order.items.find(
           (i) => i.variant_id === productOverride3.variants[0].id
diff --git a/packages/core/core-flows/src/fulfillment/workflows/create-fulfillment.ts b/packages/core/core-flows/src/fulfillment/workflows/create-fulfillment.ts
@@ -96,14 +96,10 @@ export const createFulfillmentWorkflow = createWorkflow(
       }
     })
 
-    // When we have support for hooks with a return this would be a great
-    // place to put a hook for people to collect additional data they would
-    // like to pass down to the provider.
-    //
-    // const providerDataHook = createHook("getProviderData", stepInput)
-    //
-    // The collected provider data would be passed to createFulfillment in a
-    // additional_provider_data: Record<string, unknown> field.
+    // Callers can pass an `additional_data` field on the input, which is
+    // forwarded as-is to the provider's `createFulfillment` method (without
+    // being persisted on the fulfillment). This lets custom data reach the
+    // provider before it talks to the third-party service.
 
     const result = createFulfillmentStep(stepInput)
 
diff --git a/packages/core/core-flows/src/order/workflows/create-fulfillment.ts b/packages/core/core-flows/src/order/workflows/create-fulfillment.ts
@@ -149,7 +149,7 @@ function prepareFulfillmentData({
   itemsList,
 }: {
   order: OrderDTO
-  input: OrderWorkflow.CreateOrderFulfillmentWorkflowInput
+  input: OrderWorkflow.CreateOrderFulfillmentWorkflowInput & AdditionalData
   shippingOption: {
     id: string
     provider_id: string
@@ -247,6 +247,14 @@ function prepareFulfillmentData({
   const shippingAddress = order.shipping_address ?? { id: undefined }
   delete shippingAddress.id
 
+  // Merge any recipient overrides passed in the request over the order's
+  // shipping address, so the fulfillment provider receives the resolved
+  // delivery address without mutating the order itself.
+  const deliveryAddress = {
+    ...shippingAddress,
+    ...(input.delivery_address ?? {}),
+  }
+
   return {
     input: {
       location_id: locationId,
@@ -257,10 +265,11 @@ function prepareFulfillmentData({
       items: fulfillmentItems,
       requires_shipping: someItemsRequireShipping,
       labels: input.labels ?? [],
-      delivery_address: shippingAddress as any,
+      delivery_address: deliveryAddress as any,
       created_by: input.created_by,
       packed_at: new Date(),
       metadata: input.metadata,
+      additional_data: input.additional_data,
     },
   }
 }
diff --git a/packages/core/types/src/fulfillment/mutations/fulfillment.ts b/packages/core/types/src/fulfillment/mutations/fulfillment.ts
@@ -87,6 +87,13 @@ export interface CreateFulfillmentDTO {
    * The associated order to be sent to the provider.
    */
   order?: Partial<OrderDTO>
+
+  /**
+   * Custom key-value pairs to pass to the fulfillment provider's `createFulfillment`
+   * method. Unlike `data`, this isn't persisted on the fulfillment; it's only
+   * forwarded to the provider at creation time.
+   */
+  additional_data?: Record<string, unknown>
 }
 
 /**
diff --git a/packages/core/types/src/fulfillment/provider.ts b/packages/core/types/src/fulfillment/provider.ts
@@ -124,7 +124,10 @@ export interface IFulfillmentProvider {
     data: Record<string, unknown>,
     items: Partial<Omit<FulfillmentItemDTO, "fulfillment">>[],
     order: Partial<FulfillmentOrderDTO> | undefined,
-    fulfillment: Partial<Omit<FulfillmentDTO, "provider_id" | "data" | "items">>
+    fulfillment: Partial<
+      Omit<FulfillmentDTO, "provider_id" | "data" | "items">
+    >,
+    additionalData?: Record<string, unknown>
   ): Promise<CreateFulfillmentResult>
   /**
    *
diff --git a/packages/core/types/src/http/order/admin/payloads.ts b/packages/core/types/src/http/order/admin/payloads.ts
@@ -53,6 +53,12 @@ export interface AdminCreateOrderFulfillment {
    * Whether to notify the customer about this change.
    */
   no_notification?: boolean
+  /**
+   * The recipient address to use for the fulfillment. It's merged over the
+   * order's shipping address, allowing you to override recipient details
+   * (such as the first and last name) sent to the fulfillment provider.
+   */
+  delivery_address?: OrderAddress
   /**
    * Key-value pairs of custom data.
    */
diff --git a/packages/core/types/src/workflow/fulfillment/create-fulfillment.ts b/packages/core/types/src/workflow/fulfillment/create-fulfillment.ts
@@ -188,4 +188,11 @@ export type CreateFulfillmentWorkflowInput = {
    * The associated fulfillment order to be sent to the provider.
    */
   order?: CreateFulfillmentOrderWorkflowDTO
+
+  /**
+   * Custom key-value pairs to pass to the fulfillment provider's `createFulfillment`
+   * method. Unlike `data`, this isn't persisted on the fulfillment; it's only
+   * forwarded to the provider at creation time.
+   */
+  additional_data?: Record<string, unknown>
 }
diff --git a/packages/core/types/src/workflow/order/create-fulfillment.ts b/packages/core/types/src/workflow/order/create-fulfillment.ts
@@ -1,6 +1,9 @@
 import { OrderLineItemDTO } from "../../order"
 import { BigNumberInput } from "../../totals"
-import { CreateFulfillmentLabelWorkflowDTO } from "../fulfillment/create-fulfillment"
+import {
+  CreateFulfillmentAddressWorkflowDTO,
+  CreateFulfillmentLabelWorkflowDTO,
+} from "../fulfillment/create-fulfillment"
 
 /**
  * The details of an item in the fulfillment.
@@ -67,6 +70,13 @@ export interface CreateOrderFulfillmentWorkflowInput {
    */
   shipping_option_id?: string
 
+  /**
+   * The recipient address to use for the fulfillment. It's merged over the
+   * order's shipping address, allowing you to override recipient details
+   * (such as the first and last name) sent to the fulfillment provider.
+   */
+  delivery_address?: CreateFulfillmentAddressWorkflowDTO
+
   /**
    * Whether the fulfillment should be shipped.
    */
diff --git a/packages/core/utils/src/fulfillment/provider.ts b/packages/core/utils/src/fulfillment/provider.ts
@@ -296,6 +296,9 @@ export class AbstractFulfillmentProviderService
    * @param items - The items in the fulfillment.
    * @param order - The order this fulfillment is created for.
    * @param fulfillment - The fulfillment's details.
+   * @param additionalData - Custom key-value pairs forwarded from the workflow that
+   * created the fulfillment (for example, the `additional_data` of the Create Order
+   * Fulfillment API route). It isn't persisted on the fulfillment.
    * @returns An object whose `data` property is stored in the fulfillment's `data` property.
    *
    * @example
@@ -305,7 +308,8 @@ export class AbstractFulfillmentProviderService
    *     data: Record<string, unknown>,
    *     items: Partial<Omit<FulfillmentItemDTO, "fulfillment">>[],
    *     order: Partial<FulfillmentOrderDTO> | undefined,
-   *     fulfillment: Partial<Omit<FulfillmentDTO, "provider_id" | "data" | "items">>
+   *     fulfillment: Partial<Omit<FulfillmentDTO, "provider_id" | "data" | "items">>,
+   *     additionalData?: Record<string, unknown>
    *   ): Promise<CreateFulfillmentResult> {
    *     // assuming the client creates a fulfillment
    *     // in the third-party service
@@ -327,7 +331,10 @@ export class AbstractFulfillmentProviderService
     data: Record<string, unknown>,
     items: Partial<Omit<FulfillmentItemDTO, "fulfillment">>[],
     order: Partial<FulfillmentOrderDTO> | undefined,
-    fulfillment: Partial<Omit<FulfillmentDTO, "provider_id" | "data" | "items">>
+    fulfillment: Partial<
+      Omit<FulfillmentDTO, "provider_id" | "data" | "items">
+    >,
+    additionalData?: Record<string, unknown>
   ): Promise<CreateFulfillmentResult> {
     throw Error("createFulfillment must be overridden by the child class")
   }
diff --git a/packages/medusa/src/api/admin/orders/validators.ts b/packages/medusa/src/api/admin/orders/validators.ts
@@ -105,6 +105,7 @@ export const OrderCreateFulfillment = z.object({
   location_id: z.string().nullish(),
   shipping_option_id: z.string().optional(),
   no_notification: z.boolean().optional(),
+  delivery_address: AddressPayload.optional(),
   metadata: z.record(z.string(), z.unknown()).nullish(),
 })
 export const AdminOrderCreateFulfillment = WithAdditionalData(
diff --git a/packages/modules/fulfillment/integration-tests/__fixtures__/fulfillment.ts b/packages/modules/fulfillment/integration-tests/__fixtures__/fulfillment.ts
@@ -44,5 +44,6 @@ export function generateCreateFulfillmentData(
       },
     ],
     order: data.order ?? {},
+    additional_data: data.additional_data,
   }
 }
diff --git a/packages/modules/fulfillment/integration-tests/__fixtures__/providers/default-provider.ts b/packages/modules/fulfillment/integration-tests/__fixtures__/providers/default-provider.ts
@@ -3,7 +3,13 @@ import { AbstractFulfillmentProviderService } from "@medusajs/framework/utils"
 export class FulfillmentProviderServiceFixtures extends AbstractFulfillmentProviderService {
   static identifier = "fixtures-fulfillment-provider"
 
-  async createFulfillment(data, items, order, fulfillment): Promise<any> {
+  async createFulfillment(
+    data,
+    items,
+    order,
+    fulfillment,
+    additionalData
+  ): Promise<any> {
     return {}
   }
 
diff --git a/packages/modules/fulfillment/integration-tests/__tests__/fulfillment-module-service/fulfillment.spec.ts b/packages/modules/fulfillment/integration-tests/__tests__/fulfillment-module-service/fulfillment.spec.ts
@@ -13,6 +13,7 @@ import {
   generateCreateFulfillmentData,
   generateCreateShippingOptionsData,
 } from "../../__fixtures__"
+import { FulfillmentProviderServiceFixtures } from "../../__fixtures__/providers/default-provider"
 
 jest.setTimeout(100000)
 
@@ -192,6 +193,58 @@ moduleIntegrationTestRunner<IFulfillmentModuleService>({
             )
           })
 
+          it("should forward additional_data to the provider without persisting it", async () => {
+            const shippingProfile = await service.createShippingProfiles({
+              name: "test",
+              type: "default",
+            })
+            const fulfillmentSet = await service.createFulfillmentSets({
+              name: "test",
+              type: "test-type",
+            })
+            const serviceZone = await service.createServiceZones({
+              name: "test",
+              fulfillment_set_id: fulfillmentSet.id,
+            })
+
+            const shippingOption = await service.createShippingOptions(
+              generateCreateShippingOptionsData({
+                provider_id: providerId,
+                service_zone_id: serviceZone.id,
+                shipping_profile_id: shippingProfile.id,
+              })
+            )
+
+            const createFulfillmentProviderSpy = jest.spyOn(
+              FulfillmentProviderServiceFixtures.prototype,
+              "createFulfillment"
+            )
+
+            jest.clearAllMocks()
+
+            const additionalData = {
+              recipient_first_name: "John",
+              recipient_last_name: "Doe",
+            }
+
+            const fulfillment = await service.createFulfillment(
+              generateCreateFulfillmentData({
+                provider_id: providerId,
+                shipping_option_id: shippingOption.id,
+                additional_data: additionalData,
+              })
+            )
+
+            // the provider receives additional_data as its last argument
+            expect(createFulfillmentProviderSpy).toHaveBeenCalledTimes(1)
+            expect(createFulfillmentProviderSpy.mock.calls[0][4]).toEqual(
+              additionalData
+            )
+
+            // additional_data is not persisted on the fulfillment
+            expect(fulfillment).not.toHaveProperty("additional_data")
+          })
+
           it("should create a return fulfillment", async () => {
             const shippingProfile = await service.createShippingProfiles({
               name: "test",
diff --git a/packages/modules/fulfillment/src/services/fulfillment-module-service.ts b/packages/modules/fulfillment/src/services/fulfillment-module-service.ts
@@ -603,7 +603,7 @@ export default class FulfillmentModuleService
     data: FulfillmentTypes.CreateFulfillmentDTO,
     @MedusaContext() sharedContext: Context = {}
   ): Promise<FulfillmentTypes.FulfillmentDTO> {
-    const { order, ...fulfillmentDataToCreate } = data
+    const { order, additional_data, ...fulfillmentDataToCreate } = data
 
     const fulfillment = await this.fulfillmentService_.create(
       fulfillmentDataToCreate,
@@ -624,7 +624,8 @@ export default class FulfillmentModuleService
           fulfillmentData || {},
           items.map((i) => i),
           order,
-          fulfillmentRest as unknown as Partial<FulfillmentDTO>
+          fulfillmentRest as unknown as Partial<FulfillmentDTO>,
+          additional_data
         )
       await this.fulfillmentService_.update(
         {
diff --git a/packages/modules/fulfillment/src/services/fulfillment-provider.ts b/packages/modules/fulfillment/src/services/fulfillment-provider.ts
@@ -137,10 +137,19 @@ Please make sure that the provider is registered in the container and it is conf
     data: Record<string, unknown>,
     items: Partial<Omit<FulfillmentItemDTO, "fulfillment">>[],
     order: Partial<FulfillmentOrderDTO> | undefined,
-    fulfillment: Partial<Omit<FulfillmentDTO, "provider_id" | "data" | "items">>
+    fulfillment: Partial<
+      Omit<FulfillmentDTO, "provider_id" | "data" | "items">
+    >,
+    additionalData?: Record<string, unknown>
   ): Promise<CreateFulfillmentResult> {
     const provider = this.retrieveProviderRegistration(providerId)
-    return await provider.createFulfillment(data, items, order, fulfillment)
+    return await provider.createFulfillment(
+      data,
+      items,
+      order,
+      fulfillment,
+      additionalData
+    )
   }
 
   async cancelFulfillment(
diff --git a/www/utils/generated/oas-output/operations/admin/post_admin_orders_[id]_fulfillments.ts b/www/utils/generated/oas-output/operations/admin/post_admin_orders_[id]_fulfillments.ts
@@ -74,6 +74,9 @@
  *                 type: boolean
  *                 title: no_notification
  *                 description: Whether to send the customer a notification about the created fulfillment.
+ *               delivery_address:
+ *                 $ref: "#/components/schemas/AdminFulfillmentDeliveryAddress"
+ *                 description: The recipient address to use for the fulfillment. It's merged over the order's shipping address, allowing you to override recipient details (such as the first and last name) sent to the fulfillment provider.
  *               metadata:
  *                 type: object
  *                 description: The order's metadata. Can hold custom key-value pairs.
