Fulfillment & Returns
Fulfill order items, manage tracking, returns, refunds and restocks
📄️ Fulfill order items
Marks the given items (and quantities) as fulfilled and updates the order's fulfillment status. Items on hold (`ITEM_ON_HOLD`) or awaiting payment (`ITEM_PAYMENT_PENDING`) cannot be fulfilled. Optionally attaches tracking details and emails them to the customer. Returns the updated fulfillment.
📄️ Edit fulfillment tracking
Updates the tracking details (URL, number, carrier) of items that are already fulfilled. Returns 404 if none of the given items belong to the fulfillment.
📄️ Cancel a fulfillment
Reverts fulfilled items to unfulfilled. `fulfillmentId` is either the fulfillment `_id` (reverts every item) or the `_id` of a single fulfillment item (reverts only that item). Returns the updated fulfillment.
📄️ Hold or release order items
Puts items on hold (with a reason) or releases them. Items on hold cannot be fulfilled. Releasing a hold returns the item to unfulfilled; it does not fulfill it. Holding every item sets the order to on hold. Returns the full order detail rebuilt from the canonical database.
📄️ Get the return for an order
Returns the order's return request with its items populated (name, price, image), or `null` in `data` when none exists. An order has at most one return.
📄️ Create a return
Opens a return for fulfilled items. The order must be paid or partially paid, created within the last 14 days (`RETURN_WINDOW_EXPIRED` otherwise), and items cannot exceed the fulfilled quantity (`INVALID_RETURN_QUANTITY`). An order can have only one return (`RETURN_ALREADY_EXISTS`).
📄️ Refund a return
Refunds the order's return. Only returns in `pending` or `processing` status can be refunded (`RETURN_INVALID_STATE` otherwise). Returns the updated return and the payment record.
📄️ Restock a return
Returns the returned items to inventory. The return must have been created with `restockItems: true` (`RESTOCK_NOT_ENABLED` otherwise) and can be restocked only once (`RESTOCK_ALREADY_PROCESSED`). Takes no request body.
📄️ Cancel a return
Cancels the order's return. Only returns in `pending` or `processing` status can be cancelled (`RETURN_INVALID_STATE` otherwise).