---
title: "Get invoices by user ID"
method: GET
path: "/users/{userId}/invoices"
tags: ["Invoices"]
---

# Get invoices by user ID

`GET /users/{userId}/invoices`

## Request

- Base URL: `https://connect.clever.gy`
- URL: `https://connect.clever.gy/users/{userId}/invoices`
- Auth: API key in header `clevergy-api-key`

Retrieves all invoices associated with a specific user, including those without an uploaded PDF (`fileUrl` is null in that case).

## Path parameters

- `userId` string, required

## Response `200`

List of invoices retrieved successfully

- Invoice[]
  - `id` string, required: Unique identifier of the invoice
  - `issueDate` string, date, required: Date when the invoice was issued
  - `invoicePeriodFrom` string, date, required: Start of the invoice period
  - `invoicePeriodTo` string, date, required: End of the invoice period
  - `type` 'ELECTRICITY' | 'GAS' | 'WATER' | 'OTHER', required: Type of the contract
  - `cost` number, double, required: Total cost of the invoice
  - `contractId` string, required: ID of the contract associated with this invoice
  - `externalId` string: External identifier for the invoice, used for integration with third-party systems. Unique per Clevergy user; may be reused across different users.
  - `concepts` object: Additional invoice concepts as key-value pairs
  - `fileUrl` string, nullable: Signed URL to access the invoice PDF when available. Null when no file has been uploaded for this invoice.
  - `obtainMethod` 'REAL' | 'ESTIMATED': Method in which the invoice is obtained
  - `totalEnergyConsumption` number, double: Total energy consumption recorded in the invoice in kWh
  - `paymentDate` string, date: Date when the invoice was paid
  - `paymentStatus` 'PENDING' | 'PAID' | 'OVERDUE': Payment status of the invoice

## Other responses

- `401`: Unauthorized
- `404`: User not found
- `default`: Unexpected error

---

[API](https://skmtc.dev/clevergy/apis/clevergy-connect-api.md) - [All operations](https://skmtc.dev/clevergy/apis/clevergy-connect-api/llms.txt) - [OpenAPI document](https://skmtc.dev/clevergy/apis/clevergy-connect-api/revisions/d333c5eecb5b?raw)