Skip to main content
When a delivery goes wrong — a damaged package, missing items, or a late arrival — you can report a delivery incident against the affected task. An incident can optionally request a refund, which Nash tracks as a refund request you can poll until it’s resolved.

​
Reporting a delivery incident

Report an incident with Create delivery incident (POST /v1/jobs/{jobId}/tasks/{taskId}/delivery_incident). The incident is recorded against a specific task on a job. The request requires:
  • raiseIncident (boolean) — flag the delivery to be reviewed by Nash’s team (not for urgent issues)
  • incidentNotes (string) — details about what happened
It also accepts:
  • incidentType — either REFUND_REQUEST or COURIER_NOTES
  • incidentSubtype — the refund-request type (see below)
  • incidentFileUrl / incidentFileUrls — links to supporting file attachments
  • requestAmountDeliveryFeeCents, requestAmountOrderValueCents, requestAmountTipCents — the amounts you’re requesting back
To request a refund, at least one of requestAmountDeliveryFeeCents, requestAmountOrderValueCents, or requestAmountTipCents must be provided. All provided values must be non-negative integers (≥ 0), and at least one must be greater than zero.
When an incident is a refund request, you classify it with a subtype. The supported refund-request types are:
SubtypeMeaning
arrived_lateThe delivery arrived later than expected
delivered_earlyThe delivery arrived earlier than expected
delivered_to_wrong_addressThe order went to the wrong place
missing_or_incorrect_itemsItems were missing or incorrect
never_deliveredThe order was never delivered
poor_delivery_experienceA general quality issue with the delivery
otherAny other reason

​
Refund requests

A refund request captures what you asked for, what was granted, and the supporting context. Retrieve them by task or job with Get refund requests (GET /v1/refund-requests) — at least one of taskId or jobId is required — or fetch a single request by its ID with Get refund request (GET /v1/refund-request/{id}). A refund request includes, among other fields:
  • Identity and linkage: id, jobId, taskId, organizationId, createdAt, and resolutionDate
  • The classification and context: incidentSubtype, incidentNotes, and the courier’s response
  • The requested amounts: requestAmountCents plus the per-bucket requestAmountDeliveryFeeCents, requestAmountOrderValueCents, and requestAmountTipCents
  • The granted amounts: refundAmountCents plus the per-bucket refundAmountDeliveryFeeCents, refundAmountOrderValueCents, and refundAmountTipCents, in the given currency
  • The current status and any proofOfRefund
Amounts are split into three buckets — delivery fee, order value, and tip — on both the requested and granted sides, so you can see exactly which part of a delivery was refunded.

​
Statuses

A refund request carries a status that reflects where it is in review. The status values defined in the API are:
StatusMeaning
draftThe request has been started but not submitted for review
under_reviewThe request is being reviewed
needs_attentionThe request requires manual intervention
approvedThe request has been approved
nash_approvedThe request has been approved by Nash
deniedThe request has been declined
cancelledThe request was cancelled
The status values above are the set defined in the Nash API. The plain-language meanings are summarized here for convenience; treat the status string itself as the source of truth when reconciling a request’s state in your system.

​
Next steps

Create delivery incident

Report a problem with a delivery and optionally request a refund.

Get refund requests

List refund requests for a task or job.

Get refund request

Retrieve a single refund request, including its status.