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

# GET /api/v1/invoices/:invoiceId — Fetch Invoice Details

> GET /api/v1/invoices/:invoiceId — retrieves an invoice with full details including settlement history, usage events, and related records.

Fetch a full invoice record to check payment status, review settlement history, or inspect associated usage events. The response includes all related objects — service, payment plan, user, subscription, settlements, and usage events — so you have a complete picture of the invoice lifecycle in a single call.

```
GET https://api.retempo.xyz/api/v1/invoices/:invoiceId
```

## Path Parameters

<ParamField path="invoiceId" type="string" required>
  The unique identifier of the invoice to retrieve.
</ParamField>

## Response

A successful request returns HTTP `200 OK` with the full invoice object and all related records.

<ResponseField name="invoice" type="object">
  The requested invoice with all related records.

  <Expandable title="invoice fields">
    <ResponseField name="id" type="string">Unique identifier for the invoice.</ResponseField>
    <ResponseField name="serviceId" type="string">ID of the associated service.</ResponseField>
    <ResponseField name="paymentPlanId" type="string">ID of the associated payment plan.</ResponseField>
    <ResponseField name="userId" type="string">ID of the billed user.</ResponseField>
    <ResponseField name="subscriptionId" type="string | null">ID of the linked subscription, or `null`.</ResponseField>
    <ResponseField name="status" type="string">Current invoice status: `DRAFT`, `OPEN`, `VOID`, `EXPIRED`, or `PAID`.</ResponseField>
    <ResponseField name="amount" type="string">Billed amount as a decimal string with six decimal places.</ResponseField>
    <ResponseField name="currency" type="string">Currency of the invoice.</ResponseField>
    <ResponseField name="dueAt" type="string | null">Due date, or `null` if not set.</ResponseField>
    <ResponseField name="paidAt" type="string | null">Datetime the invoice was paid. Populated only after a settlement is confirmed.</ResponseField>
    <ResponseField name="createdAt" type="string">ISO 8601 datetime the invoice was created.</ResponseField>
    <ResponseField name="service" type="object">Nested service object.</ResponseField>
    <ResponseField name="paymentPlan" type="object">Nested payment plan object.</ResponseField>
    <ResponseField name="user" type="object">Nested user object.</ResponseField>
    <ResponseField name="subscription" type="object | null">Nested subscription object if one is linked, otherwise `null`.</ResponseField>
    <ResponseField name="settlements" type="array">List of all settlements recorded against this invoice.</ResponseField>
    <ResponseField name="usageEvents" type="array">List of all usage events linked to this invoice.</ResponseField>
  </Expandable>
</ResponseField>

### 200 — Invoice retrieved

```json theme={null}
{
  "invoice": {
    "id": "clz1invoice999",
    "serviceId": "clz1abc2def3ghi4",
    "paymentPlanId": "clz1plan567",
    "userId": "clz1user111",
    "subscriptionId": null,
    "status": "OPEN",
    "amount": "49.000000",
    "currency": "USDC",
    "dueAt": "2025-07-01T00:00:00.000Z",
    "paidAt": null,
    "createdAt": "2025-06-01T10:15:00.000Z",
    "service": {
      "id": "clz1abc2def3ghi4",
      "name": "DataStream Pro",
      "status": "ACTIVE"
    },
    "paymentPlan": {
      "id": "clz1plan567",
      "name": "Pro Monthly",
      "amount": "49.000000",
      "currency": "USDC"
    },
    "user": {
      "id": "clz1user111",
      "email": "subscriber@example.com"
    },
    "subscription": null,
    "settlements": [],
    "usageEvents": []
  }
}
```

## Example Request

```bash theme={null}
curl https://api.retempo.xyz/api/v1/invoices/clz1invoice999
```

## Error Codes

| Status          | Message                  | Condition                              |
| --------------- | ------------------------ | -------------------------------------- |
| `404 Not Found` | `Invoice was not found.` | No invoice exists for the provided ID. |

<Tip>
  Check the `paidAt` field — it is populated only after a settlement against this invoice is confirmed. Until then it is `null` regardless of the invoice `status`.
</Tip>