# Retrieve an invoice

`GET https://api.mothership.com/beta/invoices/{invoiceId}`

Sandbox: `https://sandbox.api.mothership.com/beta/invoices/{invoiceId}`

Retrieves an invoice.

> [!WARNING] Invoice modifications
> Invoices have many computed properties that can change before settling (such as status). Please use the [List all modified invoices](https://developers.mothership.com/reference/listmodifiedinvoices) endpoint to ensure your records are kept up-to-date.

## Invoice statuses

The value of `status` can be in one of the following states.

| Status | Description |
| --- | --- |
| `open` | The invoice has not been paid, or payment is still processing. |
| `paid` | The invoice has been fully paid. |
| `unpaid` | Listed in the spec for compatibility. The API does not return it today. |
| `pastDue` | The invoice is not fully paid and past its due date. |
| `void` | The invoice has been voided and is not due for payment, nor has been paid previously. |

Each line item's `type` is listed in [Invoice line items](https://developers.mothership.com/reference/invoice-line-items). Line item amounts are in cents.

## Authorization

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

## Path parameters

- `invoiceId` (string, required): ID of the invoice to fetch.

## Responses

### 200

The invoice, inside `data`.

- `data` (object, required)
  - `id` (string, required): The ID of the invoice.
  - `createdAt` (string, required): When the invoice was created, as an ISO 8601 string.
  - `updatedAt` (string, required): When the invoice was last updated, as an ISO 8601 string.
  - `lineItems` (array of objects, required): The individual line items that make up the invoice.
    - `quantity` (number, required): The quantity for this line item.
    - `type` (string, required): The type of line item. One of: `additional`, `base-shipment`, `booking-fee`, `cancellation-fee`, `claim`, `credit-card-processor-fee`, `cross-dock`, `freight-coverage`, `fuel-surcharge`, `fba-appointment-delivery`, `home-delivery`, `late-fee`, `local-inside-delivery`, `oversize-fee`, `residential-delivery`, `residential-pickup`, `revenue-share-adjustment`, `scheduled-delivery`, `scheduled-pickup`, `toll-fee`, `twic-charge`, `appointment-delivery`, `international-transaction-fee`, `domestic-credit-card-processing-fee`, `international-credit-card-processing-fee`, `cross-border-transaction-fee`, `financing-fee`, `dispute-fee`, `digital-wallet-processing-fee`.
    - `unitAmountCents` (number, required): The unit amount in cents for this line item.
    - `totalAmountCents` (number, required): The total amount in cents for this line item.
    - `discountAmountCents` (number, required): The discount amount in cents for this line item.
    - `taxAmountCents` (number, required): The tax amount in cents for this line item.
    - `description` (string, required): A human-readable description of the line item.
  - `status` (string, required): The status of the invoice. One of: `open`, `paid`, `unpaid`, `pastDue`, `void`.
  - `referenceNumber` (string, required): Reference number of the invoice. It is not guaranteed to be unique, or to match the reference number of the entity it belongs to.
  - `description` (string, required): The description of the invoice.
  - `entityType` (string, required): The invoiceable entity type, most commonly 'shipment'. Payment processing fee invoices use 'payment'. One of: `shipment`, `claim`, `statement`, `payment`.
  - `entityId` (string, required): ID of the entity the invoice is for. For a shipment, the shipment reference number when available. For a payment processing fee invoice, the finance payment UUID.
  - `dueDate` (string, optional): When the invoice must be paid by, as an ISO 8601 string.
  - `total` (number, optional): Invoice total, in US cents.
  - `amountDue` (number, optional): Amount still due on the invoice, in US cents.
  - `credits` (array of objects, optional): The credits applied to the invoice.
    - `id` (string, required): The ID of the credit.
    - `createdAt` (string, required): When the credit was applied, as an ISO 8601 string.
    - `amount` (number, required): Amount of the credit, in US cents.
  - `payments` (array of objects, optional): The payments applied to the invoice.
    - `id` (string, required): The ID of the payment.
    - `createdAt` (string, required): When the payment was applied, as an ISO 8601 string.
    - `amount` (number, required): Amount of the payment, in US cents.
  - `currency` (string, optional): Three-letter ISO currency code, in lowercase. Defaults to 'usd'.

## Example request

```bash
curl --request GET \
  --url 'https://sandbox.api.mothership.com/beta/invoices/9b2e6d41-0c7a-4f3e-8d15-6a4c2e9f1b70' \
  --header "Authorization: Bearer $MOTHERSHIP_API_TOKEN" \
  --header 'Accept: application/json'
```

## Example response (200)

```json
{
  "data": {
    "id": "3f1c2a9e-5b7d-4e8a-9c61-2d4f8b0e7a15",
    "createdAt": "2026-03-19T17:00:00.000Z",
    "updatedAt": "2026-03-19T17:00:00.000Z",
    "dueDate": "2026-04-18",
    "total": 1,
    "amountDue": 1,
    "credits": [
      {
        "id": "3f1c2a9e-5b7d-4e8a-9c61-2d4f8b0e7a15",
        "createdAt": "2026-03-19T17:00:00.000Z",
        "amount": 1
      }
    ],
    "lineItems": [
      {
        "quantity": 2,
        "type": "additional",
        "unitAmountCents": 7900,
        "totalAmountCents": 7900,
        "discountAmountCents": 7900,
        "taxAmountCents": 7900,
        "description": "T-shirts"
      }
    ],
    "payments": [
      {
        "id": "3f1c2a9e-5b7d-4e8a-9c61-2d4f8b0e7a15",
        "createdAt": "2026-03-19T17:00:00.000Z",
        "amount": 1
      }
    ],
    "currency": "usd",
    "status": "open",
    "referenceNumber": "PO-1042",
    "description": "T-shirts",
    "entityType": "shipment",
    "entityId": "3f1c2a9e-5b7d-4e8a-9c61-2d4f8b0e7a15"
  }
}
```