---
title: Invoices
description: Inspect invoice payments and their provider lifecycle.
---

# Invoices

Inspect invoice payments and their provider lifecycle.

## [GET /invoices](/api-reference/invoices#tag/invoices/GET/invoices)

List invoices

Retrieve invoices visible to the caller, newest first.

Authentication: X-Api-Key, or Bearer JWT + X-Api-Key

### Query parameters

- `limit` (`integer`, optional, >= 1, <= 1000, default 100) — The maximum number of items to return.
- `cursor` (`string`, optional) — Opaque pagination token from a previous response's nextCursor.
- `customerId` (`array of string`, optional) — Filter invoices by customer ID. When omitted, all customers visible to the caller are included.
- `status` (`array of InvoiceStatus`, optional) — Filter invoices by status.
- `fromDate` (`string`, optional, date) — Include invoices created on or after this date.
- `toDate` (`string`, optional, date) — Include invoices created on or before this date.
- `dueDateFrom` (`string`, optional, date) — Include invoices due on or after this date.
- `dueDateTo` (`string`, optional, date) — Include invoices due on or before this date.

### Responses

#### 200

Invoices retrieved successfully

Type: `object`

- `items` (`array of InvoiceListItem`, required)
  - `invoiceId` (`string`, required, example 094f10ca-616e-441c-b264-9a2305d6692d) — Unique identifier for the invoice.
  - `customerId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The customer this invoice collects payment from.
  - `number` (`string`, optional, example INV-2026-001) — The provider's human-readable invoice number or payment reference. Absent until the provider assigns one.
  - `invoiceNumber` (`string`, required, deprecated) — Deprecated. Read `number` instead.
  - `status` (`enum<string>`, required, one of UNKNOWN, DRAFT, ISSUED, SENT, PARTIALLY_PAID, PAID, OVERDUE, UNCOLLECTIBLE, VOID, CREDITED) — Current status of the invoice. — Current stage of the invoice lifecycle. - UNKNOWN: The provider status could not be mapped. - DRAFT: The invoice has not been issued. - ISSUED: The provider issued the invoice and it is awaiting payment. - SENT: Deprecated alias accepted in status filters. Responses use ISSUED. - PARTIALLY_PAID: Some, but not all, of the amount due has been paid. - PAID: The invoice has been paid. - OVERDUE: The invoice is past its due date and remains unpaid. - UNCOLLECTIBLE: The provider no longer expects to collect the invoice. - VOID: The invoice was canceled and is no longer collectible. - CREDITED: The invoice was settled by credit.
  - `paymentProvider` (`enum<string>`, optional, one of STRIPE, BILLOGRAM, example STRIPE) — The provider that issued and manages the invoice. — Payment service provider that processes the transaction.
  - `dueDate` (`string`, required, date, example 2026-08-31) — The date payment is due. Absent when the provider has no due date.
  - `subtotalAmountMinor` (`integer`, optional, int64, deprecated) — Deprecated. Get the invoice and read its related payment intent instead.
  - `totalAmountMinor` (`integer`, optional, int64, deprecated) — Deprecated. Read `amountDueMinor` instead.
  - `amountDueMinor` (`integer`, required, int64, example 3239) — The amount due when the invoice was issued, in minor units of the invoice currency.
  - `amountPaidMinor` (`integer`, required, int64, example 0) — The amount credited to the invoice, in minor units of the invoice currency.
  - `amountRemainingMinor` (`integer`, required, int64, example 3239) — The amount still unpaid, in minor units of the invoice currency.
  - `currency` (`string`, required, example USD) — The ISO 4217 currency code for the invoice amounts.
  - `issuedAt` (`string`, optional, date-time, example 2026-08-01T08:00:00Z) — When the provider issued the invoice. Absent while the invoice is a draft.
  - `sentAt` (`string`, optional, date-time, deprecated) — Deprecated. Read `issuedAt` instead.
  - `paidAt` (`string`, optional, date-time, example 2026-08-20T14:30:00Z) — When the invoice became paid.
  - `voidedAt` (`string`, optional, date-time, example 2026-08-10T09:00:00Z) — When the invoice was voided.
  - `hostedUrl` (`string`, optional, uri, example https://example.com/invoices/094f10ca-616e-441c-b264-9a2305d6692d) — The provider-hosted page where the customer can view and pay the invoice.
  - `invoiceUrl` (`string`, optional, uri, deprecated) — Deprecated. Read `hostedUrl` instead.
  - `pdfUrl` (`string`, optional, uri, example https://example.com/invoices/094f10ca-616e-441c-b264-9a2305d6692d.pdf) — Direct URL to the provider-generated invoice PDF.
  - `createdAt` (`string`, required, date-time, example 2026-08-01T08:00:00Z) — When the invoice record was created.
  - `updatedAt` (`string`, required, date-time, example 2026-08-01T08:00:00Z) — When the invoice record was last updated.
  - `metadata` (`object with string keys`, optional, deprecated) — Deprecated. Invoice metadata is not stored by the platform. — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
    - `*` (`string`, optional)
- `pagination` (`object`, required) — Cursor-based pagination information returned by list endpoints. Pass `nextCursor` as the `cursor` query parameter of the next request to fetch the following page.
  - `nextCursor` (`string | null`, required, example eyJvZmZzZXQiOjEwMH0) — Opaque token for fetching the next page. Null when no more results.

#### 400

The request was malformed or invalid.

Type: [Error](/api-reference/models.md#models/Error)

#### 401

Authentication is required to access this resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 403

Access to this resource is forbidden.

Type: [Error](/api-reference/models.md#models/Error)

#### 500

An unexpected error occurred on the server.

Type: [Error](/api-reference/models.md#models/Error)

### Example request

```bash
curl https://apiv2.example.com/api/v2/invoices \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'
```

## [GET /invoices/{invoiceId}](/api-reference/invoices#tag/invoices/GET/invoices/{invoiceId})

Get invoice

Retrieve an invoice's provider-backed lifecycle and balances, together with its related payment intent when available.

Authentication: X-Api-Key, or Bearer JWT + X-Api-Key

### Path parameters

- `invoiceId` (`string`, required) — The unique identifier of the invoice to retrieve.

### Responses

#### 200

Invoice retrieved successfully

Type: [Invoice](/api-reference/models.md#models/Invoice)

#### 400

The request was malformed or invalid.

Type: [Error](/api-reference/models.md#models/Error)

#### 401

Authentication is required to access this resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 403

Access to this resource is forbidden.

Type: [Error](/api-reference/models.md#models/Error)

#### 404

The requested resource was not found.

Type: [Error](/api-reference/models.md#models/Error)

#### 500

An unexpected error occurred on the server.

Type: [Error](/api-reference/models.md#models/Error)

### Example request

```bash
curl https://apiv2.example.com/api/v2/invoices/094f10ca-616e-441c-b264-9a2305d6692d \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY'
```

## [POST /invoices/{invoiceId}/mark-paid](/api-reference/invoices#tag/invoices/POST/invoices/{invoiceId}/mark-paid)

Mark invoice as paid

Mark an invoice as paid when you manage your own payment processing.

Use this when you handle payment collection while Telness manages invoice generation and taxation. Only available for invoices in `SENT` or `OVERDUE` status. Triggers subscription renewals and prevents service cancellation.

Authentication: X-Api-Key, or Bearer JWT + X-Api-Key

### Path parameters

- `invoiceId` (`string`, required) — The unique identifier of the invoice to mark as paid.

### Header parameters

- `X-Idempotency-Key` (`string`, optional, max length 256) — A unique key to ensure idempotency of requests. If a request with the same key has already been processed, the same result will be returned. The key must be unique for each distinct operation. Keys are expired after 24 hours, but we recommend using a new key for each request. Modified requests with the same idempotency keys are rejected with a `409 Conflict` status code.

### Request body (optional)

Type: `object`

- `paidAt` (`string`, optional, date-time, example 2024-02-10T14:30:00Z) — When the payment was received. If not provided, uses the current timestamp.
- `metadata` (`object with string keys`, optional) — Metadata to attach to the invoice. — A set of key-value pairs that can be attached to an object for storing additional information in a semi-structured format. Provided by API clients and returned as-is; the platform does not interpret the values.
  - `*` (`string`, optional)

### Responses

#### 200

Invoice successfully marked as paid.

Type: [Invoice](/api-reference/models.md#models/Invoice)

#### 400

The request was malformed or invalid.

Type: [Error](/api-reference/models.md#models/Error)

#### 401

Authentication is required to access this resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 403

Access to this resource is forbidden.

Type: [Error](/api-reference/models.md#models/Error)

#### 404

The requested resource was not found.

Type: [Error](/api-reference/models.md#models/Error)

#### 409

The request conflicts with the current state of the resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 500

An unexpected error occurred on the server.

Type: [Error](/api-reference/models.md#models/Error)

### Example request

```bash
curl https://apiv2.example.com/api/v2/invoices/123e4567-e89b-12d3-a456-426614174000/mark-paid \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "paidAt": "2024-02-10T14:30:00Z",
  "metadata": {
    "propertyName": "string"
  }
}'
```