---
title: Invoices
description: The invoices of the customers that the user manages.

---

# Invoices

The invoices of the customers that the user manages.


## [GET /invoices](/end-user-api/invoices#tag/invoices/GET/invoices)

List invoices

Retrieve invoices visible to the caller, newest first.

Authentication: X-Api-Key + Bearer JWT

### 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)
  - `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.
  - `createdAt` (`string`, required, date-time, example 2026-08-01T08:00:00Z) — When the invoice record was created.
  - `currency` (`string`, required, example USD) — The ISO 4217 currency code for the invoice amounts.
  - `customerId` (`string`, required, example f47ac10b-58cc-4372-a567-0e02b2c3d479) — The customer this invoice collects payment from.
  - `dueDate` (`string`, required, date, example 2026-08-31) — The date payment is due. Absent when the provider has no due date.
  - `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.
  - `invoiceId` (`string`, required, example 094f10ca-616e-441c-b264-9a2305d6692d) — Unique identifier for the invoice.
  - `issuedAt` (`string`, optional, date-time, example 2026-08-01T08:00:00Z) — When the provider issued the invoice. Absent while the invoice is a draft.
  - `number` (`string`, optional, example INV-2026-001) — The provider's human-readable invoice number or payment reference. Absent until the provider assigns one.
  - `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.
  - `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.
  - `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.
  - `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.
  - `updatedAt` (`string`, required, date-time, example 2026-08-01T08:00:00Z) — When the invoice record was last updated.
  - `voidedAt` (`string`, optional, date-time, example 2026-08-10T09:00:00Z) — When the invoice was voided.
  - `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](/end-user-api/models.md#models/Error)

#### 401

Authentication is required to access this resource.

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

#### 403

Access to this resource is forbidden.

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

#### 500

An unexpected error occurred on the server.

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

### Example request

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

## [GET /invoices/{invoiceId}](/end-user-api/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 + Bearer JWT

### Path parameters

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

### Responses

#### 200

Invoice retrieved successfully

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

#### 400

The request was malformed or invalid.

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

#### 401

Authentication is required to access this resource.

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

#### 403

Access to this resource is forbidden.

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

#### 404

The requested resource was not found.

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

#### 500

An unexpected error occurred on the server.

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

### Example request

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