> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usenash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Refunds & incidents

> Report a delivery incident, optionally request a refund, and track the refund request through review.

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](/api-reference/job/create-delivery-incident) (`POST /v1/jobs/{jobId}/tasks/{taskId}/delivery_incident`). The incident is recorded against a specific task on a job (delivery). The request requires:

* `raiseIncident` (boolean) — flag the delivery to be reviewed by Nash's team (reviews aren't real-time — don't rely on this 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

<Warning>
  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.
</Warning>

When an incident is a refund request, you classify it with a subtype. The supported refund-request types are:

| Subtype                      | Meaning                                    |
| ---------------------------- | ------------------------------------------ |
| `arrived_late`               | The delivery arrived later than expected   |
| `delivered_early`            | The delivery arrived earlier than expected |
| `delivered_to_wrong_address` | The order went to the wrong place          |
| `missing_or_incorrect_items` | Items were missing or incorrect            |
| `never_delivered`            | The order was never delivered              |
| `poor_delivery_experience`   | A general quality issue with the delivery  |
| `other`                      | Any 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](/api-reference/job/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](/api-reference/job/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`

<Info>
  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.
</Info>

## Statuses

A refund request carries a `status` that reflects where it is in review. Statuses you may see include:

| Status            | Meaning                                                   |
| ----------------- | --------------------------------------------------------- |
| `draft`           | The request has been started but not submitted for review |
| `under_review`    | The request is being reviewed                             |
| `needs_attention` | The request requires manual intervention                  |
| `approved`        | The request has been approved                             |
| `nash_approved`   | The request has been approved by Nash                     |
| `denied`          | The request has been declined                             |
| `cancelled`       | The request was cancelled                                 |

<Note>
  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.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Create delivery incident" icon="triangle-exclamation" href="/api-reference/job/create-delivery-incident">
    Report a problem with a delivery and optionally request a refund.
  </Card>

  <Card title="Get refund requests" icon="list" href="/api-reference/job/get-refund-requests">
    List refund requests for a task or job.
  </Card>

  <Card title="Get refund request" icon="receipt" href="/api-reference/job/get-refund-request">
    Retrieve a single refund request, including its status.
  </Card>
</CardGroup>