# List modified invoices

`GET https://api.mothership.com/beta/invoices/modified_since`

Sandbox: `https://sandbox.api.mothership.com/beta/invoices/modified_since`

Takes an ISO 8601 timestamp and lists references to the invoices created or modified on or after it.

Many invoice properties (such as status) are computed and can change frequently depending on a variety of factors. Some events that can cause an invoice to be modified are payments being applied, credits applied, refunds issued, and cancellations processed.

When one of these events occurs, the invoice has effectively been modified. In order to keep your system in sync, this endpoint allows you to list all invoices that have been modified since a start date. Then call [Retrieve an invoice](https://developers.mothership.com/reference/fetchinvoicebyid) for each one.

> [!NOTE] Modifications
> Not all modifications will result in mutated data. Your system should expect versions of invoices to occasionally be identical.

## Pagination

This endpoint is paginated and can return up to 100 invoice references at a time. For your convenience, the response will tell you how many total invoices have been modified since your start date (`timestamp`) along with the current page you have retrieved and the index of the next page. Don't include the `page` parameter on the first call.

| Parameter | Required | Description |
| --- | --- | --- |
| `timestamp` | Yes | ISO timestamp of the on or after date to query. |
| `page` | No | A cursor for pagination across multiple pages of results. Don't include this parameter on the first call. Use the `nextPage` value returned in a previous response to request subsequent results. |
| `limit` | No | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. |

## Authorization

Send your API token as a Bearer token: `Authorization: Bearer <token>`.

## Query parameters

- `page` (string, optional): Pagination cursor. Leave it out on the first call, then pass the `nextPage` value from the previous response to get the next page.
- `limit` (string, optional): Number of results to return, from 1 to 100. Defaults to 10.
- `timestamp` (string, required): ISO 8601 timestamp. Invoices created or modified on or after it are returned.

## Responses

### 200

The results, inside `data`.

- `data` (object, required)
  - `invoices` (array of objects, required)
    - `id` (string, required): Invoice ID.
    - `lastModifiedAt` (string, required): The most recent timestamp the invoice was modified at.
  - `hasMore` (boolean, required): True if there are more records to fetch.
  - `total` (number, optional): The total number of invoices that are modified on or after the date.
  - `limit` (number, optional): Number of results requested for this page. The last page can return fewer.
  - `currentPage` (number, optional): Index of this page of results.
  - `nextPage` (number, optional, nullable): Index of the next page of results, if there is one.

## Example request

```bash
curl --request GET \
  --url 'https://sandbox.api.mothership.com/beta/invoices/modified_since?timestamp=2026-03-01T00%3A00%3A00.000Z' \
  --header "Authorization: Bearer $MOTHERSHIP_API_TOKEN" \
  --header 'Accept: application/json'
```

## Example response (200)

```json
{
  "data": {
    "invoices": [
      {
        "id": "9b2e6d41-0c7a-4f3e-8d15-6a4c2e9f1b70",
        "lastModifiedAt": "2026-03-02T18:21:07.000Z"
      }
    ],
    "hasMore": true,
    "total": 24,
    "limit": 10,
    "currentPage": 1,
    "nextPage": 2
  }
}
```