---
title: "An invoice's dunning journey"
description: "Every collection attempt on the invoice (with the refusal, the payment method, whether it reached the gateway, and what triggered it), the dunning events around them, and a projection of what dunning…"
canonical_url: "https://twominutebilling.com/help/developers/api-reference/invoices/an-invoice-s-dunning-journey"
---
# An invoice's dunning journey

> Every collection attempt on the invoice (with the refusal, the payment method, whether it reached the gateway, and what triggered it), the dunning events around them, and a projection of what dunning…

<api-operation method="GET" path="/v1/businesses/{biz}/invoices/{inv}/dunning_journey">
<template v-slot:docs="">

Every collection attempt on the invoice (with the refusal, the payment method, whether it reached the gateway, and what triggered it), the dunning events around them, and a projection of what dunning will do next if each retry fails: the remaining retries, any hold, the deadline attempt and the final action. The projection runs the engine's own rules (schedule, adaptive timing, network retry limits, dunning period) from the latest decline; a different decline, a new payment method or a manual collection changes it.

## Path parameters

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Required
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        biz
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      Business id (biz_…)
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        inv
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      <strong>
        yes
      </strong>
    </td>
    
    <td>
      The invoice's id (inv_…).
    </td>
  </tr>
</tbody>
</table>

## Response

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        object
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The object type; always <code>
        dunning_journey
      </code>
      
      . One of <code>
        dunning_journey
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        period_ends_at
      </code>
    </td>
    
    <td>
      <code>
        string · ISO-8601
      </code>
    </td>
    
    <td>
      When the dunning period ends (ISO-8601 UTC), or null if there is no deadline.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        history
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      What has happened so far, oldest first.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        projection
      </code>
    </td>
    
    <td>
      <code>
        array of object
      </code>
    </td>
    
    <td>
      What dunning plans to do next. Null when dunning is not going to act.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        projection_note
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      Why there is no plan, when <code>
        projection
      </code>
      
       is empty. One of <code>
        settled
      </code>
      
      , <code>
        stopped
      </code>
      
      , <code>
        exhausted
      </code>
      
      , <code>
        auto_collect_off
      </code>
      
      , <code>
        dunning_off
      </code>
      
      , <code>
        customer_excluded
      </code>
      
      , <code>
        below_minimum
      </code>
      
      , <code>
        null
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

## Status codes

<table>
<thead>
  <tr>
    <th>
      Status
    </th>
    
    <th>
      Meaning
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        200
      </code>
    </td>
    
    <td>
      Dunning journey
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        404
      </code>
    </td>
    
    <td>
      No such invoice
    </td>
  </tr>
</tbody>
</table>
</template>

<template v-slot:request="">

```bash [Request]
curl "$TMBILLING_URL/v1/businesses/biz_XXXXXXXXXXXX01/invoices/inv_XXXXXXXXXXXX01/dunning_journey" \
  -H "Authorization: Bearer $TMBILLING_API_KEY"
```

</template>

<template v-slot:response="">
<code-group>

```json [200 OK]
{
  "object": "dunning_journey",
  "period_ends_at": "2026-04-14T09:30:00Z",
  "history": [
    {
      "kind": "attempt",
      "at": "2026-03-14T09:30:00Z"
    }
  ],
  "projection": [
    {
      "kind": "retry",
      "at": "2026-03-14T09:30:00Z"
    }
  ],
  "projection_note": null
}
```

```json [404 Not Found]
{
  "error": {
    "type": "invalid_request_error",
    "message": "No such invoice"
  }
}
```

</code-group>
</template>
</api-operation>


## Sitemap

See the full [sitemap](https://twominutebilling.com/sitemap.md) for all pages.