We are building a custom fulfillment service app, and we wanted to confirm the correct approach for handling partial cancellations when we cannot fulfill some items in an order.
Use-case:
A customer places an order for 1 SKU with 5 quantity.
Our fulfillment app accepts the fulfillment request.
We are able to fulfill 3 units and ship them successfully.
However, 2 units cannot be fulfilled (e.g., out of stock or discontinued).
Flow we are thinking to implement:
Accept the fulfillment request for the order.
Use the fulfillmentCreateV2 mutation to create a fulfillment for 3 units.
For the 2 unfulfillable units, we want to cancel them so that they are no longer pending.
Question:
The Shopify docs (Step 5: Create fulfillments) show how to create a fulfillment.
But in this partial cancellation scenario, should we:
Call fulfillmentOrderClose on the remaining 2 units, so that Shopify automatically reassigns them back to the merchant? Build for fulfillment services
Or should I use cancel API so that Shopify automatically reassigns them back to the merchant Build for fulfillment services
Or is there a better API to explicitly cancel only the 2 unfulfilled items?
We want to ensure that merchants clearly see 3 items fulfilled and 2 items canceled/unfulfilled in the order timeline.
Could someone clarify the recommended approach for partial cancellations in fulfillment apps?
Just a heads up that the fulfillmentCreateV2 mutation is deprecated now. There is fulfillmentCreate as a replacement
I think the answer depends on what your merchants want to do in this scenario.
If they want the items to be fulfilled from a different location, just refunded etc.
You’ve got multiple options here as you’ve described and each is valid options but I think its more of a business decision on what your merchants want as to how you then handle the fulfillment orders
I agree with @JordanFinners here, it is ultimately dependent on what your merchants need or want your app to do, but just to clarify: for your “partial ship, remainder unfulfillable,” scenario, you technically could accept the fulfillment request, then create a partial shipment for the 3 units using fulfillmentCreate (fulfillmentCreateV2 is deprecated as Jordan mentioned!).
After that, call fulfillmentOrderClose on the same FulfillmentOrder with a brief message (e.g., “Out of stock for 2”), which should mark the FO as INCOMPLETE, closes your request, and hands the remaining quantity back to the merchant.
This should show a clear order timeline showing 3 fulfilled items and an explicit note that your service couldn’t fulfill the rest, allowing the merchant to reassign or refund.
I’d avoid using fulfillmentOrderCancel unless it’s necessary, as it cancels the FO and creates a replacement FO (often still assigned to you) and is mainly intended for submitted-but-not-accepted scenarios (for example when the merchant accidentally assigns an FO to your service but didn’t intend to).
Hope this helps, let me know if we can help out further
I have one question fulfillmentOrderClose does not have quantity field .
So if we have done create 3 units fulfillmentCreate and after that we do fulfillmentOrderClose .
Will it create a new Order with just 2 quantity in this case ?
Calling fulfillmentOrderClose after you partially fulfill wouldn’t create a new Order or automatically change the Order quantities.
Basically, it marks the remaining 2 units on that FulfillmentOrder as incomplete and returns control to the merchant. The order still shows 3 fulfilled and 2 unfulfilled. If the merchant later re-requests fulfillment for the remainder, Shopify will create a new FulfillmentOrder at that time; otherwise they can reassign or refund. If the merchant wants those 2 units “canceled” (i.e., removed/refunded), that’s done via order edits/refunds, not by fulfillmentOrderClose. Hope that makes sense, let me know if I can clarify anything further as always!
