> For the complete documentation index, see [llms.txt](https://developer.esw.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.esw.com/fulfillment-api/resources/tutorials/pick-pack-response-taxonomy.md). # Pick Pack Response Taxonomy ### The Two-Level Status Model The `pickPackResponse` reports status at two independent levels: ``` pickPackResponse ├── status ← Operation-level: what happened to the entire pick/pack job ├── failureReason ← Operation-level: why the operation failed (when applicable) ├── problemMessage ← Free-text detail (optional) └── itemsResult[] └── [per item] ├── status ← Item-level: what happened to this specific SKU ├── failureReason ← Item-level: why this item failed (when applicable) └── problemMessage ``` **Operation-level status** answers: "Did the 3PL complete the pick/pack job?" **Item-level status** answers: "For each SKU in the order, what was the outcome?" These two levels are independent — an overall `PartialResult` at the operation level means some items succeeded and some failed, while item-level `PartialResult` on a specific SKU means that specific SKU had a mixed quantity outcome. *** ### Operation-Level Status Reference #### Complete Status Taxonomy | `status` | Meaning | `failureReason` to use | `itemsResult` required? | | ----------------------- | ---------------------------------- | -------------------------------------------------- | ----------------------- | | `AcceptedForProcessing` | Queued — not yet executed | `None` | No | | `Confirmed` | Fully successful | `None` | Recommended | | `PartialResult` | Some items succeeded, some failed | `None` | **Yes** | | `Failed` | Entire operation failed | `TransientError` / `TimeOut` / `_3PLNotConfigured` | No | | `BadRequest` | Data invalid — operation rejected | (none or `None`) | No | | `BadAddress` | Address invalid — carrier rejected | `BadAddress` | No | | `TimeOut` | Operation timed out | `TimeOut` | No | #### Valid `status` + `failureReason` combinations | `status` | Valid `failureReason` values | | ----------------------- | ------------------------------------------------ | | `AcceptedForProcessing` | `None` | | `Confirmed` | `None` | | `PartialResult` | `None` | | `Failed` | `TransientError`, `TimeOut`, `_3PLNotConfigured` | | `BadRequest` | `None` (omit `failureReason`) | | `BadAddress` | `BadAddress` | | `TimeOut` | `TimeOut` | *** ### Operation-Level Failure Reasons in Depth #### `"None"` Use with every successful or partially successful status. Required when `status` is `AcceptedForProcessing`, `Confirmed`, or `PartialResult`. ```json { "status": "Confirmed", "failureReason": "None" } ``` #### `"TransientError"` A temporary condition prevented the operation. The physical goods state is unchanged — no items were picked. ```json { "status": "Failed", "failureReason": "TransientError", "problemMessage": "WMS connection refused — retrying" } ``` **Root causes:** * Network connectivity loss between WMS and ESW * WMS subsystem unavailability during maintenance window * Database transaction failure **ESW response:** Treats as retryable. May re-issue the pick instruction. **Your response:** Retry with the same `confirmationId` after a delay. Use exponential backoff — 30 seconds, 2 minutes, 5 minutes. #### `"BadAddress"` The package was packed but the carrier's routing system cannot accept the destination address. ```json { "status": "BadAddress", "failureReason": "BadAddress", "problemMessage": "Postcode SW1A 2AA not accepted by DHL routing for this service" } ``` **Root causes:** * Shopper provided an incorrect postcode * Carrier does not service the delivery area * Address format invalid for the destination country **ESW response:** Initiates an address correction workflow. The packed goods are held at the 3PL until a corrected address is confirmed. **Your response:** Do not retry. Hold the packed goods. Await instruction from ESW once address is corrected. #### `"TimeOut"` — operation did not complete in time The pick/pack operation did not finish within the expected window. ```json { "status": "TimeOut", "failureReason": "TimeOut" } ``` **Root causes:** * WMS did not respond within the SLA timeout * Picking operation overran the allocated time window * System resource contention **ESW response:** Treats as a recoverable failure. May re-issue the pick instruction for the next wave. **Your response:** Investigate whether picking actually occurred. If no physical picking happened, retry with the same `confirmationId`. If picking was partially completed, use `PartialResult` with `itemsResult` populated. #### `"_3PLNotConfigured"` — integration configuration error ESW's system has no configuration for this 3PL provider or the configuration does not cover this order. ```json { "status": "Failed", "failureReason": "_3PLNotConfigured", "problemMessage": "3PL provider 'MyWarehouse' not configured for tenant MYBRAND" } ``` **Root causes:** * 3PL onboarding not completed in ESW's system * Wrong `tenantCode` in the request * 3PL configuration expired or deactivated **ESW response:** Cannot process the operation. Escalates to ESW operations. **Your response:** Do not retry. Escalate to your ESW integration contact to investigate the configuration. *** ### Item-Level Status Reference `_3PlProviderItemStatus` describes what happened to each individual SKU during the pick/pack operation. | `status` | Meaning | `quantityConfirmed` | `quantityFailed` | | --------------- | ----------------------------------------------- | ------------------- | ------------------ | | `Created` | Item registered in 3PL system, not yet actioned | 0 | 0 | | `Success` | All ordered units picked and packed | = quantity ordered | 0 | | `Failed` | No units could be fulfilled | 0 | = quantity ordered | | `PartialResult` | Some units succeeded, some failed | > 0 | > 0 | #### Quantity arithmetic rule For every item in `itemsResult`: ```ruby quantityConfirmed + quantityFailed = quantity ordered for that SKU ``` This rule must hold for every item, regardless of item-level status. ESW validates this — a mismatch will cause processing errors. #### `"Created"` ```json { "productCode": "SKU-00123", "quantityConfirmed": 0, "quantityFailed": 0, "status": "Created" } ``` This status indicates the pick instruction exists for this item but picking has not been attempted. Use this when submitting an `AcceptedForProcessing` operation-level status — you are registering the items that are queued for pick without reporting any outcome yet. #### `"Success"` — fully confirmed ```json { "productCode": "SKU-00123", "quantityConfirmed": 1, "quantityFailed": 0, "status": "Success", "failureReason": "NotDefined" } ``` All ordered units of this SKU were picked, packed, and included in the shipment. Always pair with `failureReason: "NotDefined"`. #### `"Failed"` ```json { "productCode": "SKU-00456", "quantityConfirmed": 0, "quantityFailed": 2, "status": "Failed", "failureReason": "NotFound", "problemMessage": "Pick face B-03-12 empty" } ``` No units of this SKU could be fulfilled. `quantityFailed` must equal the ordered quantity. Always pair with an appropriate `failureReason`. #### `"PartialResult"` — mixed quantity outcome ```json { "productCode": "SKU-00456", "quantityConfirmed": 2, "quantityFailed": 1, "status": "PartialResult", "failureReason": "Damaged", "problemMessage": "1 unit found with packaging damage — moved to quarantine" } ``` Some units picked and packed; others could not be fulfilled. Both `quantityConfirmed` and `quantityFailed` must be greater than zero. The `failureReason` describes why the failed units could not be picked. *** ### Item-Level Failure Reasons in Depth `_3PLItemFailureReason` is the most granular piece of information in the response. Each value drives a different downstream action by ESW. #### `"NotDefined"` Always use with item-level `status: "Success"`. Do not use this with `Failed` or `PartialResult` — a failure must have a reason. ```json { "status": "Success", "failureReason": "NotDefined" } ``` #### `"NotFound"` The item is not at its expected warehouse location. Either the pick face is empty or the item has been mislaid. ```json { "status": "Failed", "failureReason": "NotFound", "problemMessage": "Location A-05-03 empty — last known pick was 2024-11-02" } ``` **Inventory implication:** The inventory sync may be inaccurate. Consider triggering a physical stock count for this SKU. **ESW response:** May trigger a reallocation from another location, or cancel the item if no alternative stock exists. Will also flag the inventory discrepancy. **Your response:** Investigate the inventory discrepancy. If stock is found elsewhere, sync the updated quantity. If genuinely out of stock, sync `quantity: 0` for this SKU. #### `"CancelledItem"` The order item was cancelled (by ESW, the retailer, or the shopper) before the pick was executed. ```json { "status": "Failed", "failureReason": "CancelledItem" } ``` **ESW response:** Acknowledges the cancellation. If a cancellation flow was already initiated, this confirms it. If not, ESW may investigate why the item was cancelled without a corresponding cancellation event. **Your response:** No action needed. This is expected when ESW sends a cancellation that arrives at the 3PL after the pick instruction was issued. #### `"OperationalCancel"` The 3PL's system cancelled the pick for an operational reason — a system constraint, shift boundary, or manual override — not at ESW's instruction. ```json { "status": "Failed", "failureReason": "OperationalCancel", "problemMessage": "Item dequeued from wave — exceeded max pick time" } ``` **ESW response:** Investigates why the 3PL cancelled the item. May re-release the item for the next pick wave, depending on SLA. **Your response:** Provide a clear `problemMessage` explaining the operational reason. ESW's fulfilment team will use this to decide whether to re-issue. #### `"Damaged"` The item was located but is in a condition that means it cannot be shipped — broken packaging, physical damage, contamination. ```json { "status": "Failed", "failureReason": "Damaged", "problemMessage": "Clasp broken — moved to quarantine shelf QZ-02" } ``` **Inventory implication:** This unit should be removed from `Active` inventory. Sync it as `Quarantine` or `Suspended` as appropriate. **ESW response:** Triggers a damage/quality workflow. May refund the shopper for this item. Will expect a corresponding inventory update removing the damaged unit from `Active` stock. **Your response:** 1. Record the damaged item's location 2. Submit a follow-up inventory sync updating the SKU's `Active` quantity (decreased by the damaged count) 3. Sync the damaged units as `Quarantine` pending disposal decision #### `"ReallocatedExclude"` The item was moved to a different order allocation or excluded from this pick wave by the 3PL's allocation system. ```json { "status": "Failed", "failureReason": "ReallocatedExclude", "problemMessage": "Item reallocated to express order ESW-20241103-99999" } ``` **ESW response:** Investigates the reallocation. The original order's item will need to be re-picked from available stock in the next wave. **Your response:** Confirm with your WMS which order the item was reallocated to. Ensure the receiving order's pick/pack confirm reflects the reallocated item. #### `"EndOfDay"` The picking session or shift ended before this item could be processed. The item is unharmed and in its original location. ```json { "status": "Failed", "failureReason": "EndOfDay", "problemMessage": "Pick wave 2024-11-03-PM closed at 17:00 — item queued for 2024-11-04-AM wave" } ``` **ESW response:** Re-queues the item for the next picking wave. No escalation unless the order SLA is at risk. **Your response:** Ensure the item is included in the next pick wave. No inventory sync needed — the item is still in its original `Active` state. *** ### Status Matrix Use this matrix to verify your `pickPackResponse` is internally consistent before submission. #### Operation-level matrix | `status` | `failureReason` | `itemsResult` | Use when | | ----------------------- | ------------------- | ------------- | ---------------------------------------- | | `AcceptedForProcessing` | `None` | Optional | 3PL confirms receipt of pick instruction | | `Confirmed` | `None` | Recommended | All items picked and packed | | `PartialResult` | `None` | **Required** | Some items packed, some failed | | `Failed` | `TransientError` | Omit | System error, no items picked | | `Failed` | `TimeOut` | Omit | Operation timed out | | `Failed` | `_3PLNotConfigured` | Omit | Configuration problem | | `BadRequest` | (omit) | Omit | Order reference not found in WMS | | `BadAddress` | `BadAddress` | Omit | Carrier rejected address | | `TimeOut` | `TimeOut` | Omit | Overall timeout | #### Item-level matrix (per `itemsResult` entry) | `status` | `failureReason` | `quantityConfirmed` | `quantityFailed` | Use when | | --------------- | -------------------- | ------------------- | ---------------- | --------------------------------------- | | `Created` | `NotDefined` | 0 | 0 | Item queued, not yet picked | | `Success` | `NotDefined` | = qty ordered | 0 | All units picked successfully | | `Failed` | `NotFound` | 0 | = qty ordered | Item not at pick location | | `Failed` | `CancelledItem` | 0 | = qty ordered | Item cancelled before picking | | `Failed` | `OperationalCancel` | 0 | = qty ordered | 3PL internal cancellation | | `Failed` | `Damaged` | 0 | = qty ordered | All units damaged | | `Failed` | `ReallocatedExclude` | 0 | = qty ordered | All units reassigned | | `Failed` | `EndOfDay` | 0 | = qty ordered | Session ended, no units picked | | `PartialResult` | `Damaged` | > 0 | > 0 | Some units packed, some damaged | | `PartialResult` | `NotFound` | > 0 | > 0 | Some units picked, some not found | | `PartialResult` | `EndOfDay` | > 0 | > 0 | Some units picked before session closed | *** ### Decision Tree for Building `pickPackResponse` ``` Did the 3PL's system receive and queue the pick instruction? │ └── YES — did picking actually occur? │ ├── NOT YET (queued only) │ → status: "AcceptedForProcessing", failureReason: "None" │ └── YES — did ALL items pick successfully? │ ├── YES — all items, all quantities │ → status: "Confirmed", failureReason: "None" │ → itemsResult: each item as Success, quantityFailed: 0 │ └── NO — why did some or all fail? │ ├── System/integration error (no items picked) │ └── What kind? │ ├── Temporary → status: "Failed", failureReason: "TransientError" │ ├── Timeout → status: "TimeOut", failureReason: "TimeOut" │ └── Config → status: "Failed", failureReason: "_3PLNotConfigured" │ ├── Address invalid (items packed but carrier rejected) │ → status: "BadAddress", failureReason: "BadAddress" │ ├── Order reference unknown to 3PL │ → status: "BadRequest" │ └── SOME items picked, some failed (partial) → status: "PartialResult", failureReason: "None" → itemsResult: REQUIRED ├── Successful items → Success, NotDefined └── Failed items → Failed or PartialResult └── Why? ├── Not at location → NotFound ├── Physically damaged → Damaged ├── Cancelled before pick → CancelledItem ├── 3PL internal cancel → OperationalCancel ├── Reassigned → ReallocatedExclude └── Session closed → EndOfDay ``` *** ### Response Actions by Status/Failure Combination | Combination | ESW Action | | --------------------------------- | --------------------------------------------------------------------------------------------------------------- | | `Confirmed` | Advances order to carrier booking / label generation stage | | `AcceptedForProcessing` | Waits for follow-up confirmation — no state change yet | | `PartialResult` + `Damaged` | Ships confirmed items; triggers damage/quality workflow for failed; may offer shopper a refund for failed items | | `PartialResult` + `NotFound` | Ships confirmed items; triggers stock investigation; may cancel remaining items if no reallocation available | | `PartialResult` + `EndOfDay` | Ships confirmed items; re-queues failed items for next wave | | `PartialResult` + `CancelledItem` | Ships confirmed items; acknowledges cancellation for failed items; refund flow may already be in progress | | `Failed` + `TransientError` | Schedules retry; does not cancel order | | `Failed` + `TimeOut` | Schedules retry after interval | | `Failed` + `_3PLNotConfigured` | Escalates to ESW operations; order may be manually rerouted | | `BadAddress` | Pauses fulfilment; initiates address correction workflow with shopper | | `BadRequest` | Investigates reference mismatch; may require manual resolution | *** *** ### Summary Reference Card ``` OPERATION LEVEL ───────────────────────────────────────────────────────────────── Status failureReason itemsResult ───────────────────────────────────────────────────────────────── AcceptedForProcessing None Optional Confirmed None Recommended PartialResult None REQUIRED Failed TransientError Omit Failed TimeOut Omit Failed _3PLNotConfigured Omit BadRequest (omit) Omit BadAddress BadAddress Omit TimeOut TimeOut Omit ITEM LEVEL (inside itemsResult[]) ───────────────────────────────────────────────────────────────── status failureReason Confirmed Failed ───────────────────────────────────────────────────────────────── Created NotDefined 0 0 Success NotDefined = ordered 0 Failed NotFound 0 = ordered Failed CancelledItem 0 = ordered Failed OperationalCancel 0 = ordered Failed Damaged 0 = ordered Failed ReallocatedExclude 0 = ordered Failed EndOfDay 0 = ordered PartialResult Damaged > 0 > 0 PartialResult NotFound > 0 > 0 PartialResult EndOfDay > 0 > 0 (any partial) (any fail reason) > 0 > 0 ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developer.esw.com/fulfillment-api/resources/tutorials/pick-pack-response-taxonomy.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.