List Invoices

Retrieve a paginated list of invoices with optional filtering and sorting

GET /invoices

cURL

curl "https://api.alguna.io/invoices?page=1&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -G "https://api.alguna.io/invoices" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=10' \
  --data-urlencode 'filters=[{"field":"status","operator":"in","value":"issued,paid"},{"field":"due_date","operator":"gte","value":"2024-01-01T00:00:00Z"}]' \
  --data-urlencode 'sort=due_date:desc'

const invoices = await alguna.invoices.list({
  page: 1,
  limit: 25,
  filters: [
    { field: "status", operator: "in", value: "issued,paid" },
    { field: "due_date", operator: "gte", value: "2024-01-01T00:00:00Z" }
  ],
  sort: "due_date:desc"
});

Response

{
    "items": [
        {
            "id": "ZVzWRFnt",
            "accountId": "aBsZxlLh",
            "currency": "USD",
            "description": "Platform subscription",
            "billingPeriodStart": "2024-02-01T00:00:00Z",
            "billingPeriodEnd": "2024-02-29T23:59:59Z",
            "status": "upcoming",
            "total": "200.00",
            "billingPeriod": "Feb 01, 24 - Feb 29, 24",
            "createdAt": "2024-01-24T16:36:52.78883Z",
            "updatedAt": "2024-01-26T19:30:37.734294Z"
        },
        {
            "id": "jqsKFrxO",
            "accountId": "JXvYcskd",
            "currency": "USD",
            "description": "Monthly seats",
            "billingPeriodStart": "2024-02-01T00:00:00Z",
            "billingPeriodEnd": "2024-02-29T23:59:59Z",
            "status": "upcoming",
            "total": "500.00",
            "billingPeriod": "Feb 01, 24 - Feb 29, 24",
            "createdAt": "2024-01-24T16:25:48.027798Z",
            "updatedAt": "2024-01-26T19:30:38.083477Z"
        }]
}

Retrieves a paginated list of all invoices. You can filter and sort the results using query parameters.

Query Parameters

page · integer · default: "1"

The page number to retrieve (1-indexed).

limit · integer · default: "10"

The number of invoices to return per page. Must be one of: 5, 10, 25, 50, or 100. Values exceeding 100 are capped automatically.

filters · string

A JSON-encoded array of filter objects. Each filter object has the following properties:

Show Filter Object

field · string · required

The field to filter on. Supported fields:

Field	Operators	Description
status	eq, in	Invoice status (e.g. draft, upcoming, issued, paid, void)
account_id	eq	The account ID associated with the invoice
subscription_id	eq	The subscription ID associated with the invoice
autopay	eq	Whether the invoice is set to auto-pay (true or false)
invoicing_date	eq, gte, lte	The invoicing date (ISO 8601 format)
issue_date	eq, gte, lte	The issue date (ISO 8601 format)
due_date	eq, gte, lte	The due date (ISO 8601 format)
paid_date	eq, gte, lte	The paid date (ISO 8601 format)
tag_ids	in	Tag IDs associated with the invoice

operator · string · required

The comparison operator.

Operator	Description
eq	Exact match
in	Matches any value in a comma-separated list
gte	Greater than or equal to (date fields)
lte	Less than or equal to (date fields)

value · string · required

The value to match against. For the in operator, use comma-separated values. For date operators, use ISO 8601 format.

sort · string

Sort specification in field:order format. Order is either asc (ascending) or desc (descending).

Sortable fields: invoicing_date, issue_date, due_date, paid_date, account_name, status.

cURL

curl "https://api.alguna.io/invoices?page=1&limit=25" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -G "https://api.alguna.io/invoices" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode 'page=1' \
  --data-urlencode 'limit=10' \
  --data-urlencode 'filters=[{"field":"status","operator":"in","value":"issued,paid"},{"field":"due_date","operator":"gte","value":"2024-01-01T00:00:00Z"}]' \
  --data-urlencode 'sort=due_date:desc'

const invoices = await alguna.invoices.list({
  page: 1,
  limit: 25,
  filters: [
    { field: "status", operator: "in", value: "issued,paid" },
    { field: "due_date", operator: "gte", value: "2024-01-01T00:00:00Z" }
  ],
  sort: "due_date:desc"
});

Response

Response

{
    "items": [
        {
            "id": "ZVzWRFnt",
            "accountId": "aBsZxlLh",
            "currency": "USD",
            "description": "Platform subscription",
            "billingPeriodStart": "2024-02-01T00:00:00Z",
            "billingPeriodEnd": "2024-02-29T23:59:59Z",
            "status": "upcoming",
            "total": "200.00",
            "billingPeriod": "Feb 01, 24 - Feb 29, 24",
            "createdAt": "2024-01-24T16:36:52.78883Z",
            "updatedAt": "2024-01-26T19:30:37.734294Z"
        },
        {
            "id": "jqsKFrxO",
            "accountId": "JXvYcskd",
            "currency": "USD",
            "description": "Monthly seats",
            "billingPeriodStart": "2024-02-01T00:00:00Z",
            "billingPeriodEnd": "2024-02-29T23:59:59Z",
            "status": "upcoming",
            "total": "500.00",
            "billingPeriod": "Feb 01, 24 - Feb 29, 24",
            "createdAt": "2024-01-24T16:25:48.027798Z",
            "updatedAt": "2024-01-26T19:30:38.083477Z"
        }]
}

items · array

List of invoice objects.

Show Invoice Object

id · string

The Alguna ID of the invoice.

accountId · string

The Alguna ID of the account associated with the invoice.

currency · string

The ISO 4217 currency in which the invoice is billed.

description · string

The description or memo for the invoice.

billingPeriodStart · string

The start date of the billing period for the invoice (RFC 3339 timestamp).

billingPeriodEnd · string

The end date of the billing period for the invoice (RFC 3339 timestamp).

status · string

The status of the invoice. For more info on invoice statuses see the invoice status guide.

total · string

The total amount of the invoice as a decimal string e.g., “200.00”.

billingPeriod · string

The formatted billing period for the invoice.

createdAt · datetime

The date and time at which the invoice was created.

updatedAt · datetime

The date and time at which the invoice was last updated.

pageCount · integer

Total number of pages available based on the current limit.

limit · integer

The number of items per page used for this request.