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

# Invoices

> List and retrieve invoice records linked to payments.

An invoice is created alongside a payment and represents the billing record for a checkout session. Use these endpoints to look up invoices by customer, payment, or invoice ID.

## GET /api/gateway/invoices

Returns a paginated list of invoices.

```bash theme={null}
curl "https://dash.getopenrails.com/api/gateway/invoices?limit=20"
```

### Query parameters

| Parameter    | Type   | Description                                          |
| ------------ | ------ | ---------------------------------------------------- |
| `limit`      | number | Maximum number of records to return. Defaults to 20. |
| `customerId` | string | Filter by customer `cus_*` ID.                       |
| `paymentId`  | string | Filter by payment `pay_*` ID.                        |
| `invoiceId`  | string | Filter to a specific invoice by `inv_*` ID.          |
| `status`     | string | Filter by invoice status.                            |

### Response

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "id": "inv_xyz789",
      "object": "invoice",
      "customerId": "cus_7G42M9",
      "paymentId": "pay_abc123",
      "sessionId": "chk_nimbus_1056",
      "amount": 116,
      "currency": "USD",
      "status": "paid",
      "created": "2026-05-24T17:37:00Z"
    }
  ],
  "hasMore": false
}
```

## GET /api/gateway/invoices/{invoiceId}

Fetches a single invoice by its `inv_*` ID.

```bash theme={null}
curl https://dash.getopenrails.com/api/gateway/invoices/inv_xyz789
```

### Response

```json theme={null}
{
  "id": "inv_xyz789",
  "object": "invoice",
  "customerId": "cus_7G42M9",
  "paymentId": "pay_abc123",
  "sessionId": "chk_nimbus_1056",
  "amount": 116,
  "currency": "USD",
  "status": "paid",
  "metadata": {
    "order_id": "ord_284"
  },
  "created": "2026-05-24T17:37:00Z"
}
```

### Status values

| Status | Meaning                                    |
| ------ | ------------------------------------------ |
| `open` | Invoice created; payment not yet received. |
| `paid` | Payment confirmed and invoice closed.      |
| `void` | Invoice voided before payment.             |

To look up an invoice by payment, use the `paymentId` filter on the list endpoint or navigate from the [payment record](/api-reference/payments) directly.