Navigating Unfulfillable Order Items: A Developer's Guide to Seamless Merchant Communication

As app developers, we know that managing order fulfilment can sometimes be a puzzle, especially when not all items in an order can be fulfilled at once. One common challenge is the "partial ship, remainder unfulfillable" scenario. How do you handle this gracefully, ensuring your merchants have clear visibility and control? Let's dive into the best practices.

Understanding the "Partial Ship, Remainder Unfulfillable" Dilemma

Imagine a customer orders five units of an item, but your service only has three in stock. This is the classic "partial ship, remainder unfulfillable" situation. The goal here is to ship the available units while clearly communicating that the rest couldn't be fulfilled, allowing the merchant to decide on the next steps—whether that's reassigning the remaining items to another service or issuing a refund.

The Recommended Approach: fulfillmentCreate and fulfillmentOrderClose

To handle this scenario effectively, you'll want to leverage two key API calls:

1. Accept the Fulfillment Request: You could technically accept the fulfillment request.

2. Create a Partial Shipment: For the units you can fulfil (e.g., 3 units), create a partial shipment using fulfillmentCreate. It's important to note that fulfillmentCreateV2 is deprecated. This action will accurately reflect the items that have been shipped.

3. Close the Remaining Unfulfillable Items: After creating the partial shipment, call fulfillmentOrderClose on the same FulfillmentOrder with a brief message (e.g., “Out of stock for 2”). This is crucial for handling the unfulfillable portion.

   What happens next? Calling fulfillmentOrderClose with a message should

   • Mark the `FulfillmentOrder` as INCOMPLETE [1].
   • Close your request.
   • Hand the remaining quantity back to the merchant.

The Merchant's View: Clarity and Control

This method provides excellent visibility for the merchant. The order timeline should clearly show 3 fulfilled items and an explicit note that your service couldn’t fulfill the rest .

This transparency allows the merchant to promptly reassign the unfulfilled items to another service or issue a refund to the customer, ensuring smooth order management.

A Word of Caution: Avoid fulfillmentOrderCancel for This Scenario

It’s generally best to avoid using fulfillmentOrderCancel unless it's necessary for the "partial ship, remainder unfulfillable" situation. Here's why:

• fulfillmentOrderCancel cancels the `FulfillmentOrder` and creates a replacement `FulfillmentOrder.
• Often, this new replacement `FulfillmentOrder` will still be assigned to your service, potentially leading to confusion or an endless loop if you can't fulfil it.
• fulfillmentOrderCancel is mainly intended for submitted-but-not-accepted scenarios, such as when a merchant accidentally assigns an `FulfillmentOrder` to your service but didn’t actually intend to.

By understanding and implementing the `fulfillmentCreate` and `fulfillmentOrderClose` workflow, your app can provide a robust and clear solution for managing unfulfillable order items, empowering merchants with the information and control they need.