# List rebills

`GET https://api.mothership.com/beta/rebills`

Sandbox: `https://sandbox.api.mothership.com/beta/rebills`

Lists the rebills your organization is charged for, newest first. Every filter is optional, and filters combine.

Lists the rebills your organization is charged for, newest first, in `results`. Each one has the same fields as [Retrieve a rebill](https://docs.mothership.com/reference/fetchrebillbyid).

Every filter is optional. Filters on different parameters must all match, and the values listed for one parameter are alternatives. So `status=scheduled,disputed` lists rebills in either status, and adding `shipmentId=MS5016101` narrows those to one shipment. A parameter can also be repeated instead of separated with commas.

An unknown status is a `400 INVALID_REQUEST` that names the statuses the API accepts. [Rebills](https://docs.mothership.com/reference/rebills#rebill-statuses) explains each one.

`total` counts the matches across every page. Keep increasing `page` while `hasMore` is `true`.

## Authorization

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

## Query parameters

- `page` (integer, optional, min 1): The page of results to return, starting at 1. Defaults to 1.
- `perPage` (integer, optional, min 1, max 100): The most rebills to return on a page, from 1 to 100. Defaults to 25.
- `status` (string, optional): Only rebills in one of these statuses, separated by commas, such as scheduled,disputed. The statuses are scheduled, disputed, finalized, processed, waived, voided, accepted, failed.
- `disputeStatus` (string, optional): Only rebills with a dispute in one of these statuses, separated by commas, such as info-needed. The statuses are under-review, with-carrier, info-needed, resolved-approved, resolved-waived-approved, resolved-charged, withdrawn, voided.
- `shipmentId` (string, optional): Only rebills for this shipment, by its reference number, such as MS5016101. A shipment that is not yours, or does not exist, matches nothing. List rebills for a shipment answers 404 for one instead.
- `createdAfter` (string<date-time>, optional): Only rebills created at or after this ISO timestamp. A date on its own, such as 2026-06-15, means midnight UTC at the start of that day.
- `createdBefore` (string<date-time>, optional): Only rebills created at or before this ISO timestamp. A date on its own, such as 2026-06-15, means midnight UTC at the start of that day, so pass 2026-06-15T23:59:59.999Z to include all of it.

## Responses

### 200

A page of rebills, inside `data`.

- `data` (object, required)
  - `results` (array of objects, required): The rebills on this page, newest first.
    - `id` (string, required): The ID of the rebill.
    - `referenceNumber` (string, required): The reference number of the rebill, such as MSSR5016101. A second rebill on the same shipment ends in -2.
    - `status` (string, required): Where the rebill is in its review. The Rebills reference page explains each status. One of: `scheduled`, `disputed`, `finalized`, `processed`, `waived`, `voided`, `accepted`, `failed`.
    - `shipmentId` (string, required): The reference number of the shipment the carrier billed for, such as MS5016101.
    - `proNumber` (string, required, nullable): The carrier's PRO number on the bill.
    - `amountCents` (integer, required): The total of the line items in cents.
    - `processingFeeCents` (integer, required): The carrier bill processing fee in cents, or 0 when there is none. It may apply if the rebill is finalized or a dispute is lost.
    - `totalAmountCents` (integer, required): amountCents plus processingFeeCents.
    - `currency` (string, required): Three-letter ISO currency code, in lowercase. Always 'usd'.
    - `disputableUntil` (string, required, nullable): ISO string of when the review window ends. Until then you can accept or dispute each line item, and after it the rebill is charged as billed.
    - `invoiceId` (string, required, nullable): The ID of the invoice that charges the rebill, once its review is over. Pass it to Retrieve an invoice. Null before then, and when there is nothing to charge.
    - `lineItems` (array of objects, required): The charges the carrier billed.
      - `id` (string, required): The ID of the line item.
      - `type` (string, required): The kind of charge. The Rebills reference page explains each type. One of: `bill-of-lading-correction`, `reconsignment`, `delivery-attempt`, `driver-labor`, `expedited-delivery`, `additional-freight`, `lumper-fee`, `pickup-address-change`, `pickup-attempt`, `reactivated-shipment`, `return-shipment`, `detention`, `incorrect-weight`, `liftgate-pickup`, `liftgate-delivery`, `incorrect-dimensions`, `appointment`, `residential-pickup`, `residential-delivery`, `inside-pickup`, `inside-delivery`, `excessive-length`, `commodity-class-up`, `tradeshow`, `blind-shipment`, `government-airport-gas-mine-or-refinery-delivery`, `container-freight-station-pickup`, `container-freight-station-delivery`, `storage-fee`, `amazon-distribution-center`, `call-before-delivery`, `carrier-or-service-upgrade`, `limited-truck-access-pickup`, `limited-truck-access-delivery`, `hazmat`, `toll-fee`, `freight-coverage`, `oversize-fee`, `scheduled-delivery`, `documentation`, `cancellation-fee`, `cargo-details-updated`.
      - `name` (string, required): The name of the charge, as the dashboard shows it.
      - `amountCents` (integer, required): The amount of the charge in cents.
      - `explanation` (string, required): What the charge is and why the carrier billed it, in Markdown.
      - `avoidanceGuidance` (string, required): How to avoid this charge on later shipments, in Markdown.
      - `disputeEvidence` (string, required): What a dispute of this charge needs to succeed, in Markdown.
      - `disputeRequiresDocuments` (boolean, required): Whether a dispute of this charge must include supporting documents.
      - `acceptedAt` (string, required, nullable): ISO string of when you accepted the charge.
      - `dispute` (object, required, nullable): The dispute on this line item, or null when the charge has not been disputed.
        - `id` (string, required): The ID of the dispute.
        - `lineItemId` (string, required): The ID of the line item the dispute is about.
        - `status` (string, required): Where the dispute is. The Rebills reference page explains each status. One of: `under-review`, `with-carrier`, `info-needed`, `resolved-approved`, `resolved-waived-approved`, `resolved-charged`, `withdrawn`, `voided`.
        - `reason` (string, required, nullable): The reason you picked when you disputed the charge, such as Wasn't performed.
        - `message` (string, required, nullable): Your explanation of why the charge is wrong.
        - `infoRequested` (string, required, nullable): What Mothership last asked you to send while the status was info-needed, or null when Mothership has not asked for anything.
        - `fileIds` (array of strings, required): The files you attached to the dispute. Download one with Retrieve a file.
        - `createdAt` (string, required): ISO string of when you disputed the charge.
        - `updatedAt` (string, required): ISO string of when the dispute last changed.
    - `createdAt` (string, required): ISO string of when the rebill was created.
    - `updatedAt` (string, required): ISO string of when the rebill last changed.
    - `statusUpdatedAt` (string, required): ISO string of when the status last changed.
  - `page` (integer, required): The page of results returned, starting at 1.
  - `perPage` (integer, required): The most rebills a page holds.
  - `total` (integer, required): How many rebills match, across every page.
  - `hasMore` (boolean, required): True if a later page has more rebills.

## Example request

```bash
curl --request GET \
  --url 'https://sandbox.api.mothership.com/beta/rebills' \
  --header "Authorization: Bearer $MOTHERSHIP_API_TOKEN" \
  --header 'Accept: application/json'
```

## Example response (200)

```json
{
  "data": {
    "results": [
      {
        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "referenceNumber": "MSSR5016101",
        "status": "scheduled",
        "shipmentId": "MS5016101",
        "proNumber": "1234567890",
        "amountCents": 8500,
        "processingFeeCents": 1500,
        "totalAmountCents": 10000,
        "currency": "usd",
        "disputableUntil": "2026-03-29T17:00:00.000Z",
        "invoiceId": null,
        "lineItems": [
          {
            "id": "1b4e28ba-2fa1-4d3b-a3f5-ef19b5a7633b",
            "type": "incorrect-weight",
            "name": "Incorrect Weight",
            "amountCents": 8500,
            "explanation": "The carrier weighed the freight at its terminal and found it heavier than the weight on the bill of lading, so it billed for the difference.",
            "avoidanceGuidance": "Weigh each handling unit, packaging included, and enter that weight when you book.",
            "disputeEvidence": "A scale ticket or a photo of the freight on a certified scale showing the weight you booked, taken before pickup.",
            "disputeRequiresDocuments": true,
            "acceptedAt": null,
            "dispute": null
          }
        ],
        "createdAt": "2026-03-19T17:00:00.000Z",
        "updatedAt": "2026-03-19T17:00:00.000Z",
        "statusUpdatedAt": "2026-03-19T17:00:00.000Z"
      }
    ],
    "page": 1,
    "perPage": 25,
    "total": 1,
    "hasMore": false
  }
}
```