---
title: Invoices
description: Manage invoices and invoice items.
---

# Invoices

Manage invoices and invoice items.

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

List invoices

Retrieve a paginated list of invoices with optional filtering by status, customer, or date range.

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 IDs
- `status` (`array of InvoiceStatus`, optional) — Filter invoices by status
- `fromDate` (`string`, optional, date) — Filter invoices created from this date
- `toDate` (`string`, optional, date) — Filter invoices created up to this date
- `dueDateFrom` (`string`, optional, date) — Filter invoices with due date from this date
- `dueDateTo` (`string`, optional, date) — Filter invoices with due date up to 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 is for.
  - `invoiceNumber` (`string`, required, example INV-2024-001) — Human-readable invoice number.
  - `status` (`enum<string>`, required, one of DRAFT, SENT, PAID, VOID, OVERDUE, example SENT) — Current status of the invoice. — Current stage of the invoice lifecycle. - DRAFT: Being prepared; not yet visible to the customer. - SENT: Delivered to the customer and awaiting payment. - PAID: Payment has been received. - VOID: Canceled and no longer collectible. - OVERDUE: Past its due date without payment.
  - `dueDate` (`string`, required, date, example 2024-02-15) — When payment is due.
  - `subtotalAmountMinor` (`integer`, optional, int64, example 2999) — Sum of all line items before taxes, fees, and discounts, in minor units of the invoice currency (e.g., 2999 = $29.99 when the currency is USD).
  - `totalAmountMinor` (`integer`, optional, int64, example 2989) — Total amount the customer owes for this invoice after taxes, fees, and discounts, in minor currency units.
  - `currency` (`string`, optional, example USD) — The ISO 4217 currency code for all invoice amounts (e.g., "USD").
  - `sentAt` (`string`, optional, date-time, example 2024-01-15T10:00:00Z) — When the invoice was sent to the customer (if status is sent or later).
  - `paidAt` (`string`, optional, date-time, example 2024-02-10T14:30:00Z) — When the invoice was paid (if status is paid).
  - `voidedAt` (`string`, optional, date-time, example 2024-02-05T09:00:00Z) — When the invoice was voided (if status is void).
  - `invoiceUrl` (`string`, optional, uri, example https://invoices.yourapp.com/094f10ca-616e-441c-b264-9a2305d6692d) — Hosted URL where customer can view the invoice.
  - `createdAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the invoice was created.
  - `updatedAt` (`string`, required, date-time, example 2024-01-15T10:00:00Z) — When the invoice was last updated.
  - `metadata` (`object with string keys`, optional) — 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 details of a specific invoice by its identifier, including status, due date, and payment information.

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"
  }
}'
```