> For the complete documentation index, see [llms.txt](https://eshop.gitbook.io/eshopbox-developers/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://eshop.gitbook.io/eshopbox-developers/advanced/failed-delivery-api.md). # Failed Delivery API The Failed Delivery Resolution API lets you submit a resolution action for a shipment that could not be delivered. You can request another attempt, choose a new delivery date, request return to origin ## NDR Resolution API Use this API to submit an action after a forward shipment has a failed delivery attempt (Non-Delivery Report, or NDR). You can request another attempt, choose a new delivery date, request return to origin, or report a fake attempt. ### Before you begin You need: * Sandbox access for testing. Raise a support ticket with Eshopbox to request it. * A seller access token. See [Authentication](https://eshop.gitbook.io/eshopbox-developers/basics/authentication/generating-access-token) for how to generate and refresh it. * A forward shipment tracking ID/AWB belonging to your seller account, with an actionable NDR. * The shipment's current NDR reason, so you can pick an allowed resolution code. See Allowed codes by NDR reason. Use the shipment tracking ID, rather than an internal shipment ID or an order number, in `trackingId`. For orders with multiple shipments, submit a separate request for each affected tracking ID. ### Endpoint and headers ```http POST https://wms.eshopbox.com/api/v2/ndrResolution Authorization: Bearer {ACCESS_TOKEN} Content-Type: application/json Accept: application/json ``` This is the production endpoint. For sandbox access, raise a support ticket with Eshopbox. ### Choose a resolution | resolutionCode | Action | Additional information | | -------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | `ACTF001` | Request another delivery attempt | Optionally include corrected delivery details. | | `ACTF002` | Request delivery on a new date | Include `deferredDate`. | | `ACTF003` | Request return to origin (RTO) | Optionally include the reason in `remarks`. Confirm the buyer's intention before requesting RTO. | | `ACTF004` | Report a fake attempt and request another attempt | Optionally include communication evidence and buyer feedback. | Send codes exactly as shown, in uppercase. An action may be rejected if it is unavailable for the shipment's current NDR reason. Already-delivered shipments cannot be resolved through this API. These codes apply to **forward delivery**. Use the affected forward shipment's tracking ID. #### Allowed codes by reason Each NDR reason allows only some resolution codes. Sending a code that is not allowed returns `412` `107: Invalid resolution action.` | NDR reason | Allowed resolution codes | | ------------------------------------------- | ------------------------------------------ | | Address Issue | `ACTF001`, `ACTF002`, `ACTF003`, `ACTF004` | | Customer Unavailable | `ACTF001`, `ACTF002`, `ACTF003`, `ACTF004` | | Customer Unreachable | `ACTF001`, `ACTF002`, `ACTF003`, `ACTF004` | | Customer wants open delivery | `ACTF001`, `ACTF002`, `ACTF003`, `ACTF004` | | Delivery delayed - external factors | `ACTF001`, `ACTF002`, `ACTF003`, `ACTF004` | | Delivery Rescheduled | `ACTF001`, `ACTF002`, `ACTF003`, `ACTF004` | | Exception | `ACTF001`, `ACTF002`, `ACTF003`, `ACTF004` | | OTP code mismatch/unavailable | `ACTF001`, `ACTF002`, `ACTF003`, `ACTF004` | | OTP verified cancellation | `ACTF001`, `ACTF002`, `ACTF003`, `ACTF004` | | Payment Issue | `ACTF001`, `ACTF002`, `ACTF003`, `ACTF004` | | Shipment Misrouted by the logistics partner | `ACTF001`, `ACTF002`, `ACTF003`, `ACTF004` | | No Attempt | `ACTF001`, `ACTF002`, `ACTF003` | | Rejected by Customer | `ACTF001`, `ACTF003`, `ACTF004` | | Shipment Seized By Customer | `ACTF001`, `ACTF003`, `ACTF004` | | Order already cancelled | `ACTF003`, `ACTF004` | | Out Of Delivery Area | `ACTF003` | | Self Collect | `ACTF003` | ### Request fields | Field | Type | Requirement and meaning | | -------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `trackingId` | string | Required. The affected shipment's tracking ID/AWB. | | `resolutionCode` | string | Required. One of ACTF001–ACTF004. The code must be allowed for the shipment's current NDR reason; see Allowed codes by NDR reason. | | `customerOrderNumber` | string | Required. The customer order number associated with the shipment. A missing or mismatched value returns 105: Invalid Customer Order Number. | | `deferredDate` | string | Required for ACTF002; omit for other actions. Format YYYY-MM-DD. Must be from tomorrow up to 3 days after the request date, in IST (Asia/Kolkata). | | `contactPhoneNumber` | string | Optional. Buyer contact number to forward to the courier for ACTF001, ACTF002 and ACTF004. Not forwarded for ACTF003 (RTO). If omitted, no phone update is sent to the courier; the phone saved on the order is not substituted. | | `shippingDetails` | object | Optional. Corrected delivery details for ACTF001 or ACTF004; see Corrected delivery details. | | `remarks` | string | Optional explanation, especially for RTO or a fake attempt. | | `proofOfCommunication` | array of strings | Optional, for ACTF004. Publicly accessible HTTPS URLs of communication evidence. Allowed extensions: .jpg, .jpeg, .png, .mp3, .wav (case insensitive). Send URLs, not file contents. | | `fakeAttemptBuyerCommunication` | string | Optional, for ACTF004. One of BUYER\_CONFIRMED\_AVAILABLE, BUYER\_NOT\_CONTACTED or BUYER\_DENIED\_ATTEMPT. | | `fakeAttemptBuyerCommunicationRemarks` | string | Optional, for ACTF004. Notes describing the buyer's feedback. | `clientEmail` is set from your access token. Do not send it. #### Corrected delivery details ```json {   "shippingDetails": {     "updatedAddress": "24 Example Road, Apartment 3, Bengaluru",     "landmark": "Near the community centre",     "notes": "Use the main entrance"   },   "contactPhoneNumber": "9999999999" } ``` | Nested field | Type | Meaning | | ---------------- | ------ | --------------------------------- | | `updatedAddress` | string | Corrected delivery address. | | `landmark` | string | Nearby landmark. | | `notes` | string | Additional delivery instructions. | All nested fields are optional. Use them only with `ACTF001` or `ACTF004`; they are not applied to `ACTF003` (RTO). Only `updatedAddress`, `landmark` and `notes` are forwarded to the courier. To send a new buyer phone number, use the top-level `contactPhoneNumber` field. Evidence URLs in `proofOfCommunication` must be publicly accessible over HTTPS. Query strings and fragments are ignored when checking the file extension, and blank entries are ignored. PDF and video files are rejected. ### Examples The tracking IDs, phone numbers, addresses and evidence URLs below are examples. Replace them with your own values. #### Request another attempt ```bash curl --request POST   "https://wms.eshopbox.com/api/v2/ndrResolution"   --header "Authorization: Bearer ${ACCESS_TOKEN}"   --header 'Content-Type: application/json'   --header 'Accept: application/json'   --data '{     "customerOrderNumber": "ORDER-1001",     "trackingId": "AWB123456789",     "contactPhoneNumber": "9999999999",     "resolutionCode": "ACTF001"   }' ``` #### Choose a new delivery date Use the same endpoint and headers: ```json {   "customerOrderNumber": "ORDER-1001",   "trackingId": "AWB123456789",   "contactPhoneNumber": "9999999999",   "resolutionCode": "ACTF002",   "deferredDate": "2026-10-20" } ``` Use a date from tomorrow up to 3 days ahead, in IST. #### Request return to origin ```json {   "customerOrderNumber": "ORDER-1001",   "trackingId": "AWB123456789",   "contactPhoneNumber": "9999999999",   "resolutionCode": "ACTF003",   "remarks": "Buyer confirmed that the shipment is no longer required." } ``` #### Report a fake attempt ```json {   "customerOrderNumber": "ORDER-1001",   "trackingId": "AWB123456789",   "contactPhoneNumber": "9999999999",   "resolutionCode": "ACTF004",   "remarks": "Buyer reports a fake attempt and requests redelivery.",   "proofOfCommunication": [     "https://evidence.example.com/ndr/buyer-confirmation.png",     "https://evidence.example.com/ndr/call-recording.mp3"   ],   "fakeAttemptBuyerCommunication": "BUYER_DENIED_ATTEMPT", "fakeAttemptBuyerCommunicationRemarks": "Buyer confirmed availability at the delivery address." } ``` ### Success response The response echoes the submitted request, with values resolved for the shipment and the authenticated seller. No separate resolution ID is returned. Example `200 OK` response: ```json {   "trackingId": "AWB123456789",   "resolutionCode": "ACTF001",   "timeline": "forwardTrackingTimeline",   "customerOrderNumber": "ORDER-1001",   "contactPhoneNumber": "9999999999",   "orderItemID": "123456",   "actorType": "seller",   "actor": "seller@example.com",   "clientEmail": "seller@example.com" } ``` A `200 OK` means the action was accepted and sent for processing. It does not mean the shipment has been delivered or returned; for `ACTF003`, it means RTO was requested. Track the shipment to follow the outcome. ### Errors and recovery Errors return a JSON `error` object. Example for a missing or invalid token: ```json {   "error": {     "errors": [       {         "domain": "global",         "reason": "bad request",         "message": "126: Invalid Token"       }     ],     "code": 400,     "message": "126: Invalid Token"   } } ``` | HTTP status in the application | Example message | Suggested action | | ------------------------------ | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `400` | `126: Invalid Token` | Generate a new access token as described in Authentication, then retry. | | `400` | `Tracking ID cannot be null.` | Supply the affected shipment's tracking ID. | | `400` | `Mobile number not found for tracking ID in orders table.` | No phone number is saved on the order for this tracking ID. Check the tracking ID, and raise a support ticket if it is correct. | | `400` | `101:TrackPayload not found` | Shipment tracking information is unavailable; contact support if this persists. | | `400` | `102:Deffered date not found.` | Include deferredDate when using ACTF002. | | `400` | `101:Unsupported proofOfCommunication format. Allowed: .JPG, .JPEG, .PNG, .MP3, .WAV` | Replace unsupported evidence references. | | `412` | `107: Order Already Delivered` | Stop submitting an NDR resolution for this shipment. | | `412` | `107: Invalid resolution action.` | Select an action available for this shipment's current NDR reason. | | `412` | `103:Invalid channelId` / `104:Invalid mobileNo` / `105:Invalid Customer Order Number` | Check shipment and account details with Eshopbox. | | `412` | `104:ndr data not found` | Contact support; action configuration is unavailable. | | `412` | `105: ndr_update_status not found` / `108: ndr status not updated` | Check shipment status before deciding whether to retry; contact support if unresolved. | The number at the start of each message is an application error code, not an HTTP status. Some codes are reused for different errors, so read the full message together with the HTTP status. #### Other errors These can be returned by the gateway or platform rather than the application. | HTTP status | Meaning | Suggested action | | ----------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `401` / `403` | Token missing, expired, or not authorised for this seller account. | Generate a new access token as described in Authentication, and check it belongs to the shipment's seller account. | | `404` | Endpoint not found. | Check the URL and path `/api/v2/ndrResolution`. | | `500` / `502` / `503` / `504` | Server or gateway error. The action may or may not have been recorded. | Do not resubmit automatically. Check the shipment status first, and raise a support ticket if the outcome is unclear. | If you receive an HTTP `400` message starting with `120:` saying an OTP was sent, the request used a buyer token and the resolution was not submitted. Use a seller access token as described in [Authentication](https://eshop.gitbook.io/eshopbox-developers/basics/authentication). ### Retries and integration checklist There is no published rate limit. Requests are not idempotent: sending the same action twice can create two actions. Do not retry automatically. If a request times out or returns a `5xx` error, check the shipment status before resubmitting. This matters most for `ACTF003` (RTO), which cannot be reversed. Before enabling the integration: 1. Raise a support ticket with Eshopbox for sandbox access, and generate an access token as described in [Authentication](https://eshop.gitbook.io/eshopbox-developers/basics/authentication). 2. Test each resolution code you plan to use against a sandbox shipment with an active NDR. 3. Check that `deferredDate` values fall between tomorrow and 3 days ahead (IST), and that evidence URLs are publicly accessible. 4. Check success responses, token failures, unavailable actions, and missing-field errors. 5. Record request time, tracking ID, action, HTTP status, and response for troubleshooting. Exclude access tokens from logs and restrict access to buyer data/evidence. 6. Track shipment status after each submission to confirm the outcome.