---
title: "List invoices"
method: GET
path: "/invoices"
tags: ["Invoices"]
---

# List invoices

`GET /invoices`

## Request

- Base URL: `https://api.palomma.com/v1`
- URL: `https://api.palomma.com/v1/invoices`
- Auth: HTTP bearer

Returns a paginated list of invoices for the authenticated merchant.

## Query parameters

- `reference` string
- `customerDocumentNumber` string
- `contract` string
- `paymentDate` string, date
- `settlementDate` string, date
- `settlementCycle` string
- `limit` integer
- `cursor` string

## Response `200`

Paginated invoices list

- ListInvoicesResponse
  - `items` Invoice[], required: Invoices in the current page.
    - `id` string, required: Unique invoice identifier.
    - `reference` string: Merchant-provided invoice reference.
    - `status` 'ready' | 'paid' | 'cancelled' | 'chargeback', required: Invoice status: `ready` (payment link active), `paid`, `cancelled`, or `chargeback`.
    - `amount` number, required: Invoice amount in COP.
    - `description` string, required: Invoice description.
    - `contract` string, required: Contract identifier.
    - `expirationDate` string: Payment link expiration datetime (ISO 8601). Invoices expire 5 minutes after creation, so redirect the customer immediately. Once a transaction is in progress, it no longer expires until the transaction completes.
    - `customerDocumentNumber` string, required: Customer's document number.
    - `customerName` string: Customer's display name.
    - `createdAt` string, required: Invoice creation datetime (ISO 8601).
    - `paymentDate` string, date-time: When the invoice was paid. Present on paid and chargeback invoices.
    - `paymentMethod` 'pse' | 'nequiButton' | 'bancolombiaButton' | 'breb' | 'card': Payment method used. Present on paid and chargeback invoices.
    - `paymentSource` 'whatsapp' | 'portal' | 'link': Channel through which payment was made. Present on paid and chargeback invoices.
    - `paymentAmount` number: Amount actually paid in COP. Present on paid and chargeback invoices.
    - `settlementDate` string: Expected settlement date (`YYYY-MM-DD`). Present on paid and chargeback invoices.
    - `settlementTime` string: Expected settlement cycle. Present on paid and chargeback invoices.
    - `paymentId` string: Payment identifier. Present on paid and chargeback invoices.
    - `paymentUrl` string, uri, required: Palomma hosted payment page URL for this invoice.
  - `cursor` string, nullable: Cursor for the next page. `null` when there are no more pages.
  - `count` integer, required: Number of invoices returned in this page.

## Other responses

- `400`: Invalid request input
- `401`: Invalid or missing bearer token
- `500`: Unexpected server error

---

[API](https://skmtc.dev/palomma/apis/palomma-rentals-api.md) - [All operations](https://skmtc.dev/palomma/apis/palomma-rentals-api/llms.txt) - [OpenAPI document](https://skmtc.dev/palomma/apis/palomma-rentals-api/revisions/1ccb5e11c48d?raw)